Microsoft Commerce Server 2000

  • Commerce Server Online Help

  • Commerce Server Solution Sites

  • Microsoft Product Support Services

  • Commerce Server Support

  • Commerce Server 2000 ISV Partners

  • Microsoft Accessibility Web Site

  • White Papers

  • Business Desk Tutorial

  • Feedback
Copyright © 1996–2000 Microsoft Corporation.
All rights reserved.


Getting Started

Microsoft Commerce Server 2000 provides a set of tools for the site developer, system administrator, and business manager to develop, deploy, and manage commerce applications for the Web. The Getting Started topics are designed to familiarize you with the Commerce Server features and tools that you need to build successful e-commerce solutions that scale with your business needs and integrate with your existing systems and data.

This section contains:

  • Introducing Commerce Server 2000. Describes Commerce Server and the features that are new in this release. Describes how Commerce Server is accessible to people with disabilities.

  • Using Commerce Server Help. Describes the Commerce Server documentation, how to use it, and where to find additional resources.

  • Installing Commerce Server. Explains the hardware and software requirements for installing Commerce Server. Explains how to install and uninstall Commerce Server Business Desk.

  • Commerce Server Architecture. Describes how Commerce Server can be used with other .NET technologies. Describes the architecture of Commerce Server Manager and Commerce Server Business Desk.

  • Commerce Server Concepts. Describes key Commerce Server features and how they work.

  • Commerce Server Security. Describes key security features in Commerce Server.

  • Planning Your Commerce Server Installation. Describes the planning considerations you must address to ensure a successful implementation of Commerce Server. Describes the tools available for migrating a Site Server 3.0 Commerce Edition site to Commerce Server.


Introducing Commerce Server 2000

Microsoft Commerce Server 2000 is a comprehensive, integrated commerce solution that provides ready-to-use features and tools to quickly develop, deploy, and manage commerce applications for the Web. You can use Commerce Server to build scalable business-to-consumer (B2C) and business-to-business (B2B) site applications.

Commerce Server provides business managers with the ability to easily analyze and manage business operations. It includes sophisticated analytical capabilities and a real-time feedback loop that empower business managers to respond to the changing needs of customers and partners. By creating highly dynamic, personalized commerce sites, you can optimize the customer experience, encourage repeat business, and successfully compete in the e-commerce marketplace.

This section contains:

  • Commerce Server Features at a Glance. Describes the Commerce Server features, and how you can use them to update and manage your site.

  • Development Tools. Describes the tools for the site developer, including the Solution Sites and the Commerce Server Software Development Kit (SDK).

  • Administration Tools. Describes the tools for the system administrator, including Commerce Server Manager and Commerce Server Site Packager.

  • Site Management Features. Describes the Commerce Server Business Desk, and how you can use it together with other Commerce Server features to manage your site.

  • Pipeline Features. Describes the Commerce Server pipeline features.

  • Accessibility for People with Disabilities. Describes the accessibility features of Commerce Server.

  • Contacting Microsoft Technical Support. Describes Microsoft technical support services, and provides Web links and phone numbers for accessing technical support.


Commerce Server Features at a Glance

Commerce Server features function together seamlessly, enabling you to provide merchandising, catalog display, customer service, and order capture and receipt.

The following table provides an overview of the Commerce Server features.

Commerce Server Feature Description
Product Catalog System
  • Create and update catalogs of products to sell.

  • Import catalogs of products from other data sources. Import Commerce Server catalogs in XML or CSV format.

  • Export catalogs in XML format.

  • Add integrated search capabilities making it easy for users to find what they need:
    • Category search. Browse by product category.

    • Free-text search. Find products by full or partial name or property.

    • Property search. Find products based on a property value, such as Price < $10.

    • Specification search. Refine the search request until the product is found.
  • Build custom catalogs with special pricing for groups of users.

  • Apply discounts to products.

  • Identify which products are selling by running Commerce Server reports.

  • Exchange catalog data with vendors by using Microsoft BizTalk Server 2000.
Profiling System
  • Manage millions of users and organizations.

  • Enable users to manage their own profile information and to research the status of their order.

  • Build profiles for any business-related entity, such as users and organizations.

  • Determine what information to collect about users visiting your site.

  • Determine what information to display to specific users, such as custom catalogs.

  • Analyze profile information to determine who is visiting your site.

  • Create target expressions to match content to users.

  • Create advertising, discount, and direct mail campaigns to target specific user groups.
Business Analytics System
  • Import large amounts of site usage data collected from different data sources into the Commerce Server Data Warehouse, and manage the data.

  • Analyze site effectiveness by running Commerce Server reports, or by creating your own custom reports.

  • Identify specific groups of users by running a report, and then export the results to a list. Use the list in a direct mail campaign, or to update the properties of the users so you can target merchandise or content to them.

  • Review collected data to identify hidden trends and new customer segments, and to view the properties of the segments.

  • Provide intelligent cross-sell capabilities, and dynamically recommend products to users as they navigate your site.
Targeting System
  • Personalize the buying experience with targeted merchandising.

  • Deliver the optimal content for a given user in a given context.

  • Create, analyze, and manage personalized and targeted discounts, and direct marketing and advertising campaigns.

  • Add predictive capabilities to your Web site.

  • Target ads or discounts to users of a specific profile. For example, you can target ads to female users who visit your site three times a week, and who have purchased three or more products.

  • Create and schedule campaigns for customers who compete within the same industry. The competing ads are never shown on the same page.

  • Charge your advertising customers based on the number of ad requests or clicks they want their ads to receive.

  • Charge your advertising customers based upon the page on which they want their ad to display.
Business Process Pipelines
  • Customize your order, targeting, and merchandising processes.

  • Define and link together the stages of a business process.


Development Tools

The Commerce Server development tools are designed to help site developers build and customize sites quickly, and transfer them to customers. Commerce Server includes new development tools and enhancements to Site Server 3.0 and Site Server 3.0, Commerce Edition (SSCE).

Solution Sites

Commerce Server SDK

Programmer's Documentation

Commerce Server 2000 Resource Kit

Solution Sites

Commerce Server has replaced the Site Server 3.0 Starter Sites with three Solution Sites. The Solution Sites are development reference sites that provide an integrated set of features included in Commerce Server. The Solution Sites provide merchandising, catalog display, customer service, and order capture and receipt.

Because the Solution Sites provide comprehensive e-commerce functionality, you can use them as a starting point for developing your own Web sites, and, when you are ready, add functionality that is specific to your business.

Commerce Server includes the following Solution Sites:

  • Blank. You can use this Solution Site as a starting point for building your own custom site. It includes all of the Commerce Server resources. The Blank site is included in the Commerce Server box.

  • Retail. You can use this Solution Site as a starting point for building a business-to-consumer site. It includes business-to-consumer functionality for personalization, merchandising, catalog search, customer service, and business analytics. It includes the Customer Service, which enables users to manage their own profile information and to view their order status. The Retail site is available from http://www.microsoft.com/commerceserver/solutionsites.

  • Supplier. You can use this Solution Site as a starting point for building a business-to-business site. It uses Active Directory in Microsoft Windows 2000 to provide secure user authentication and group access permissions. It provides purchase order and requisition handling, XML-based catalog updates and exchange, and trading partner self-service. It includes the Partner Service, which enables a delegated administrator (a contact at a supplier company) to manage organizational information, purchase orders, and order status for that supplier company. The Supplier site is available from http://www.microsoft.com/commerceserver/solutionsites.

Commerce Server SDK

The Commerce Server Software Development Kit (SDK) includes header files, sample code, sitelets, and tools for developing e-commerce solutions with Commerce Server.

Header Files

Sample Code

Sitelets

Tools

Header Files

The Include folder of the SDK contains the header and Interface Description Language (IDL) files required to use and extend the services provided by Commerce Server in Microsoft Visual C++.

Sample Code

The following is a partial list of the sample code provided in the SDK:

  • Administration Samples. A reference for creating Commerce Server resources, integrating with and extending Commerce Server Manager, building custom Commerce Server Site Packager components, and building custom Commerce Server Business Desk modules.

  • Business Desk Module Framework. A working code base from which to develop new Business Desk modules. This code base demonstrates how to use XML data-islands, and includes the Business Desk widgets for creating a rich, Web-based user interface (UI) to allow for non-technical administration of your Commerce Server site. This sample provides you with an Edit page for implementing the Edit widget, a List page for implementing the List widget, and a Response page for handling requests from the Business Desk UI. Additionally, the AddModuleToConfig.vbs script is provided to demonstrate how to install new Business Desk modules into an existing Business Desk.

  • Business Desk Installer. A simple COM component that demonstrates how to use the Administration API in conjunction with the Internet Information Services (IIS) 5.0 metabase, and how to use the Microsoft Extensible Markup Language (MSXML) parser to install new Business Desk modules into an existing Business Desk.

  • Custom Site Packager Component. A component that demonstrates how to package and unpack data specific to the site resources that you create in a Commerce Site Package during the packaging/unpacking process. The Custom Site Packager component is a Microsoft Visual Basic ActiveX dynamic-link library (DLL) that implements the IPuP interface (required for Custom Site Packager components), packages data stored in a Microsoft SQL Server™ database, and unpacks the data into a specified site.

  • Data Warehouse Schema Browser. A schema browser you use to view Commerce Server Data Warehouse classes, class properties, data members, and class relationships as they are defined in the logical schema. This sample demonstrates how to use the Commerce Server OLE DB provider to access the logical schema of the Data Warehouse.

  • CSF Score Headlines. A sample that demonstrates how to extend the Targeting System using custom Content Selection Framework (CSF) Cache Loading and Scoring components. The CSF Score Headlines sample is based on the premise that you want to target headlines to users of your site based on the age of the headline and what headlines have been seen the most. It demonstrates integration with the Targeting System using both Visual C++ and Visual Basic.

  • CSF Debug Utils. A set of Active Server Pages (ASP) that you include in your scripts to dump the contents of a CSF cache and to trace the scoring logic applied for any given content request. The CSF Score Headlines sample demonstrates how to use these debugging utilities.

  • CSF DB Utils. A set of SQL scripts that purge the CSF, Expression Evaluator, and List Manager databases of all content.

Sitelets

In addition to the traditional code samples provided in the Commerce Server 2000 SDK, small scale Commerce Server 2000 sites (referred to as "sitelets") are also included. The sitelets demonstrate how to use the API sets from ASP pages, without integrating them with the rest of the run-time services for Commerce Server 2000. Run the sitelets to help you isolate and understand the APIs for a particular feature, without manually filtering extraneous code unrelated to the task you want to perform.

The following sitelets are provided in the Commerce Server 2000 SDK:

  • Advertising Sitelet. Demonstrates how to use the Profiling System in combination with the Targeting System to display targeted advertisements.

  • Auction Sitelet. Demonstrates how to use the Auction component to implement Winning Bid auctions. It includes a custom Business Desk module designed for managing auctions.

  • Catalog Sitelet. Demonstrates how to use the Product Catalog System to offer catalog browse and search functionality on your e-commerce site.

  • Discount Sitelet. Demonstrates how to leverage targeted discounts in the order capture process of your Web site.

  • Order Sitelet. Demonstrates how to use Commerce Server to implement an order capture process on your Web site.

  • Passport Sitelet. Demonstrates how to integrate Passport single sign-on capability with the Profiling System. With this capability, you and your customers can benefit from a single sign-on authentication service, while still being able to use the Profiling System for targeting users, managing user data, and so on.

  • Profile Sitelet. Demonstrates how to use the Profiling System to register and authenticate users on your e-commerce site.

Tools

The Commerce Server 2000 SDK includes a set of tools to help you simplify and speed up the development process for building sites run by Commerce Server, building products that integrate with Commerce Server, and building add-on components for Commerce Server.

  • Pipeline Component Wizard for Visual Basic. This tool provides Visual Basic developers with a release and deployment (RAD) environment for building Business Processing Pipeline components. To install the Pipeline Component Wizard for Visual Basic, register the PipelineCompWizard.dll file in the VB Pipe Wizard folder of the SDK Tools. For example, C:\Program Files\Microsoft Commerce Server\SDK\Tools\VB Pipe Wizard.

  • Pipeline Component Wizard for Visual C++. This tool consists of a group of files that you add to your Visual C++ 6.0 installation to automate the creation of Commerce Server pipeline components. The Pipeline Component Wizard creates the object definition and implementation files that contain the function prototypes for all of the interfaces that you need to implement to create a fully functional pipeline component. In addition, the Pipeline Component Wizard creates a property page for your project, in which you add the controls through which users set component properties.

  • Pipeline Component Registration Tool. This tool helps you register pipeline components for stage affinity. You register the pipeline component on the computer in which the tool is being run and you can export the data to a Registry Script (.reg) file for deployment to other servers. The Pipeline Component Registration Tool is located in the Registration Tool folder of the SDK. For example, C:\Program Files\Microsoft Commerce Server\SDK\Tools\Registration Tool.

Programmer's Documentation

Commerce Server 2000 Help provides detailed documentation that explains how to customize Commerce Server. For example, the documentation includes instructions for:

  • Building Business Desk Modules

  • Building Pipeline Components

  • Working with the Data Warehouse

  • Extending the Content Selection Framework

  • Integrating with BizTalk Server

  • Modifying Your Site for an International Audience

In addition, for each of the Commerce Server objects, Commerce Server 2000 Help includes example code.

Commerce Server 2000 Resource Kit

The Commerce Server 2000 Resource Kit provides detailed information about developing e-commerce solutions with Commerce Server. It is available from Microsoft Press.

The Commerce Server 2000 Resource Kit includes information about the following topics:

  • Developing multi-language, multi-currency sites

  • Implementing identification and authentication

  • Extending the Business Analytics System

  • Implementing complex pricing schemes

  • Developing with the Profiling System

  • Modifying order processing

  • Integrating with SAP

  • Integrating with J.D. Edwards OneWorld

  • Testing your site

  • Maximizing performance

See Also

Using Site Packager

Programmer's Reference


Administration Tools

Commerce Server includes the following administration tools for system administrators to manage resources, sites, applications, and Web servers:

  • Commerce Server Manager. A tool you use to manage and configure Commerce Server resources, sites, applications, and Web servers. The Microsoft Management Console (MMC), a Windows-based interface that is included in Microsoft Windows 2000, hosts Commerce Server Manager.

    Commerce Server Manager provides a common framework for managing Web sites within a single, integrated interface. The functionality in Commerce Server Manager is not available through either Web-based or command line administration. Instead, most of this functionality is accessed and manipulated through COM objects, so it is possible for you to write a Windows Scripting Host (WSH) script or an ASP page to extend the administration environment. For information about Commerce Server Manager, see Administering Commerce Server.

    Note

    • You cannot use Commerce Server Manager to manage Site Server 3.0 or Site Server 3.0, Commerce Edition (SSCE). For information about migrating a site from Site Server, see Migrating from Site Server 3.0.
  • Commerce Server Site Packager. A deployment tool that you use to package your site and its applications and resources into a single file, and then move that file to another environment. You use it to package your Commerce Server site (including the IIS metabase settings), file system, resources from the Administration database, and SQL Server databases into a single file. You also use it to unpack the Commerce Server site (or portions of it) onto other computers.

    For example, after developing or updating your site, you can use Site Packager to package and move your site from your development environment to your test environment, and then finally to your production environment.

    In most cases, Site Packager is used for the initial deployment of your site. For future deployments, incremental updates, and rollbacks, use other tools such as Microsoft Application Center 2000 or other content management products. For information about Commerce Server Site Packager, see Using Site Packager.

See Also

Administering Commerce Server

Using Site Packager

Migrating from Site Server 3.0


Site Management Features

Commerce Server Business Desk is an extensible tool that business managers use to manage and analyze their Web sites. For example, you use Business Desk features to update pricing information in your catalogs, target new advertisements to specific users, and then run reports to measure how these changes affect site productivity.

Business Desk has two parts: the Business Desk application and the Business Desk client.

  • Business Desk application. The management tool you use to configure, manage, and analyze your site. After you install Commerce Server, you can unpack a Solution Site to install a Business Desk application. Business Desk is accessible from any computer running Microsoft Internet Explorer 5.5, providing you with secure remote access.

  • Business Desk client. The client software that is installed locally on your computer, providing the interface to the Business Desk application. When you first access the Business Desk application (via a URL), the Business Desk client is downloaded and installed onto your computer. It is recommended that the computer on which you run the Business Desk client have a high-speed connection to the Business Desk application.

Business Desk is an enhancement of Site Server 3.0 and Site Server 3.0, Commerce Edition (SSCE) Web-based Administration (WebAdmin), a browser-based interface used to administer Site Server from a remote location. WebAdmin was designed for system administrators. Business Desk, however, is designed for business managers: people who understand business goals, strategies, and processes for creating and running a successful e-commerce Web site, but who may not have the technical knowledge for administering a server application.

The following new Business Desk features were designed for the business manager to use to easily manage a Web site:

Profiling System

Product Catalog System

Targeting System

Business Analytics System

Profiling System

In Site Server 3.0 and SSCE, the profile system collects user information. In the Commerce Server Profiling System, however, you can collect any information you specify for any business-related item. For example, you can collect profile information for anonymous users, a context (such as the date and time of a visit), or an organization.

The Profiling System consists of the Profiles resource, managed using Commerce Server Manager, and the Users modules, managed using Commerce Server Business Desk. Profile information is stored in the Profiles data store, which can be Active Directory, SQL Server, or both. You can export data from the Profiles data into the Data Warehouse, and then using the Business Desk you can analyze the profile data that is collected.

Note

  • Commerce Server does not include the Site Server 3.0 Membership Directory. For information about migrating profile information from the Site Server 3.0 Membership Directory to Commerce Server, see Migrating from Site Server 3.0.

Product Catalog System

The Commerce Server Product Catalog System is a new feature for importing, exporting, creating, and managing online catalogs. By using the Catalog modules in Business Desk, business managers can create catalogs of products, and add and update product data. You do not need any specialized knowledge about the databases that store your product data, even if you are assembling a catalog of products from different sources, such as several different suppliers. For example, you can:

  • Import catalogs that are in Extensible Markup Language (XML) or comma-separated value file (CSV) format.

  • Export catalogs in XML or CSV format.

  • Exchange catalogs with trading partners using BizTalk Server.

  • Price products and categories.

  • Add, update, and delete categories and products, and the data they contain.

  • Apply discounts to products or groups.

  • Run reports to analyze catalog activity.

  • Apply multiple search mechanisms so users visiting your site can find what they need in your catalog.

Catalog data is stored in the Commerce Server database, which is a SQL Server (7.0 or 2000) database. You can export catalog data from the Commerce Server database to the Data Warehouse, and then using Business Desk you can analyze the catalog data that is collected.

A site developer can use the Product Catalog System COM objects to customize your Product Catalog System.

Targeting System

The Targeting System is a high-performance, versatile platform that business managers use to target content to any business-related item or condition. It includes a consistent targeting model so business managers can use only one technology to target different business conditions.

The Targeting System includes the following features:

  • Campaigns. The Campaigns modules in Business Desk are an extended version of the Ad Manager feature in SSCE. The Campaigns modules are tightly integrated with both the Profiling System and the Product Catalog System through expressions. Expressions enable you to target advertisements to users and to apply discounts to products. The Campaigns modules are also integrated with the Business Analytics System so that you can analyze the success of your campaigns.

  • Content Selection Framework. The Content Selection Framework (CSF) is a pipeline-based system that determines the content to be delivered for advertising and discount campaigns. CSF allows multiple pieces of content to be retrieved as a recordset with only one call, resulting in significant speed.

    The CSF architecture supports an open scoring system that enables site developers to change the algorithm used to determine which piece of content is delivered. In addition, debugging code can be used to monitor events that occur during the scoring process.

  • Expression Builder. In Commerce Server, Expression Builder provides an intuitive user interface that business managers use to create expressions that target content to any business item that has a profile.

    Business Desk users access Expression Builder through the Campaign Manager and Campaign Expressions modules. However, Expression Builder is designed so that site developers can easily embed its functionality and user interface in other Business Desk modules or other Web applications.

  • List Manager. List Manager is a service with a Business Desk user interface that enables you to import and export lists of user profiles. It is integrated with the Business Analytics System enabling you, for example, to run reports to generate a list of profiles, and then import that list to the List Manager. You can also import segment data to the List Manager. After you import a list of user profiles to List Manager, you can export it to the Users module, and then update the profile information as needed, for example, to add properties to user profiles for targeting. You can also use the list to run a direct mail campaign.

  • Commerce Server Direct Mailer. Direct Mailer is a fast, scalable Windows 2000 service that you use to send personalized e-mail messages from a Web page, or non-personalized mailings from a flat text file, to large groups of recipients. Direct Mailer can be used as a stand-alone process or integrated into the Campaigns modules in Business Desk. Direct Mailer tracks e-mails, recording which ones are sent and which ones are clicked (opened), enabling you to analyze the success of a direct mail campaign.

    The Direct Mailer pipeline is used to process lists of recipients. You can add new components to the pipeline, integrate the components with line-of-business systems, or replace them with components supplied by third parties.

Business Analytics System

The Business Analytics System includes enhancements to the Site Server 3.0 Analysis and Predictor features to significantly increase functionality, efficiency, and processing speed.

The Business Analytics System includes the following new features and enhancements:

  • Analysis. The Analysis modules in Business Desk include the functionality of the Report Writer feature in Site Server 3.0, and many additional enhancements. You can use the Analysis modules to:
    • Run reports on site activity.

    • View and manipulate the reports in Internet Explorer using Microsoft PivotTables and Microsoft PivotCharts.

    • Export the reports to the Profiling System or Targeting System, and then use the data for updating profiles or for targeting content.

    • Customize reports.

    You can run reports much more quickly in Commerce Server than was possible in Site Server because the data required for many of the reports is stored in an Online Analytical Processing (OLAP) database.

  • Data Warehouse. The Commerce Server Data Warehouse replaces the Site Server 3.0 Analysis database. The Data Warehouse is a combination of a SQL Server database, an OLAP database, and a set of processes that a system administrator uses to import and maintain data. The Data Warehouse imports a large amount of data collected from several different data sources. It collects day-to-day operational data about users who visit your site: user profile data, transaction data, and click-history data. It also collects product data and advertising data. This data is gathered from your Web server logs, the Commerce Server databases, and other data sources that you specify. The Data Warehouse then manages the data in the database for the purpose of business analytics.

    You can configure Data Warehouse properties to specify how data is to be imported.

  • Predictor. The Predictor resource is a Windows 2000 service that is optionally installed with Commerce Server 2000 as part of a complete or a custom installation. The Predictor resource enables you to provide predictive capabilities for your Web site, for example, to display product recommendations.

    The Commerce Server Predictor resource includes several enhancements that make it more efficient than the Site Server 3.0 Predictor. It also includes additional functionality, enabling you to analyze your models.

    Predictor includes the following enhancements and functionality:

    • Segment models. In addition to creating Prediction models, you can now create Segment models. A Segment model, also known as a cluster model, partitions users into segments, or groups of users who share specific characteristics or behavior. You can use these segments for subsequent marketing.

    • Model viewers. You can analyze Prediction models using the Prediction Model Viewer accessed through Commerce Server Manager, and you can analyze Segment models using the Segment Viewer module in Business Desk.

    • Model-based algorithm. In Site Server 3.0, Predictor used a data-based algorithm for making predictions. The new model-based algorithm uses decision trees (dependency networks) for making predictions, which is more accurate and significantly faster.

    • Automated data analysis. Predictor includes features for automatic and efficient data sampling, improved methods for selecting the attributes to model, and an algorithm that automatically "guesses" the optimal distribution for modeling those attributes.

    • Offline building of models. Models are not built on the Web server, so the building process does not impact the performance of your site.

    • All Web servers use the same model. In Site Server 3.0, each Web server had to build its own model. In Commerce Server, all Web servers use the same model so fewer resources are consumed building models.

See Also

Commerce Server Concepts

Business Desk Users

Business Desk Catalogs

Business Desk Campaigns

Business Desk Analysis


Pipeline Features

Commerce Server 2000 includes several new pipeline features that provide for more flexible order handling, easier shipping method maintenance, more flexible discount handling, and greater efficiency in pipeline loading and execution. These features include:

  • High-precision currency handling

  • Multiple shipment handling

  • Discount handling

  • Pipeline pooling

See Also

Working with Pipelines

Currency Enhancements

Multiple-shipment Shipping Architecture

Discount Objects

Pooled Pipelines


Accessibility for People with Disabilities

Microsoft is committed to making its products and services easier for everyone to use. This section provides information about features that make Commerce Server 2000 more accessible to people with disabilities.

For information about using your keyboard to navigate within the Help Viewer, see Help Viewer Keyboard Shortcuts.

For a list of the keyboard shortcuts that are used frequently within Commerce Server Business Desk, see Using Keyboard Shortcuts.

Microsoft Windows 2000 Accessibility Features

For Additional Accessibility Information

Microsoft Windows 2000 Accessibility Features

Commerce Server 2000 supports the following accessibility features of Windows 2000. These features can be used in Commerce Server Business Desk, Commerce Server Manager, and the Pipeline Editor.

  • Magnifier. Enlarges a portion of your screen in a separate window for easier viewing.

  • Narrator. Reads information on your screen, including dialog box names, menus, entered text, and so on. Narrator provides a minimum level of accessibility so that people who are blind or who have low vision can interact with Commerce Server 2000 during configuration or emergency situations.

    Note

    • Narrator is available only with U.S. English.
  • On-Screen Keyboard. Displays a virtual keyboard so you can enter information by using a pointing device, such as a mouse or a switch input device. On-Screen Keyboard is compatible with many, but not all, keyboards and keyboard settings.

For more information about using these and other accessibility options, see "Accessibility for People with Disabilities" in the Windows 2000 Server Help.

For Additional Accessibility Information

For information about accessibility options, in Windows 2000 Help, see "Accessibility for People with Disabilities" in the "Getting Started with Windows 2000" book.

For information about accessibility options in Microsoft SQL Server, see "Accessibility for People with Disabilities" in SQL Server Books Online.

To learn more about Microsoft products available for people with disabilities, visit www.microsoft.com/enable/. This site contains:

  • Complete information about accessibility services for Microsoft products.

  • Information on a wide variety of third-party hardware and software products that are available to make it easier to use personal computers.

  • An overview of other accessibility products, services, and resources that are available from Microsoft and other organizations.


Contacting Microsoft Technical Support

Product name: Microsoft Commerce Server 2000

Support options: Paid Professional Support

Online support: Microsoft Product Support Services Web site (support.microsoft.com/directory/directory/onlinesrpro.asp)

Phone support: See additional topics in this section for telephone contact details in the United States.

Support hours: Available 24 hours a day, 7 days a week — including holidays.

Worldwide: Support options, hours, and cost in your country may differ from the United States, please check with your local office for details.

This section contains:

  • Professional Support Options

  • Additional Support Options

  • International Support

Note

  • Microsoft support services are subject to Microsoft's then-current prices, terms, and conditions, which are subject to change without notice.


Professional Support Options

Professional support options provide advanced support for experts and businesses. Visit our customized support sites for pay-per-incident assistance online (US $195) and phone (US $245) by experts trained to assist business professionals. To purchase support incidents in advance, call Professional Support Sales at (800) 936-3500. If you are calling from Canada, Professional support is available by calling (800) 805-4440 from 8:00 a.m. – 8:00 p.m. Monday – Friday, Eastern Time.

Submit your incident online (US $195)

  • Microsoft Product Support Services Web site (support.microsoft.com/directory/directory/onlinesrpro.asp)

Get additional information on our support offerings:

  • Professional Support for Developers

  • Professional Support for IT Professionals

  • Professional Support for Value Add Partners, Resellers, Consultants

  • Professional Support for Microsoft Certified Solution Providers

  • Professional Support for Original Equipment Manufacturers (OEMs)

Submit your incident over the phone (US $245):

Area of expertise | Phone number
Developers | (800) 936-5800
IT Professionals | (800) 936-4900
Partners (resellers/consultants) | (888) 456-5570
Microsoft Certified Solution Providers | (888) 677-9444
Original Equipment Manufacturers | (800) 936-2197
System Builders | (888) 456-5570

Note

  • Microsoft support services are subject to Microsoft's then-current prices, terms, and conditions, which are subject to change without notice.


Additional Support Options

If the professional support offerings do not apply to you or your business, the following support options are also available and may help you locate the support service which best meets your needs.

Premier

Premier support provides proactive access to specialized technical expertise needed by large enterprises, maximizing business value and minimizing total cost. See our customized support sites for Premier customers, or view the following facts sheets for more information. For more information, contact your Microsoft account representative or call Microsoft Enterprise Support Sales at (800) 936-3200 in the United States or Canada.

  • Microsoft Premier Support for Enterprise Systems

  • Microsoft Premier Support for Developers

  • Microsoft Premier Support for MCSPs

  • Microsoft Premier Support for Original Equipment Manufacturers (OEMs)

  • Microsoft Authorized Premier Support

Alliance

Alliance support is designed to help very large enterprise customers to successfully develop, deploy, and manage enterprise systems built around a broad range of high-quality Microsoft solutions for the server and the desktop. See the following facts sheets for more information. For more information, contact your Microsoft account representative or call Microsoft Enterprise Support Sales at (800) 936-3200 in the United States or Canada.

  • Microsoft Alliance Support for Enterprise Systems

  • Microsoft Alliance Support for High Availability

Microsoft Certified Support Centers

Microsoft Certified Support Centers are selected for their ability to provide high-quality support and a full range of support services for organizations using Microsoft products in all kinds of environments. Certified Support Centers provide the highest-quality service for both Microsoft products and a wide range of third-party products to ensure a cohesive, high-performance business solution.

  • For more information, go to the Microsoft Certified Support Center (www.microsoft.com/support/mcsc).

Note

  • Microsoft support services are subject to Microsoft's then-current prices, terms, and conditions, which are subject to change without notice.


International Support

Note

  • Phone numbers for Microsoft Subsidiaries are subject to change. For the most recent listing, go to the Microsoft Product Support Services Web site (support.microsoft.com/directory) and select "worldwide support". If there is no Microsoft subsidiary office in your country, please contact the establishment from which you obtained your Microsoft product.

Argentina

Microsoft de Argentina S.A.

Fax: (54-11) 4316-1922

Customer Service: (54-11) 4316-4600

Technical Support Phone (54-11) 4316-4664

Armenia

See Russia

Australia

Microsoft Pty. Ltd.

Phone: 13 20 58

Fax: 612 9023 5021

Technical Support Phone: 13 20 58

Austria

Microsoft Ges.m.b.H.

Phone:(+43) 1 610 64 -0

Fax: (+43) 1 610 64 -200

InfoServices: 08000-123 345, Fax: +43-2236-64595, InfoService@microsoft.at

Direct Services (Updates, etc.): +43-1- 795 67028, Fax: +43-1-795 67029,austria@msdirectservices.com

Standard Support (Installation and Handling): +43-1-50222-2255

Azerbaijan

See Russia

Belgium

Microsoft NV

Phone: +32 2 7043000

Fax: +32 2 7043535

TechNet Subscription: +353 1 703 8738

MSDN Subscription: +32 2 5138684

Microsoft Information Center: +32 2 5133113

Technical Support:

  • +32 2 513 32 74 (Dutch speaking)

  • +32 2 502 34 32 (English speaking)

  • +32 2 513 22 68 (French speaking)

Belarus

See Russia

Bolivia

See Uruguay

Brazil

Microsoft Informatica Ltda.

Phone: (55) (11) 5514 - 7100

Fax: (55) (11) 5514 - 7106/5514-7107

Technical Support:

  • Phone: (55) (11) 5504-2155

  • Fax: (55) (11) 5504-2227

  • Automatic Fax: (55) (11) 5506-8506

  • Bulletin Board Service: (55) (11) 5506-1234

Customer Services: (55) (11) 822-5764

Customer Services Fax: (55) (11) 822-6227

Canada

Microsoft Canada Co.

Head Office Phone: 1 (905) 568-0434

Customer Information Centre: 1 (800) 563-9048

Technical Support:

  • Desktop Systems including Microsoft Windows 95: (905) 568-4494

  • Microsoft Office and Office Components: (905) 568-2294

  • Other Standard Technical Support: (905) 568-3503

  • Priority Support Information: (800) 668-7975

  • Text Telephone (TTY/TDD) (905) 568-9641

Caribbean

Microsoft Caribbean, Inc.

Phone: (809) 273-3600

Fax: (809) 273-3636

Technical Support/Soporte Tecnico: (408) 953-8086

Support E-mail/Correo Electronico para Soporte Tecnico: mscasup

Customer Service/Centro de Servicios: (800) 297-5982 for area codes 787 & 809 only

Customer Service E-mail/Correo Electronico para Atencion a Usarios: msccatus

Central America

Technical Support/Soporte Tecnico: (506) 298-2020

Support E-mail/Correo Electronico para Soporte Tecnico: mscasup

Customer Service/Centro de Servicios: (506) 298-2000

Customer Service E-mail/Correo Electronico para Atencion a Usarios: mscarsup

Chile

Microsoft Chile S.A.

Phone: 56-2-330-6000

Fax: 56-2-330-6190

Customer Service: 56-2-800-330600

Personal Operating System and Applications:

  • Phone: 56-2-330-6222

  • Fax: 56-2-341-1439

China

Microsoft (China) Co. Ltd

6/F, Beijing Sigma Center

No. 49, Zhichun Road, Haidian District

Beijing, 100080, PRC

Phone: 011-86-10-6261 7711

Fax: 011-86-10-6253 6630

Microsoft Asia Regional Engineering Center

19th - 20th Floor, Metro Tower

No. 30 Tian Yao Qiao Road,

Shanghai, 200030, P.R.C.

Phone: 011-86-21-64691188/ 011-86-21-6469 8899

Fax: 011-86-21-6469 1166 / 011-86-21-6469 9900

Colombia

Microsoft Colombia

Carrera 7a. # 71-21 Torre B Piso 7

Santa Fé de Bogotá

Phone: (571)3173838

Fax: (571) 3173494

Technical Support:

Línea de Respuesta Bogota

Phone: 524-0404

Other cities: 9800-10595

Fax: (091) 524-0405

Croatia

Microsoft Hrvatska d.o.o.

Trg D. Petrovica 3

10 000 Zagreb

Croatia

Phone: 385 1 4802 500

Fax: 385 1 4843 688

Product Support Phone Number 385 1 393539, e-mail: hot-line@microsoft.hr

Customer Service + 385 0800 300 300, e-mail: info-line@microsoft.hr

Czech Republic

Microsoft s.r.o.

Phone (+420) (2) 611 97 111

Fax: (+420) (2) 611 97 100

Technical Support: (+420) (2) 2150 3222

Denmark

Microsoft Denmark

Phone: (45) (44) 89 01 00

Fax: (45) 44 68 55 10

Technical Support:

  • Phone: (45) 44 89 01 11

  • Microsoft Sales Support: (45) 44 89 01 90

  • Microsoft FastTips: (45) 44 89 01 44 (Document 303030 in FastTips contains detailed instructions)

  • Microsoft MSDL (BBS): (45) 44 66 90 46

Dominican Republic

See Central America

Dubai

Microsoft Middle East

Phone: (971) 4 3973888

Fax: (971) 4 3972244

Technical Support (Personal Operating Systems & Desktop Applications only):

Phone: (971) (4) 3975443

Fax: (971) (4) 3972304

E-mail: mswsgulf@microsoft.com

Customer Service Center (Version upgrade / TechNet and MSDN subscription):

Phone: (971) (4) 3975752

Fax: (971) (4) 3972304

Ecuador

Corporation Microsoft del Ecuador S.A.

Phone/PBX: (593 2) 460453

Fax: (593 2) 463093

Customer Service: (593 2) 258025

Technical Support: (593 2) 258025

Egypt

Technical Support (Personal Operating Systems & Desktop Applications, and Development Tools "Installation ONLY"):

Tel no.: 202 - 338 8724

202 - 338 9794

Fax: (202) 360 4976

E-mail: mssupport@gbrands.com

England

See United Kingdom

Estonia

Technical Support: (+372) 650 49 99

Finland

Microsoft OY

Phone: +358-(0) 9-525 501

Fax: +358-(0) 9-878 8770

Technical Support:

  • Phone: +358-(0) 9-525 502 5026

  • Standard +358 (0) 9-525-502-500

  • Priority: +358 (0) 9-525-502-20

France

Phone: (011)(33) 825 827 829 (*)

Customer Svc. Phone: (011)(33) 0 825 827 829 (*)

Fax: (33) 01 64-46-06-60

Telex: MSPARIS 604322

Customer Svc. Phone: (011)(33) 0 825 827 829 (*)

Technical Support Phone: (011)(33) 825 827 829 (*) access code 1020

Technical Support Fax: (011)(33) 1 69 28 00 28

(*) indigo number 0,99 F TTC per minute

French Polynesia

See France

Georgia

See Russia

Germany

Microsoft GmbH

Phone: 089/3176-0

Fax: 089/3176-1000

Telex: (17) 89/83 28 MS GMBH D

Information: 089/3176 1199

Prices, updates, etc.: 01805 / 25 11 99

Standard Support (Installation and Handling): 01805/67 22 55

General information about Microsoft Support in Central Europe: Fax: 1805-25-1191

Greece

Microsoft Hellas, S.A.

Phone: (30)(1) 6806-775 through (30)(1)6806-779

Fax: (30)(1) 6806 780

Technical Support:

  • Phone: (30) (1) 6806111

  • Fax: (30) (1) 6809528

Gulf and Eastern Mediterranean

PO Box 52244

Dubai, UAE

Tel: 971 4 3973888

Fax: 971 4 3972244

Personal Support Contact Details: (Personal Operating Systems & Desktop Applications ONLY)

Gulf (Bahrain, Malta, Qatar and United Arab Emirates)

Phone - 971 4 3975443

Fax - 971 4 3972304

E-Mail = mswsgulf@microsoft.com

  • Lebanon (Cyprus and Lebanon)

    See Lebanon

  • Oman

    See Oman

Hong Kong SAR, PRC

Microsoft Hong Kong SAR, PRC Limited

Fax: (852) 2560-2217

Microsoft Information Hotline: (852) 2804-4234

Personal Technical Support: (852) 2804-4222

Professional Technical Support: (852) 2804-4288

Hungary

Microsoft Hungary

Phone: (+36) (1) 437-2800

Fax: (+36) (1) 437-2899

Customer Services: (+36) (1) 267-4636 (2MSINFO)

Technical Support: (+36) (1) 267-7846 (2MSSUGO)

Iceland

See Denmark

India

Microsoft India

Phone: (91) (80) 559-5733, (91) (11) 6294600, 6294601, (91) (22) 2850193

Fax: (91) (80) 559-7133, (91) (11) 629-2650

Indonesia

Microsoft Indonesia - Jakarta

Technical Support:

  • Phone: 62 21 570 42 54

  • Fax: 62 21 520 81 22

Ireland

Technical Support:

Phone: 706 5353

See United Kingdom

Israel

Microsoft Israel Ltd.

Reception:

Phone: +972-9-952-5353

Fax: +972-9-952-5333

Customer Service & Information Center:

Phone: +972-9-9525400

Fax: +972-9-9525411

Technical Free Support for Windows, Office and Microsoft Fun:

Phone: +972-9-9525400

Fax: +972-9-9525403

Italy

Microsoft Srl

Phone: (39) (2) 70-398-398

Fax: (39) (2) 7039-2020

Microsoft Rome Office: (39) (6) 5095-01 - Fax: (39) (6) 5095-0600

Customer Service (New product info, product literature): (39) (2) 70-398-398

Operatori del Settore IT (Customer Service for IT): (39) (2) 70-398-398

Technical Support: (39) (2) 70-398-398

Microsoft Consulting Service: (39) (2) 70-398-398

Japan

Microsoft Company Ltd.

Technical Support (Standard Support): (81) (3) 5354-4500

Technical Support options/ Support Contract: (81) (3) 5354-4700

Channel Marketing Information Center (Presales Product Support):

  • Tokyo Phone: (81) (3) 5454-2300

  • Osaka Phone: (81) (6) 6245-6995

Customer Service Phone (Version upgrade/Registration):

  • Phone: (81) (48) 226-5500

  • Fax: (81) (48) 226-5511

Kazakhstan

See Russia

Kingdom of Saudi Arabia

http://www.microsoft.com/middleeast
Microsoft Arabia
Riyadh, Kingdom of Saudi Arabia
Tel: 966 1 2180808
Fax: 966 1 2180809

Support
Tel: 800 1242255 (toll free)
Fax: 966 1 218-0821
E-mail: saudimss@microsoft.com

Kyrgyzstan

See Russia

Korea

Microsoft CH

Phone: (82) (2) 531-4500

Fax: (82) (2) 531-1724

Game and Hardware Service Center: 080-645-1000 (toll free domestic only)

Customer Satisfaction Center: 080-985-2000 (toll free domestic only), (82) (2) 558-8161

Technical Support Center: (82) (2) 508-0040

Microsoft FastTips: (82) (2) 3453-7555

Support Sales: (82) (2) 531-4544

Internet: http://www.microsoft.com/korea/support/default

Kuwait

PO Box 5244

13053 Safat

Tel: +965-243-0248

Fax: +965-243-0249

Technical Support (Personal Operating Systems, Desktop Applications and Developer Tools ONLY):

Tel: +965-243-1071

Latin America

Microsoft Latin American Headquarters (U.S.A.)

Phone: (305) 489-4800

Fax: (305) 491-1616

Customer Service: (425) 936-8661

Technical Support: (214) 714-9100

Lebanon (Cyprus and Lebanon)

Phone - 961 1 983348

Fax - 961 1 983349

E-Mail = mts@lebanon-online.com.lb

Liechtenstein

See Switzerland

Luxembourg

Microsoft NV

Phone: +32 2 730 39 11

Microsoft Support Network Info. Center +31-800-9977-57

TechNet Subscription: +353-1-703 8738

MSDN Subscription: +353-1-708-8690

Microsoft Information Center: +32-2-481 52 52

Bulletin Board: +32 2 726 85 45 (1200/2400/9600/14400 bd, 8N1, ANSI)

Technical Support:

  • +32 2 513 32 74 (Dutch speaking)

  • +32 2 502 34 32 (English speaking)

  • +32 2 513 22 68 (French speaking)

See also Netherlands

Malaysia

Microsoft (Malaysia) Sdn Bhd:

Phone: +6 (03) 757-2266

Fax: +6 (03) 757-2265

Customer Services:

  • Phone: Toll-free - 1-800-88-3249

  • Fax: +6 (03) 758-5011

Technical Support:

  • Phone: +6 (03) 793-9595

  • Fax: +6 (03) 295-2065

México

Microsoft México, S.A. de C.V.

267-2110 Atencion a Distribuidores

265-3380 Atencion a Clientes

265-3399 Soporte Sistemas Operativos y Applicaciones de Escritorio

267-2190 Soporte de Servidores y Herramientas de Desarrollo

Fast Tips: (52)(5) 2612199

Microsoft BBS 628-6200/02 MSMEXICO sin password

Middle East

Microsoft Middle East

Phone: (971) 4 397 3888

Fax: (971) 4 397 2244

Technical Support (Personal Operating Systems & Desktop Applications ONLY):

  • Phone: (971) (4) 397 5443

  • Fax: (971) (4) 397 2304

  • E-mail: mswsgulf@microsoft.com

Customer Service Center (Version upgrade / TechNet and MSDN subscription):

  • Phone: (971) (4) 299 5082

  • Fax: (971) (4) 299 5097

Morocco

Microsoft Afrique du Nord et de l'Ouest

Phone: (212) 2 95 80 80

Fax: (212) 2 95 85 85

Netherlands, The

Jaar 2000 informatie centrum

Netherlands: (020) 5001033

Belgium: +32-2 7043000

Luxemburg: +32-2-5139979

Support and Services

Product Support:

  • Netherlands (Dutch): (020) 5001005

  • Netherlands (English): (020) 5001053

  • Belgium (Dutch): +32 2 513 31 13

  • Belgium (French): +32 2 513 22 68

  • Belgium (English): +32 2 502 34 32

  • Luxemburg (French): +32 2 513 2268

  • Luxemburg (English): +32 2 502 3432

Microsoft Consulting Services Benelux

Netherlands, Belgium and Luxemburg: +31 (0)20 5001005

Information Services and Subscriptions

TechNet

  • Netherlands: (020) 5001035

  • Belgium: +32 2 5022176

  • Luxemburg: +32 2 5022176

MSDN

  • Netherlands: (020) 5001037

  • Belgium: +32 2 5138684

  • Luxemburg: +32 2 5138684

New Zealand

New Zealand

Microsoft New Zealand Ltd

Phone: 64 (9) 357-5800

Fax: 64 (9) 357-0868

Technical Support:

  • Phone: 64 (9) 357-5575

  • Fax: 64 (9) 357-5577

Northern Ireland

See United Kingdom

Norway

Microsoft Norway AS

Phone: +(47) 22 02 25 00

Fax: +(47) 22 95 06 64

Technical Support:

  • Standard: + (47) 22 02 25 50

  • Priority: + (47) 22 02 25 45

  • Premier: + (47) 22 02 25 46

Microsoft Sales Support: +(47) 22 02 25 80

Microsoft MSDL: + (47) 22 18 22 09

Microsoft FastTips: + (47) 22 02 25 70 (Document 404040 in FastTips contains detailed instructions)

Oman

Phone - 968 691191

Fax - 968 698568

E-Mail = mspss@gto.net.om

Pakistan

Phone: 92 21 111 674357

Fax: 92 21 4533370

E-mail: mssupport@nets.net.pk

Customer Service Center (Version upgrade / TechNet and MSDN

subscription):

Phone: (971) (4) 3975752

Fax: (971) (4) 3972304

Panama

Technical Support/Soporte Tecnico: (506) 298 2020

Support E-mail/Correo Electronico Para soporte tecnico: mscasup

Customer Service/Centro de Servicios: (506) 298 2000

Customer Service E-mail/Correo Electronico para Atencion a Usuarios: msccatus=

Papua New Guinea

See Australia

Paraguay

See Uruguay

Perú

Phone: (511) 421-1200

Fax (511) 4217307

Technical Support:

(511) 2155002 and (511) 2155005

Philippines

Phone: (632) 811-0062

Technical Support:

  • Phone: (632) 892-2295/2495

  • Fax: (632) 813-2493

Poland

Microsoft Sp. z o.o.

Phone: +(48-22) 661-54-00

Fax: +(48-22) 661-54-34

Information Service: +(48-22) 865-99-33

Technical Support: +(48-22) 865-99-66

Portugal

Microsoft Portugal MSFT, Lda.

Phone: (351) 1 4409200

Fax: (351) 1 4412101

Technical Support:

  • Standard Support: +(351) 1 4409280

  • Fax : +(351) 1 4411655

Puerto Rico

Soporte Tecnico: (408) 953 8086

Support E-Mail/Correo Electronico Para soporte tecnico: mscarsup

Customer Service/Centro de Servicios: (800) 297 5982 for area codes 787 & 809 only

Customer Service E-mail/Correo Electronico para Atencion a Usuarios: msccatus

Romania

Microsoft s.r.l.

Phone: (+40) (1) 222 90 16

Fax: (+40) (1) 222 90 12

Technical Support: (+40) (1) 312 09 48

Russia

Microsoft Z.A.O.

Microsoft Information Center:

Phone:

  • Moscow: +7 (095) 916-7171

  • St.Peterburg: +7 (812) 118-3636

  • Novosibirsk: +7 (3832) 119-019

  • Kiev +380 (044) 2305101

Fax:

  • Moscow: +7 (095) 916-7112

Technical Support:

Phone:

  • Moscow: +7 (095) 745-5445

  • St.Peterburg: +7 (812) 118-3636

  • Novosibirsk: +7 (3832) 119-019

  • Kiev +380 (044) 2305102

Fax:

  • Moscow: +7 (095) 916-7112

Scotland

See United Kingdom

Singapore

Microsoft Singapore Pte Ltd

Phone: (65) 337-6088

Fax : (65) 337-6788

Customer Services Phone: (65) 324-5255

Customer Services Fax: (65) 324-6181

Product Support Services Phone: (65) 378-3600

Product Support Services Fax: (65) 378-3662

Slovakia

Microsoft Slovakia s.r.o.

Bratislava Business Center IV

Prievozska 6/A

821 09 Bratislava

SLOVAK REPUBLIC

Phone: +421-7-5341 9841

Fax: +421-7-5341 9840

Hotline: +421-7-67 296 296

Infoservice: +421-7-67 296 297

Y2K Infoservice: +421-7-67 296 200

Slovenia

Microsoft d.o.o.

Phone: (+386) (61) 1 800 800

Fax: (+386) (61) 1 800 822

Technical Support: (+386) (61) 185 3449

South Africa

Microsoft South Africa

All services

Phone: (+27) 11 257 0000 or

0860225567 (inside South Africa)

Fax: (27) 11 257 0257

Technical Support Fax: (+27) 11 257-0424

South East Africa and Indian Ocean Islands

See South Africa

Spain

Microsoft Iberica SRL

Inside Spain

Phone: 902 197 198

Fax: 91 803 8310

Technical Support: 902 197 198

Customer Service: 902 197 198

Fax Back telephone: 902 197 198

Outside Spain

Phone: (34) 91 353 69 60

Fax: (34) 91 803 8310

Technical Support: (34) 91 353 69 60

Customer Service: (34) 91 353 69 60

Fax Back telephone: (34) 91 353 69 60

Sweden

Microsoft AB

Phone: +46-(0) 8-752 56 00

Fax: +46-(0) 8-750 51 58

Technical Support:

  • Standard: +46-(0) 8- 752 09 29

  • Priority: +46 (0) 8 751 09 80

  • Premier: +46 (0) 8 632 57 01

Sales Support: +46-(0) 8- 752 56 30

Switzerland

Microsoft AG

Phone: 01-839 61 11

Fax: 01-831 08 69

Customer Service Phone: 0848-858-868

  • Microsoft Info-Service, Postfach, 8001 Zürich, Fax: 01 311-72-27

Support:

  • Standard Technical Support (German speaking) Installation and Handling: Phone 0848 80 - 2255

  • Standard Technical Support (French speaking): Phone 022-738 96 88

  • General information about Microsoft Support in Central Europe: Phone 0848-80-2330

Tajikistan

See Russia

Taiwan

Microsoft Taiwan Corp.

Phone: (886) (2) 2504-3122

Fax: (886) (2) 2504-3121

Technical Support:

  • Phone: (886) (2) 2508-9501

  • Fax: (886) (2) 2508-9575

Thailand

Microsoft (Thailand) Limited

Phone: (662) 266-3300

Fax: (662) 266-3310

Product Support:

Phone: (662) 613-7208 through 11

Fax: (662) 613-7198

Turkey

Microsoft Turkey

Phone: 90 (212) 258 59 98

Fax: (90 (212) 258 59 54

Support Hotline:

  • Phone: 90 (212) 275 2466

  • Fax: 90 (212) 272 7755

Turkmenistan

See Russia

United Kingdom

Microsoft Limited

Phone: (0870) 60 10 100

Fax: (0870) 60 20 100

Microsoft Technical Support

  • Desktop Applications, Home Products, Personal Operating Systems and hardware. 0870 50 10 100

  • Developer Products 0870 50 10 200

  • Business Systems 0870 50 10 300

  • Customers phoning from Ireland should dial 706 5353 for technical support.

Pre-Sales Information: Microsoft Connection (0345) 00 2000

Uruguay

Technical Support:

  • Phone: (598) (2) 774934

  • Fax: (598) (2) 774935

See also Uruguay Online

Uzbekistan

See Russia

Venezuela

Corporation MS 90 de Venezuela S.A.

Other information: (582) 265-9922

Fax: (582) 265-0863

Technical Support: (582) 993-6755

Wales

See United Kingdom

Note

  • Microsoft support services are subject to Microsoft's then-current prices, terms, and conditions, which are subject to change without notice.


Using Commerce Server Help

The Commerce Server 2000 Help system provides documentation for site developers, system administrators, and business managers.

This section contains:

  • About Commerce Server Help. Describes the structure and contents of Commerce Server 2000 Help.

  • Using the Help Viewer. Explains how to use the Help Viewer to find the information you need.

  • Searching for a Help Topic. Explains how to search for exact phrases and how to search for topics using OR, AND, NEAR, and NOT.

  • Bookmarking a Help Topic. Explains how to bookmark a help topic so you can quickly return to it.

  • Printing a Help Topic. Explains how to print one or more topics at the same time.

  • Copying a Help Topic. Explains how to copy a help topic and paste it into another document.

  • Using Language Filtering. Explains how to use language filtering to view code samples in C++ or Microsoft Visual Basic.

  • Help Viewer Keyboard Shortcuts. Lists the keyboard shortcuts for using Help Viewer.

  • Additional Resources. Lists other resources for information besides Commerce Server 2000 Help.


About Commerce Server Help

Commerce Server 2000 Help is designed so that users can quickly locate the type of information—workflow, concepts, procedures, or reference—they need to effectively manage, administer, or develop their commerce sites.

Structure of the Help System

Developer Help

Business Desk Help

Structure of the Help System

The table of contents is organized into several books, each one corresponding to a major functional area of the product. The nodes, or chapters, contained in each book correspond to major tasks that you will perform in that area, or explain key concepts or technologies that you will need to understand to complete those tasks.

The following table lists the Commerce Server books and provides a description of each one.

Book | Description | Users
Getting Started | Describes Commerce Server features, tools, and concepts. Explains how to plan your Commerce Server site and provides a link to the installation instructions. | All users of Commerce Server
Developing Your Site | Explains how to set up your development environment, how to program with Commerce Server objects, how to customize pipelines, and how to integrate Commerce Server with other applications. | Site developers
Deploying Your Site | Explains how to use Site Packager to deploy a site that uses SQL Server or Active Directory, and how to make incremental updates to your site. Explains how to secure your site. Provides two detailed examples for installing Commerce Server on a 4-computer, clustered configuration and on a 3-computer, non-clustered configuration. | System administrators
Administering Commerce Server | Describes Commerce resources, sites, applications, Web servers, and the Administration database, and explains how to manage them. Explains how to manage Profiles, CS Authentication, Direct Mailer, Data Warehouse, and Predictor. Explains how to set up Commerce Server to use BizTalk Server. | System administrators
Working with Business Desk | Explains how to manage your site using Business Desk. Includes a tutorial that contains labs for learning how to manage a business-to-consumer site and a business-to-business site. | Business managers
Extending Commerce Server | Explains how to integrate a custom resource into Commerce Server, how to build new Business Desk modules, and how to build new pipeline components. Explains how to create custom reports, extend the Data Warehouse, integrate with third-party product catalogs, and integrate with Microsoft Passport. | Site developers
Programmer's Reference | Provides extensive reference material about the COM components that serve various functions within Commerce Server. | Site developers
Troubleshooting Commerce Server | Describes symptoms and solutions for problems you may encounter using Commerce Server. | System administrators and site developers
Glossary | Defines common terms used throughout Commerce Server. | All users of Commerce Server

Within each book, you will find nodes that contain the following types of information:

  • Workflow diagrams. The documentation for each Business Desk category contains a figure illustrating the key tasks performed in that functional area, with links to the task topics that provide step-by-step instructions for completing each one.

  • Getting Started. Getting Started nodes appear for both Commerce Server and for Business Desk.

  • Basics topics. These topics describe common tasks and provide navigational information for using Business Desk, Commerce Server Manager, and pipelines.

  • Concepts. In the Business Desk topics and elsewhere, titles beginning with "About" indicate topics that explain key concepts for successfully using Commerce Server and its components.

  • Tasks. Task topics provide step-by-step instructions for completing the tasks shown in the workflow.

Developer Help

To assist you in finding only the information that is relevant to your programming environment, Commerce Server 2000 Help implements a language-filtering tool. On the title bar in topics contained in the Programmer's Reference, you will find a filter button that provides a language menu. Using this menu, you can choose to view documentation tailored either to Visual C++ or to Visual Basic. After you select a language, that selection remains in effect while viewing subsequent pages.

In addition to Help, see the following for developer information:

  • Commerce Server Software Development Kit (SDK). Includes code samples and documentation for developing e-commerce solutions with Commerce Server. For example, it explains how to develop code for related sells (up-sells, cross-sells, and inventory sells). The SDK is installed with Commerce Server 2000.

    To access the SDK, click Start, point to Programs, point to Microsoft Commerce Server 2000, and then click Software Development Kit.

  • Commerce Server 2000 Resource Kit. Provides detailed information about how to plan, develop, deploy, scale, and optimize your Commerce Server installation. The Commerce Server 2000 Resource Kit is published by Microsoft Press.

Business Desk Help

The Business Desk Help system is a subset of the Commerce Server 2000 Help system. Business Desk users have access to the help contained in the book, "Working with Business Desk," but they do not have access to the other Commerce Server books from their client computer.

To access help from the Business Desk, click Business Desk Help Icon on the toolbar.


Using the Help Viewer

The Commerce Server 2000 Help system uses HTML to format and display information. The Help Viewer provides a table of contents, an index, and a full-text search feature so that you can find information easily. Book icons open to reveal sub-books and topics.

To expand the table of contents and view topics within a book, click the expand indicator (+) next to a book title. When you click the collapse indicator (-), the topics are hidden. Using the Help Viewer, you are able to see the table of contents, index, or search results at the same time you are viewing a Help topic.

The Help Viewer also includes a Favorites tab, which you can use to bookmark topics. This enables you to quickly display topics that you refer to often.

To learn more about Commerce Server, you can use the table of contents to browse through the documentation. When you click a topic in the table of contents, information is displayed in the content pane of the Help window.

In the Help Viewer, the following browse and search options are available:

  • Contents tab
    1. To browse the table of contents, click the Contents tab. Double-click the book icons to reveal topic entries and sub-books.

    2. Click a table-of-contents entry to display the corresponding topic.
  • Index tab
    1. To see a list of index entries, click the Index tab, and then either type a word or scroll through the list. Topics are often indexed under more than one entry.

    2. Double-click an index entry to display the corresponding topic.
  • Search tab
    1. To locate every occurrence of a word or phrase, click the Search tab, type the word or phrase for which you want to search, and then click List Topics. To make your search results more specific, you can combine multiple words or phrases with AND, OR, NEAR, or NOT.

    2. Double-click a search results entry to display the corresponding topic.

    For more information about searching for a topic, see Searching for a Help Topic.

  • Favorites tab
    1. To bookmark a topic, use the Contents, Index, or Search tabs to locate and then display a topic.

    2. Click the Favorites tab, and click Add to save the topic title to the Topics list.

    3. Double-click a bookmark in the Topics list to quickly display the topic.

See Also

Searching for a Help Topic

Bookmarking a Help Topic

Printing a Help Topic

Copying a Help Topic

Using Language Filtering

Help Viewer Keyboard Shortcuts


Searching for a Help Topic

  1. To locate every occurrence of a word or phrase, click the Search tab, type the word, and then click List Topics.

  2. To search for a specific phrase, surround the phrase in quotes, for example "the computer and monitor" finds topics that contain the exact phrase the computer and monitor.

  3. To make your search results more specific, you can combine multiple words or phrases with AND, OR, NEAR, or NOT.

    For example:

    • Searching for computer and monitor finds topics that contain both computer and monitor.

    • Searching for computer or monitor finds topics that contain computer or contain monitor.

    • Searching for computer near monitor finds topics that contain both computer and monitor in close proximity to each other.

    • Searching for computer not monitor finds topics that contain the keyword computer but do not contain the keyword monitor.
  4. Double-click a search results entry to display the corresponding topic.

See Also

Bookmarking a Help Topic

Printing a Help Topic

Copying a Help Topic

Using Language Filtering

Help Viewer Keyboard Shortcuts


Bookmarking a Help Topic

  1. Use the Contents, Index, or Search tab to locate and then display the topic you want to bookmark.

  2. Click the Favorites tab, and then click Add.

The Help Viewer adds the topic title to the Topics list. Later, you can return to this list and double-click the bookmark to quickly display the topic.

Notes

  • You can create a list of frequently visited Help topics.

  • To remove a bookmark from the Topics list, click the bookmark, and then click Remove.

See Also

Searching for a Help Topic

Printing a Help Topic

Copying a Help Topic

Using Language Filtering

Help Viewer Keyboard Shortcuts


Printing a Help Topic

  • Right-click the topic you want to print, and then click Print.

  • To print a pop-up topic, right-click inside the pop-up window, and then click Print.

  • To print all topics within a book, on the Contents tab, select the book. On the Help toolbar, click Options, click Print, and then click Print the selected heading and all subtopics.

Notes

  • If you print a section with multiple topics that contain multiple illustrations, the illustrations will not print.

  • Printing code samples and large illustrations could result in incomplete printing. If a line of code is very long or an illustration is very large, the right edge of the code or illustration might extend beyond the margin boundary and will not print.

See Also

Bookmarking a Help Topic

Searching for a Help Topic

Copying a Help Topic

Using Language Filtering

Help Viewer Keyboard Shortcuts


Copying a Help Topic

  1. In the topic pane of the Help Viewer, right-click inside the topic you want to copy, and then click Select All.

  2. Inside the topic, right-click again, and then click Copy.

  3. Open the document to which you want to copy the topic.

  4. Click the place in your document where you want the information to appear.

  5. On the Edit menu, click Paste.

Notes

  • If you want to copy only part of a topic, select the part you want to copy, right-click the selection, and then click Copy.

  • Step numbers are not copied to the Clipboard.

See Also

Printing a Help Topic

Bookmarking a Help Topic

Searching for a Help Topic

Using Language Filtering

Help Viewer Keyboard Shortcuts


Using Language Filtering

To assist you in finding only the information that is relevant to your programming environment, Commerce Server Help implements a language-filtering tool. On the title bar in topics contained in the Programmer's Reference, you will find a filter button that provides a language menu. Using this menu, you can choose to view documentation tailored either to Visual C++ or to Visual Basic. After you select a language, that selection remains in effect while viewing subsequent pages.

To view the language-filtering options, click the filter button on the title bar, and then click one of the following options:

  • C++

  • Visual Basic

See Also

Printing a Help Topic

Bookmarking a Help Topic

Searching for a Help Topic

Help Viewer Keyboard Shortcuts

Copying a Help Topic

Additional Resources


Help Viewer Keyboard Shortcuts

If your mouse is unavailable or if you prefer using your keyboard, you can use the following keyboard commands to navigate within the Help Viewer.

Help Viewer keyboard shortcuts

Press | To
ALT+SPACEBAR | Display the system menu.
SHIFT+F10 Display the Help Viewer shortcut menu.

Note

  • Use this shortcut when the focus is in the topic pane.
ALT+TAB | Switch between the Help Viewer and other open windows.
ALT+O | Display the Options menu.
ALT+O, and then press T | Hide or show the navigation pane.
CTRL+TAB | Switch to the next tab in the navigation pane.
CTRL+SHIFT+TAB | Switch to the previous tab in the navigation pane.
UP ARROW | Move up one topic in the table of contents, index, or search results list.
DOWN ARROW | Move down one topic in the table of contents, index, or search results list.
PAGE UP | Move up one page in the table of contents, index, or search results list.
PAGE DOWN | Move down one page in the table of contents, index, or search results list.
F6 | Switch focus between the navigation pane and the topic pane.
ALT+O, and then press R | Refresh the topic that appears in the topic pane.
UP ARROW or DOWN ARROW | Scroll through a topic.
CTRL+HOME | Move to the beginning of a topic.
CTRL+END | Move to the end of a topic.
CTRL+A | Highlight all text in the topic pane.
ALT+O, and then press P | Print a topic.
ALT+O, and then press B | Move back to the previously viewed topic.
ALT+O, and then press F | Move forward to the next (previously viewed) topic.
ALT+F4 | Close the Help Viewer.

Contents tab keyboard shortcuts

Press | To
ALT+C | Display the Contents tab.
RIGHT ARROW | Open a book.
LEFT ARROW | Close a book.
BACKSPACE | Return to the previous open book.
UP ARROW or DOWN ARROW | Select a topic.
ENTER | Display the selected topic.

Index tab keyboard shortcuts

Press | To
ALT+N | Display the Index tab.
UP ARROW or DOWN ARROW | Select a keyword in the list.
ALT+D or ENTER | Display the associated topic.

Search tab keyboard shortcuts

Press | To
ALT+S | Display the Search tab.
ALT+L | Start a search.
ALT+D or ENTER | Display the selected topic.

Favorites tab keyboard shortcuts

Press | To
ALT+I | Display the Favorites tab.
ALT+A | Add a topic to the Topics list.
ALT+P Select a topic in the Topics list.

Note

  • Use this shortcut when the focus is in the topic pane and you want to move to the Topics list.
ALT+R | Remove a topic from the Topics list.
ALT+D | Display a topic from the Topics list.

See Also

Printing a Help Topic

Bookmarking a Help Topic

Searching for a Help Topic

Using Language Filtering

Copying a Help Topic


Additional Resources

In addition to the Commerce Server 2000 Help system, you can find information from the following sources:

  • Software Development Kit (SDK), located in the Program Files\Microsoft Commerce Server\SDK folder

  • Commerce Server Resource Kit, available as a printed book from Microsoft Press

  • Commerce Server Web Site


Installing Commerce Server

This section provides hardware and software requirements for Microsoft Commerce Server 2000, and it explains how to uninstall Commerce Server. For instructions on installing Commerce Server, see http://support.microsoft.com/support/commerceserver/2000/install/default.asp.

This section contains:

  • Hardware Requirements. Provides the hardware requirements for Commerce Server 2000.

  • Software Requirements. Provides the software requirements for Commerce Server 2000.

  • Installing the Business Desk Client. Explains how to install Commerce Server Business Desk on a client computer.

  • Uninstalling Commerce Server. Explains how to uninstall Commerce Server 2000, Commerce Server databases, site virtual directories, and site folders and files.

  • Uninstalling the Business Desk Client. Explains how to uninstall the Business Desk client.

See Also

Installing Administration Tools Only


Hardware Requirements

This section lists the hardware requirements for the following:

Commerce Server

Administration Tools

Business Desk Client

Commerce Server

The hardware requirements for a Commerce Server 2000 server installation are:

  • 400 MHz or faster Pentium-compatible CPU

  • 256 MB of RAM (128 MB of RAM is adequate for a development environment)

  • 100 MB of hard disk space

  • CD-ROM drive

  • Network adapter card

  • VGA or Super VGA monitor

  • Microsoft Mouse or compatible pointing device

In your production environment, the volume of traffic on your Web site may dictate more stringent hardware requirements for Web servers.

Administration Tools

The hardware requirements for a Commerce Server 2000 installation with Administration tools only are:

  • 266 MHz or faster Pentium-compatible CPU

  • 128 MB of RAM

  • 20 MB of hard disk space

  • CD-ROM drive

  • Network adapter card

  • VGA or Super VGA monitor set to 800 by 600 pixels resolution or higher

  • Microsoft Mouse or compatible pointing device

Business Desk Client

The hardware requirements for a Business Desk client are:

  • 266 MHz or faster Pentium-compatible CPU

  • 5 MB of hard disk space

  • CD-ROM or DVD-ROM drive

  • VGA or higher-resolution monitor set to 800 by 600 pixels resolution or higher

  • Microsoft Mouse or compatible pointing device


Software Requirements

This section lists the software requirements for the following:

Commerce Server

SQL Server

Business Desk Client

Commerce Server

Before you install Commerce Server 2000, you must install the following software on your server in the order listed:

Note

  • This is the only platform supported by Microsoft Professional Support Services. Pre-release versions of Windows 2000 are not supported.
  1. Microsoft Windows 2000 Server or Advanced Server.

    If you want to install only the Administration tools or Commerce Server 2000 Help, you can use Microsoft Windows 2000 Professional.

  2. Windows 2000 Server Service Pack 1.

  3. Microsoft Windows 2000 Hotfixes.

    These hotfixes apply to Microsoft Windows 2000 Server, Microsoft Windows Advanced Server, and Microsoft Windows 2000 Professional.

In addition, you must also have an installation of SQL Server 2000 or SQL Server 7.0 available to Commerce Server on the same network. For the SQL Server software requirements, see SQL Server.

Note

  • Commerce Server Direct Mailer must be installed on the same computer as SQL Server.

For detailed information about configuring a multi-computer production environment, see Deploying Your Site.

SQL Server

Commerce Server requires access to either SQL Server 2000 or SQL Server 7.0 on the same network.

SQL Server 2000 Requirements

  • SQL Server 2000 Client Tools

  • SQL Server 2000 Analysis Services

  • SQL Server 2000 Analysis Services Client Tools

SQL Server 2000 includes Microsoft Data Access Components (MDAC) 2.6.

SQL Server 7.0 Requirements

  • Microsoft SQL Server 7.0 Client Tools

  • Microsoft SQL Server 7.0, Service Pack 2

  • Microsoft SQL Server 7.0 OLAP Services

  • Microsoft SQL Server 7.0 OLAP Services, Service Pack 2

  • OLAP Add-in Manager

  • OLAP Server Client Tools

  • Microsoft Data Access Components (MDAC) 2.6

Business Desk Client

Before you install the Commerce Server Business Desk client, you must install the following software:

  • Microsoft Windows 98, Microsoft Windows Millennium Edition, Microsoft Windows NT 4.0, Windows 2000 Professional, Windows 2000 Server, or Windows 2000 Advanced Server

  • Internet Explorer 5.5

  • Microsoft Office Web Components or SQL Server 2000 Client Tools


Installing the Business Desk Client

You must install the Commerce Server Business Desk client for all computers from which you want to access Business Desk, including the computer running Commerce Server. After you unpack a site, you can install the Business Desk client by connecting to the Uniform Resource Locator (URL) for the Business Desk application.

Business managers can also download and install the Business Desk client. Before installing the Business Desk client, the following software must be installed on the client computer:

  • Microsoft Internet Explorer 5.5, available on the Commerce Server 2000 CD.

  • Microsoft Office Web Components or SQL Server 2000 Client Tools.

If you are using the Windows 2000 operating system, you must have Administrator access rights to install the Business Desk client.

Notes

  • You must have a connection to the Internet to install the Business Desk client.

  • It is strongly recommended that your client computer have a high-speed connection to your Business Desk application.

To install the Business Desk client

  1. Click Start, point to Programs, and then click Internet Explorer.

  2. In the Address box, type the URL for your installation of the Business Desk (for example, http://<computername>/BusinessDesk), and then press Enter.

  3. In the Browse for Folder dialog box, select a folder in which you want to install the Business Desk client, and then click OK.

    The Business Desk Client Setup begins. In the upper portion of the Business Desk Client Setup screen, troubleshooting tips are displayed for downloading the Microsoft ActiveX controls needed to install the Business Desk Client.

    In the lower portion of the screen, check marks appear when each installation item is complete. When all four tasks are complete, the Business Desk installation is complete. A link to Business Desk is displayed at the bottom of the screen.

    Note

    • If you are unable to download the ActiveX controls, follow the instructions on the Business Desk Client Setup screen.
  4. When you have completed the Business Desk installation, close Internet Explorer.

The Business Desk icon now appears as a shortcut on your desktop, and a shortcut Business Desk is added to the Start menu.

To start Business Desk

  • Double-click the Business Desk icon on your desktop or click Start, and then click the Business Desk shortcut.

Notes

  • You can run two Business Desk clients for different sites at the same time on your computer.

  • You cannot open two instances of the same Business Desk client for the same site on your computer.

See Also

Hardware Requirements

Software Requirements

Uninstalling the Business Desk Client


Uninstalling Commerce Server

To uninstall Commerce Server 2000, you must perform the following steps in the order shown. Detailed instructions for each step follow:

  1. Remove the Commerce Server 2000 Solution Sites. Perform this step to remove the Blank site, or other Solution Sites you may have downloaded from http://www.microsoft.com/commerceserver/solutionsites. This step removes the Solutions Sites from the Microsoft Commerce Server\PuP Packages folder so you cannot unpack these sites again. It does not remove the unpacked Solution Sites.

  2. Remove the Commerce Server 2000 platform. Perform this step to remove the Commerce Server Runtime objects, Administration Tools, Predictor global resource, and Direct Mailer global resource.

  3. Delete the Commerce Server 2000 installation folder.

  4. Delete the Commerce Server 2000 databases, for example, the Administration database, Data Warehouse database, Profiles database, and Catalogs database.

  5. Delete the Commerce Server 2000 Analysis server databases (called OLAP server in SQL Server 7.0).

  6. Delete the Commerce Server 2000 site virtual directories. Perform this step only if you have unpacked a site.

  7. Delete the ISAPI filter (CSAuthFilter) from Internet Information Services. Perform this step only if you have set Autocookie or changed the Authentication Filter setting on a Commerce application from the default set by the Solution Site packages.

  8. Delete the Commerce Server 2000 site folders and files. Perform this step only if you have unpacked a site.

  9. Delete the Direct Mailer jobs in SQL Server. Perform this step only if you installed Direct Mailer and created Direct Mailer jobs. If you do not perform this step and you re-install Direct Mailer at a later date, the direct mail jobs from the previous installation will be enabled.

After performing these steps, it is recommended that you restart your computer.

The following procedures provide detailed instructions for performing each of these steps.

Step 1: Remove the Commerce Server 2000 Solution Sites

  1. Click Start, point to Settings, and then click Control Panel.

  2. Double-click Add/Remove Programs.

  3. In the Add/Remove Programs dialog box, click Commerce Server Solution Sites Remove.

Step 2: Remove the Commerce Server 2000 platform

  1. Click Start, point to Settings, and then click Control Panel.

  2. Double-click Add/Remove Programs.

  3. In the Add/Remove Programs dialog box, click Commerce Server 2000 Remove.

  4. Click Yes to confirm that you want to remove Commerce Server 2000.

  5. Click Yes to restart your computer if prompted.

Step 3: Delete the Commerce Server 2000 installation folder

  1. Using Windows Explorer go to the folder where Commerce Server is installed (for example, C:\Program Files\Microsoft Commerce Server).

  2. Right-click the folder you want to delete, and then click Delete.

  3. Click Yes to confirm the deletion.

Step 4: Delete the Commerce Server 2000 databases

  1. Click Start, point to Programs, point to Microsoft SQL Server or Microsoft SQL Server 7.0 (depending on your installed database), and then click Enterprise Manager.

    Note

    • In SQL Server Enterprise Manager, make sure that SQL Server is running (the icon in the Enterprise Manager window displays a green light). If it is not running, right-click the name of the SQL Server computer, and then click Start.
  2. Expand the nodes to the following path: \Microsoft SQL Servers\SQL Server Group\SQL Server Name\Databases.

  3. Right-click the database you want to delete, and then click Delete.

    Repeat this step for each database you want to delete.

Step 5: Delete the Commerce Server 2000 Analysis server databases (called OLAP server in SQL Server 7.0)

  1. Click Start, point to Programs, point to Microsoft SQL Server, point to Analysis Services, and then click Analysis Manager.

  2. Expand the nodes to the following path: \Analysis Servers\SQL Server Name.

  3. Right-click the database you want to delete, and then click Delete.

  4. Click Yes to confirm folder deletion for each database you want to delete.

  5. Repeat Steps 3 and 4 for each database you want to delete.

Step 6: Delete the Commerce Server 2000 site virtual directories

  1. Click Start, point to Administrative Tools, and then click Internet Services Manager.

  2. Expand the nodes to the following path: \<computer name>\<IIS Web site name>.

  3. Right-click the virtual directories you want to delete (for example, Retail or Supplier), and then click Delete.

  4. Click Yes for each virtual directory you want to delete.

  5. Repeat Steps 3 and 4 for each virtual directory you want to delete.

Step 7: Delete the ISAPI filter from Internet Information Services

  1. Click Start, point to Administrative Tools, and then click Internet Services Manager.

  2. Expand the nodes to the following path: \<computer name>\<IIS Web site name>. For example, CSServer1\Default Web Site.

  3. Right-click the IIS Web site, and then click Properties.

  4. In the ISAPI Filters tab, select CSAuthFilter, and then click Remove.

Step 8: Delete the Commerce Server 2000 site folders and files

  1. Using Windows Explorer go to the directory (for example, C:\Inetpub\wwwroot) where the site files were installed.

  2. Right-click the folder you want to delete, and then click Delete.

  3. Click Yes for each folder you want to delete.

  4. Repeat Steps 2 and 3 for each folder you want to delete.

Step 9: Delete the Direct Mailer jobs in SQL Server

  1. Click Start, point to Programs, point to Microsoft SQL Server or Microsoft SQL Server 7.0 (depending on your installed database), and then click Enterprise Manager.

  2. Expand the nodes to the following path: \Microsoft SQL Servers\SQL Server Group\SQL Server Name\Management\SQL Server Agent\Jobs.

  3. The Direct Mailer jobs appear in the right pane of the SQL Server Enterprise Manager.

  4. Select the Direct Mailer job(s) you want to delete, and then click the Delete button on the toolbar.

After performing these steps, it is recommended that you restart your computer.

See Also

Uninstalling the Business Desk Client


Uninstalling the Business Desk Client

To uninstall the Business Desk client

  1. Click Start, point to Settings, and then click Control Panel.

  2. Double-click Add/Remove Programs.

  3. Select Commerce Server 2000 Business Desk (application name), and then click Change/Remove.

    The Business Desk client is now removed from your computer.

See Also

Installing the Business Desk Client

Uninstalling Commerce Server


Commerce Server Architecture

Microsoft Commerce Server 2000 provides a rich and extensible foundation for building sophisticated e-commerce applications that integrate with your existing back-end systems. Because the architecture is based on the Component Object Model (COM), it is easy to extend the platform by choosing from the large number of integrated third-party solutions available, or by having your site developers customize Commerce Server tools to meet your business needs. In either case, Commerce Server has been designed for building tailored, scalable e-commerce solutions that optimize the user experience and provide business managers with real-time analytics and control of their online businesses. Additionally, Commerce Server takes full advantage of Microsoft Windows 2000, including support for the Microsoft Active Directory service, and is optimized for use with other .NET Enterprise Servers.

This section provides a summary of the major components of the Commerce Server architecture.

This section contains:

  • Overview of Commerce Server Architecture. Describes the architecture of Commerce Server, and provides a figure that illustrates its components.

  • Commerce Server and .NET Enterprise Servers. Describes the .NET technologies that typically are used with Commerce Server.

  • Commerce Server Manager Architecture. Describes resources, sites, applications, and Web servers, and how each one is used in Commerce Server.

  • Business Desk Architecture. Describes the components of Commerce Server Business Desk, and the Business Desk Framework.


Overview of Commerce Server Architecture

At a high level, Commerce Server is comprised of five main systems: the Business Analytics System, the Product Catalog System, the Targeting System, the Profiling System, and the Business Processing Pipelines System. Each of these systems is designed to be easily customizable by a site developer to meet your business needs.

Business managers use Commerce Server Business Desk to work with the Commerce Server systems, for example, to update catalogs, target content to users, profile users and organizations, and analyze site usage and productivity. System administrators use Commerce Server Manager to configure the system resources and manage the applications, databases, and Web servers.

Commerce Server systems, Business Desk, Commerce Server Manager, and the Commerce Server databases are preconfigured and packaged in the Solution Sites, which site developers can use as a starting point for building a custom site and integrating third-party applications.

The following figure provides an overview of the Commerce Server architecture.

A figure providing an overview of Commerce Server
Solution Sites
Commerce Server Manager
Business Desk
Business Analytic System
Targetting System
Product Catalog System
Profiling System
Business Processing Pipeline Systems
SQL Server
SQL Server
SQL Server
ODBC
LDAP
Commerce Server Data Warehouse
Catalogs, Campaigns, Orders
Profiles
Other Applications


Commerce Server and .NET Enterprise Servers

Although Commerce Server 2000 is a stand-alone product, it is designed to operate seamlessly with other products that, taken together, comprise .NET Enterprise Servers. The .NET Enterprise Servers are Microsoft's comprehensive family of server applications for building, deploying, and managing scalable, integrated, Web solutions with fast time to market. You can use .NET Enterprise Servers to build systems that integrate Commerce Server sites with the rest of your management information system. If you have a need for this level of integration, you can implement one or more of the .NET technologies in conjunction with Commerce Server.

Some of the .NET technologies that typically are used with Commerce Server include:

  • Microsoft BizTalk Server 2000

  • Microsoft SQL Server 2000

  • Microsoft Application Center 2000

  • COM+ (an extension to the Component Object Model) Services

  • Microsoft Host Integration Server 2000

BizTalk Server

Microsoft BizTalk Server 2000 provides a comprehensive solution for business-to-business electronic document exchange and business process integration. BizTalk Server acts as a business document gateway between trading partners, and manages the data translation, encryption, digital signatures, and document tracking services for many different transport mechanisms.

You can integrate Commerce Server and BizTalk Server, for example, to exchange catalogs of products that you post on your Web site, and to send orders entered on your Web site to suppliers for fulfillment. For more information about integrating Commerce Server and BizTalk Server, see Integrating with BizTalk Server and Using BizTalk Server and Commerce Server.

SQL Server

Microsoft SQL Server 2000 provides a scalable database that combines ease of use with complex analysis and data warehousing tools. SQL Server includes a rich graphical user interface (UI) along with a complete development environment for creating data-driven applications.

Commerce Server takes advantage of SQL Server data warehousing and analysis capabilities in several key areas. The Commerce Server Data Warehouse, for example, uses SQL Server Data Transformation Services (DTS) to transform data stored in SQL Server databases to the format used by Commerce Server resources.

Application Center

Microsoft Application Center 2000 is a high-availability deployment and management tool for Web applications built on Windows 2000. It extends the core set of Web application services found in Microsoft Windows 2000 (Internet Information Services (IIS) 5.0, Active Server Pages (ASP), COM+, Message Queuing), and provides a suite of monitoring, testing, and diagnostic tools not available in the core operating system. Application Center is designed for customers with high-end requirements for scalability and availability.

You can use Application Center with Commerce Server in order to perform deployments, incremental updates to your Web site, and rollbacks. For more information about using Application Center with Commerce Server, see Deploying Your Site.

COM+ Services

Microsoft COM+ Services (Component Services, including MTS) is a unified programming model that is used to build component-based, three-tier distributed applications. COM+ builds on the Microsoft Component Object Model (COM) by combining COM with the transactional features of Microsoft Transaction Server (MTS). It extends the programming environment by adding a rich set of features to make it easier for site developers to develop, deploy, and administer highly-scalable, distributed, component-based solutions.

Host Integration Server

Microsoft Host Integration Server 2000 is a comprehensive integration platform that provides support for Internet, intranet, and client/server technologies while preserving investments in existing systems. By recognizing that accessing existing data is only the first step in leveraging enterprise computing resources, Host Integration Server provides enterprise developers with a way to create distributed applications that make the most of either client/server or Web computing and host information.

See Also

Integrating with BizTalk Server

Using BizTalk Server and Commerce Server

Deploying Your Site

Programming with Commerce Server Objects


Commerce Server Manager Architecture

Commerce Server Manager is a tool that you use to manage and configure Commerce Server 2000 resources, sites, applications, and Web servers. The Microsoft Management Console (MMC), a Windows-based interface that is included in Microsoft Windows 2000, hosts Commerce Server Manager. This section describes each Commerce Server Manager object and how the objects interact.

The following figure shows the Commerce Server Manager console and identifies its parts.

Click the illustration to enlarge or reduce.

This section contains:

  • Resources

  • Sites

  • Applications

  • Web Servers

  • Using Commerce Server and IIS


Resources

A resource is an entity that provides functionality to the applications in a Commerce Server site.

A resource is comprised of one or more COM objects that are used on the Web pages of an application to access the resource functionality. Resources include properties that are stored in the Administration database. These properties can be accessed and changed using Commerce Server Manager (and changed programmatically through the Config objects).

There are two types of resources: global resources and site resources. Third parties can develop custom global resources and site resources to work with Commerce Server. For more information, see Integrating Custom Resources.

Global Resources

Global resources are available for use by all sites.

Commerce Server Setup creates some global resources; others are created when you unpack a site using Commerce Server Site Packager. Only resources with global-level properties appear in Commerce Server Manager under the Global Resources node. Every site that uses a global resource also uses the properties that you assign to that global resource.

The following table lists and describes the global resources included with Commerce Server.

Global resource | Description | Installed by
Commerce Server Direct Mailer (also a Windows 2000 service) | Sends personalized or non-personalized mailings to large groups of recipients. | Commerce Server Setup
Predictor (also a Windows 2000 service) | Adds predictive capabilities to your Web site, and builds complex analysis models that you can use to identify population segments and user trends. | Commerce Server Setup
Data Warehouse | Imports and manages Web site data from Web log files, Commerce Server databases, and other data sources. | Commerce Server Site Packager
CS Authentication | Configures the authentication and identification method for your Commerce Server site. | Commerce Server Site Packager
Profiles | Creates data sources for storing profile data, and creates and stores profile definitions and properties. | Commerce Server Site Packager

Site Resources

Site resources provide functionality to a specific site.

In Commerce Server Manager, global resource pointers and site resources appear under a site. You configure the properties of a site resource at the site level. You configure global resource pointers to point to the global resource at the global level.

A resource can have all of its properties at the site level, or all of its properties at the global level, but it cannot have properties in both places.

The following table lists and describes the site resources included with Commerce Server.

Site resource | Description
App Default Config | Stores properties that you use to configure a site, such as currency locale and symbols, billing and payment options, privacy options, unit of measure for weight, and options for integrating with BizTalk Server.
Campaigns | Connects to the database that stores data about campaigns (ads, discounts, and direct mail).
Product Catalog | Connects to the database that stores catalog schema, and product data.
Transactions | Connects to the database that stores data for baskets and orders.
Transactions Config | Connects to the database that stores data for shipping methods and rates, tax rates, state and region codes, and order status codes.

See Also

Managing Commerce Resources

Integrating Custom Resources

Integrating a Custom Snap-in Extension

Deploying Your Site


Sites

A site is a collection of ASP-based applications that use Commerce Server Component Object Model (COM) objects, which in turn use and modify resources. A site provides a means of administering the applications in the site together.

A site typically includes at least two applications: one that users browse to view your online store, and one that business managers use to access Commerce Server Business Desk. In addition, a site may include other applications. For example, a site might include www.alpineskihouse.com, www.alpineskihouse.com/equipment, www.alpineskihouse.com/clothing, and www.alpineskihouse.com/BusinessDesk. All of these applications can be distributed across many servers.

Sites use both global resources, which are shared across multiple sites, and site resources that are defined explicitly for the site.

From a site node in Commerce Server Manager, you can package a site, and add and delete resources.

See Also

Managing Commerce Sites

Deploying Your Site

Example A: Installing on a Four-Computer Clustered Configuration

Example B: Installing on a Three-Computer Non-Clustered Configuration


Applications

A Commerce Server 2000 application is a Web site. It is a logical representation of an application in Internet Information Services (IIS) 5.0; it appears in both the Commerce Server Manager and IIS console trees. In the IIS console, an application is either at the home directory level of the Web site or at a subdirectory level of the Web site.

An application represents the Web address that a Web client accesses. When you add an application to Commerce Server, the Administration database is updated with the configuration data for the application. When you add a Web server to the application, the Active Server Pages (ASP) files are installed on the Web server computer.

When a Commerce Server site is unpacked, it typically installs two applications: one for the Web site that users access to browse and purchase products, and one for the Commerce Server Business Desk, which is used to manage that site. An application can use only the resources of the site it is belongs to.

An application includes its own Web servers, which in turn serve the ASP page content for the Web site. An application may include multiple Web servers; it always includes at least one Web server. You can set up a site at the root level of an IIS Web site or at a virtual directory any number of levels below the root.

You can perform the following functions from the IIS and Commerce Server Manager consoles:

  • From the application node in the IIS snap-in, you can set all properties available at the virtual directory level, including virtual directory properties, default documents, directory security, Hypertext Transfer Protocol (HTTP) headers, and custom errors. You can also configure Microsoft FrontPage Server Extensions and rename or delete the application.

  • From the application node in Commerce Server Manager, you can set the nonsecure and secure host name and IIS application path, enable HTTPS, enable Autocookie, enable an authentication filter, and configure settings common to all Web servers in the application.

For detailed information about properties that are inherited from IIS to Commerce Server, see Using Commerce Server and IIS.

See Also

Managing Commerce Application and Web Servers

Deploying Your Site

Example A: Installing on a Four-Computer Clustered Configuration

Example B: Installing on a Three-Computer Non-Clustered Configuration


Web Servers

In Commerce Server, a Web server is a computer with Internet Information Services (IIS) 5.0 installed. To use a Web server with Commerce Server 2000, you must install Commerce Server on the same computer as IIS.

In Commerce Server, a Web server is associated with one or more applications; different applications can share the same Web server. The Web server contains the ASP files and subfolders for the application. One application may have several Web servers that, taken together, form a Web farm.

To add ASP files to a Web server, you use Commerce Server Site Packager to unpack the Web server. The Commerce Web server object is added to the application when unpacking is complete. In Commerce Server Manager, a Web server object is exposed under the associated application.

The Web server object contains properties needed by the Data Warehouse to import log files. From the Web server node in Commerce Server Manager, you can view or change the following properties.

Property | Description
Server name | The name of the computer on which IIS is installed.
IP Address | The Internet Protocol (IP) address for the IIS Web site of the application.
Log file path | The path to which the IIS Web site of the application is to write events, for example, C:\Winnt\System32\Log1.
Log file period | The length of time the IIS Web site of the application will retain the log file before it overwrites the data.

When a Web server is added, these properties are automatically populated from IIS 5.0 to the Commerce Server Administration database.

Commerce Server supports Web servers that are not running IIS and do not include Commerce Server components. This enables you to make the Web server log files available to the Data Warehouse for import. For more information, see Adding a Non-Commerce Application and Web Server.

It is possible that different applications might share a Web server. Each application has a unique URL; unique URLs can be served by a single IIS Web site. For example, www.microsoft.com and www.microsoft.com/commerceserver could be served by the same IIS Web site.

If you are running a Web farm, you need to replicate your Web servers. It is recommended that you use Application Center Server 2000 or another product to perform content replication.

See Also

Using Commerce Server and IIS

Deploying Your Site

Example A: Installing on a Four-Computer Clustered Configuration

Example B: Installing on a Three-Computer Non-Clustered Configuration


Using Commerce Server and IIS

The system administrator, who is responsible for the day-to-day administration of Commerce Server 2000, is typically also responsible for administering Internet Information Services (IIS) 5.0.

Although Commerce Server runs on top of IIS, the relationship between IIS and Commerce Server objects is not strictly hierarchical. The total set of properties that affect a Commerce Server site includes properties that are:

  • Set at the IIS level only.

  • Set within Commerce Server only, independent from IIS.

  • Inherited from IIS.

You use the IIS snap-in to manage Web site access permissions and security, performance, directories and paths, the identification of Web site names, and Internet Protocol (IP) addresses and ports.

You use Commerce Server Manager to perform the following tasks:

  • Manage global and site Commerce Server resources, configure Commerce Server-specific properties, configure database connection strings for resources, and add and remove Web servers from an application.

  • At the Commerce Server application level, you can specify the IIS application path, IIS Web site, non-secure and secure host names, and IP port and secure IP port. You can also configure properties to enable HTTPS, enable Autocookie, and select an authentication filter. These properties apply to all of the Web servers used by the application.

    When you change port properties in Commerce Server, they are not automatically changed in IIS. The following port properties in IIS are the port properties that are actually used:

    At the application level

    • Transmission Control Protocol (TCP) port

    • Secure Sockets Layer (SSL) port

    At each Web server

    • Internet Protocol (IP) address

    • Log file path

    • Log file period

    If you change the port properties in IIS, you must also change them in Commerce Server.

    Web server properties are inherited from IIS and stored in the Administration database for ease of access. If the IIS properties change, then you need to synchronize the Administration database either by manually updating the new values, or by clicking the Synchronize values button on the Web Servers tab in the Application Properties dialog box. For more information, see Configuring an Application.

    When you click the Synchronize values button, Commerce Server synchronizes the properties at the application level and the properties for all the Web server objects below the application. For the properties at the application level (TCP port and SSL port), Commerce Server reads the values for the first Web server. It assumes that the Web servers have all been configured identically, which must be the case for a Web farm to operate correctly.

  • At the Commerce Server Web server level, you can view and change properties for the IP address, log file path, and log file period.

The following figure shows the objects on the IIS and Commerce Server Manager console trees, and the relationships among these objects.

A figure illustrating the relationships between objects in IIS and Commerce Server Manager

Click the illustration to enlarge or reduce.

See Also

Administering Commerce Server

Adding a Non-Commerce Application and Web Server

Deploying Your Site

Example A: Installing on a Four-Computer Clustered Configuration

Example B: Installing on a Three-Computer Non-Clustered Configuration


Business Desk Architecture

Commerce Server Business Desk is a Web-based site management tool included with Microsoft Commerce Server 2000. Business Desk hosts business management modules that you use to configure, manage, and analyze your sites. For example, you use Business Desk modules to update pricing information in your catalogs, target new advertisements to specific users, and then run reports to measure how these changes affect site productivity.

Business Desk has two parts: the Business Desk application and the Business Desk client.

  • Business Desk application. The management tool you use to configure, manage, and analyze your site. After you install Commerce Server, you can unpack a Solution Site to install a Business Desk application. Business Desk is accessible from any computer running Microsoft Internet Explorer 5.5, providing you with secure remote access.

  • Business Desk client. The client software that is installed locally on your computer, providing the interface to the Business Desk application. When you first access the Business Desk application (via a URL), the Business Desk client is downloaded and installed onto your computer. It is recommended that the computer on which you run the Business Desk client has a high-speed connection to the Business Desk application.

The following figure shows how you can use Business Desk clients to remotely access the Business Desk application to update a Web site.

Business Desk
Client
Business Desk
Client
Business Desk
Client
Commerce Server Data Center
Business Desk
Application
Your
Web site
New York
Tokyo
Chicago
New York
The Internet
A figure illustrating how a Business Desk client accesses the Business Desk application

This section contains:

  • Business Desk Components

  • Updating Your Web Site with Business Desk

  • Securing Business Desk Modules

  • Customizing Business Desk

  • Business Desk Framework


Business Desk Components

You use modules, the main components of Commerce Server Business Desk, to manage different aspects of your site. The following table lists the Business Desk modules and the categories that contain them, and describes the tasks you can do with each one.

Category | Description
Analysis Reports Completed Reports Segment Viewer | Run and review reports that represent your site activity, and perform predictive analysis. The Analysis modules come with a rich set of reports covering various aspects of your site.
Campaigns Campaign Manager List Manager Campaign Expressions Target Group Reference Tables Publish Campaigns | Create and schedule marketing campaigns. You add customer information and manage campaigns and campaign items, such as creating advertising banners, Direct Mailer jobs, and product discounts. Each campaign item can be targeted to specific users thereby creating a highly personalized user experience.
Catalogs Catalog Designer Catalog Editor Catalog Sets | Import catalogs, create catalogs, add and price products. Create custom catalogs that contain special prices and are displayed only to certain users, for example, members of a club.
Orders Basket Manager Data Codes Order Status Shipping Methods Tax Rates Publish Transactions | Search the Commerce Server database for existing order information, and add, delete, approve, and change order information. Add, delete, and change shipping rates and tax rates.
Users Users Organizations Profile Designer Site Terms Editor Publish Profiles | Create and change users, organizations, and profiles. Create and change site terms.

See Also

Working with Business Desk


Updating Your Web Site with Business Desk

The following figure shows how you can use the Commerce Server Business Desk modules to update your Web site. For example, site data is gathered from your Web site and imported to the Data Warehouse, and then you can run analysis reports. You use the Campaigns modules to create and display advertisements, discounts, and promotions. You use the Catalogs modules to update information in your catalog. You use the Orders modules to research user orders. You use the Users modules to reset user passwords, change other user profile information, and specify the profile data to be collected.

A figure illustrating how Business Desk modules update your Web Site
Users
Orders
Campaigns
Orders
Profiles
Commerce Server
Data
Warehouse
Register
Users
Business Desk
Commerce Server Databases
Your Web Site
Display Catalogs
Catalogs
Catalogs
Campaigns
Analysis
Record
Activity
Take
Orders
Display
Ads


Securing Business Desk Modules

Commerce Server Business Desk provides role-based security: Business Desk users can view and manage only those modules for which they are authorized. For example, if a group of users does not use the Catalog Designer module, you can prevent that module from appearing in the navigation pane when those users access Business Desk. After the site developer limits user access to a module, a user without permissions to the module will not see it.

Note that the ability to limit access to specific modules in Business Desk is not intended to prevent a malicious security violation. Rather, it prevents users from seeing Business Desk modules that are outside their areas of responsibility.

System administrators implement security. To secure a Business Desk module, the system administrator must set Windows Access Control Lists (ACLs) on the module Active Server Pages (ASP) files. For more information, see Security.

Notes

  • If you secure one of the following modules, all the modules are secured by default: Publish Profiles, Publish Campaigns, and Publish Transactions.

  • This feature does not limit access to specific data within Business Desk. To limit access to the data a user sees in Business Desk, contact your system administrator or site developer to implement security at the database level. For example, if you want to limit a Business Desk user to editing one specific catalog, your site developer can implement that security.

  • If a user connects to Business Desk from the Internet via an unauthenticated session, Internet Explorer prompts for the user name, password, and domain name in order to authenticate the user for the Business Desk application.

See Also

Limiting Access to Business Desk Modules

Building Business Desk Modules


Customizing Business Desk

Site developers and system administrators can customize Commerce Server Business Desk to meet your business needs. For example, a site developer can add or remove features, integrate Business Desk with an existing application, or change the way Business Desk performs specific functions.

The following table describes several areas where you can coordinate customization with your system administrator or your site developer.

Business Desk component Customization and coordination
Analysis: Reports module
  • Your site developer can create new or customized reports for your business needs. You can also create custom reports based on the existing dynamic reports in the Reports module of Business Desk.

  • The system administrator is responsible for importing data into the Data Warehouse on a regular basis. After data is imported into the Data Warehouse, you can run reports against the data and analyze it.

  • The system administrator can customize the data from the Web log files that is imported into the Data Warehouse and can set user and visit definitions that affect the results of the reports you run.
Analysis: Segment Viewer module
  • To view Segment models you use the Segment Viewer module in Business Desk. Your system administrator must build the Segment models.

  • To view Prediction models, you use the Predictor Model Browser in Commerce Server Manager. Contact your system administrator for information about viewing Prediction models.
Users
  • The system administrator creates profile definitions using Commerce Server Manager, and adds data sources, data members, and data objects. When you use Business Desk to add profile properties to the profile definition, you select the data source, data member, and data objects as needed.
General System Settings
  • The system administrator configures system settings such as units of measure, currency options, payment options, and Web site registration and security options. You need to coordinate any changes to these options or settings with the system administrator.

See Also

Business Desk Framework

Building Business Desk Modules


Business Desk Framework

Commerce Server Business Desk is a user interface framework implemented primarily as Active Server Pages (ASP) containing Dynamic Hypertext Markup Language (DHTML). This framework provides a structured environment in which third party developers can easily extend the management functionality provided with Commerce Server 2000. This environment includes structured page navigation, standard mechanisms for data manipulation, shared utility routines, and a multitude of conventions that help assure a consistent user experience.

By default, every Commerce Server Web site has a distinct instance of Business Desk associated with it. Though Business Desk shares the same set of commerce resources with the Web site, such as various databases, it exists as a separate ASP application, with a directory structure and virtual root of its own.

The Commerce Server Business Desk Framework provides the environment in which Business Desk modules are run. The following figure shows how a set of configuration files provides two important types of information needed for the Business Desk Framework to support navigation. The first type determines the set of categorized modules that will be accessible within Business Desk. The second type is used to build and manage the taskbar, which will may be unique to each action page.

Master Configuration File
Module
Configuration
File
Module
Configuration
File
Module
Configuration
File
Toolbar Buttons
and Menus
Navigation Pane
Analysis
Campaigns
Catalogs
Orders
Users
Nav
ListSheet HTC
DynamicTable HTC
Individual EditField HTCs
Module 1
Module 1
Module 1
?
?
?
?
A figure providing an overview of Commerce Server

The figure also shows how modules are typically designed such that their initial action page is a list page, from which edit pages may be accessed using task buttons. It also shows the typical design in which a user must return to the initial list page in order to move to a different module.

The Business Desk Framework has the following characteristics:

  • The master configuration file, together with a set of module configuration files, provides the information needed by the Business Desk Framework to manage both the navigation pane and the taskbar displayed on each action page.

  • Action pages that display read-only lists, known as list pages, are always displayed along with the navigation pane. This means that to move to a different module, the user must do so from a list page, not an edit page. List pages are read-only (with the exception of Delete tasks), which means that users will generally not need to be presented with warnings about leaving the module without having saved changes to data.

  • Navigation between action pages should typically be done using the task buttons on the taskbar. This mechanism allows the Business Desk Framework to provide services that occur during transition between action pages. You should minimize the direct linking of action pages to buttons within a page.

See Also

Building Business Desk Modules


Commerce Server Concepts

To optimize your use of Microsoft Commerce Server 2000, it is important that you have a sound understanding of the underlying concepts on which it is built.

This section contains:

  • Site Management Cycle. Describes how you can use Commerce Server you to continuously collect data about user activity on your Web site, analyze the data, and then use the results of the analysis to update your site.

  • Roles and Responsibilities. Describes how the Commerce Server design targets the skills of three key groups: Web site developers, system administrators, and business managers. Lists the interfaces and tools available for each group.

  • Profiles. Describes Commerce Server profiles, how profiles are created, and how profiles are used in Web site management.

  • User Lists and Mailing Lists. Describes Commerce Server user lists and mailing lists, and how these lists are used in Web site management.

  • Cookies and Authentication. Describes Commerce Server cookies and how Commerce Server uses them.

  • Catalogs: Products for Sale. Describes Commerce Server catalogs, how catalogs are used in Web site management, how catalogs are structured, and how they are populated with product data.

  • Data Warehouse. Describes the Commerce Server Data Warehouse, how it is used in Web site management, and how it is populated with data.

  • Prediction and Data Mining. Describes Commerce Server analysis models, how they are created, and how they are used in Web site management.

  • Pipelines. Describes Commerce Server pipelines and how to use them.

  • Targeting and Personalization. Describes Commerce Server targeting and personalization, and how they are used in Commerce Server to perform targeting and personalization.

  • Campaigns: Ads, Discounts, and Direct Mail. Describes Commerce Server campaigns, how campaigns are used in Web site management, how campaigns are structured, and how they are processed.


Site Management Cycle

E-commerce Web sites are corporate assets that business managers must continuously analyze and enhance in order to keep their Web sites competitive. Business managers need to quickly analyze user activity to measure the effectiveness of their sites, and then use the results to fine-tune them. This process of continuously analyzing and enhancing a site defines the site management cycle for an e-commerce site.

A figure that shows the stages of the site management cycle
Users and Customers
Business Manager
Site Developer
Analyze
Enhance
Deploy
Web Site

Commerce Server 2000 provides a set of features to manage and increase the effectiveness of your site. Using Commerce Server, you can:

  • Collect and Store User Data

  • Analyze User Data

  • Update Your Site

  • Implementing the Cycle - A Team Effort

By analyzing data about user activity on your site, you can make decisions about how to improve your site and meet business goals.

Collect and Store User Data

You can collect three types of data about the users who visit your site:

  • Explicit profile data. Obtained when users provide information about themselves by completing online forms, surveys, and polls.

  • Click history. Obtained when users visit your site and click links to site pages. The click history includes the length of time a user spent visiting your site, referring URLs, ad clicks, ad reach, click frequency, and the "path" the user takes through the site, including entry and exit pages. For example, you can collect browsing activities for a particular user session in which the user spent 17 minutes at the site, viewed catalog descriptions of three catalog products, added two of them to the basket, clicked on one promotional ad, and then added the promoted item to the basket.

  • Transaction history. Obtained when users purchase products. The transaction history records baskets and orders. For example, the transaction history could include the user name, shipping address, date and time, product purchased, and total order value.

This data is collected in the Web server log files and the Commerce Server databases. On a regular basis the system administrator imports the data from the Web server log files and Commerce Server databases into the Commerce Server Data Warehouse. The Data Warehouse includes a central database that contains a large amount of data collected from several different data sources, such as Web server log files, the Commerce Server databases, and any other data sources that you specify.

The following figure shows how user data is collected in Web server logs and the Commerce Server databases, and is then stored in the Data Warehouse.

A figure showing how user data is collected and stored
Commerce Server Data Warehouse
User profile data
Event data
Transaction data Campaign data
Catalog data
Commerce Server Database
Business Desk
collect
import
display
import
Web Server Logs
Web Site
User

Analyze User Data

You analyze data in the Data Warehouse to determine important information about your business. You can identify the types of users who visit your site, what is selling well, and which advertising campaigns are successful.

To analyze data about user activity on your site, you use the Analysis modules in Commerce Server Business Desk. You can analyze user activity by running reports against the Data Warehouse, or by viewing analysis models that are generated by the Commerce Server Predictor resource.

The following figure shows how you can use Business Desk to access data in the Data Warehouse, and then perform different types of analysis.

A figure showing how data can be analyzed
Business Desk
Analyze User Data
Run Reports
View Segment Models
Predictor Resource
Site Usage Data
Site Usage Data
Commerce Server Data Warehouse

Commerce Server provides two types of reports that you can use to analyze site activity:

  • Dynamic reports. Transform specific data into a Microsoft® PivotTable® format from which you can rearrange columns and create charts.

  • Static reports. Appear in a browser window in HTML format. You can send these reports to others by e-mail, post them on your Web site, and edit them in other applications. For example, using Microsoft Internet Explorer, you can export the report into a Word document, and then edit it.

Commerce Server includes several reports that you can run from Business Desk, such as advertising reports, product sales reports, and Web usage reports. You can use one or more of these reports, or your site developer can customize a report to retrieve other data. For a complete list of reports provided with Commerce Server, see Commerce Server Reports.

In addition to analyzing reports, you can analyze Segment models using the Segment Viewer module in Business Desk. Segment models identify segments of the user population visiting your site. A segment is a group of users who share similar characteristics. For example, one segment of users may be female users who purchase science fiction books. Another segment may be male users who purchase books on golf. After you have identified the characteristics of a user segment, you can use this information to update your site and then target content to that user segment.

Update Your Site

Based on your analysis of user data, you can make changes to your site to refine how you target users, promote popular pages, or make popular products easier to find. For example, if you discover that all your users view a page that is four clicks away from the home page, you can redesign your site so that page is only one click away.

You can also use the results of your analysis to target specific groups of users, to sell certain products in your catalog, or to create advertisements or discounts. For example, you sell sporting goods on your site. You analyze user activity, and then use Business Desk Campaigns to generate a list of registered users who enjoy biking. You then target an ad for a new bike accessory to this group so that the ad displays prominently when those users visit your site. For more information about targeting users, see Targeting and Personalization.

Implementing the Cycle - A Team Effort

To effectively implement the site management cycle, the business manager, site developer, and system administrator need to communicate and work together to implement updates to the site. You should establish a process to facilitate this communication. For example, to update a large set of user profiles in bulk, the business manager contacts the system administrator, who then performs this task. To add new functionality to Business Desk, such as a module for selling gift certificates, the business manager contacts the site developer and communicates the requirements.

In many organizations, the business manager, system administrator, and site developer may each work in different departments, cities, or countries, so it is important to establish an effective process for communication, and to assess the process periodically to ensure that it is working.

For an overview of the tasks typically performed by the business manager, site developer, and system administrator, see Roles and Responsibilities.

See Also

Targeting and Personalization

Roles and Responsibilities

Profiles

Prediction and Data Mining

Data Warehouse


Roles and Responsibilities

Commerce Server 2000 provides a set of features and tools to develop, deploy, and manage Web sites. Working with Commerce Server requires specific skills that span three areas of expertise within an organization. In the following table, Commerce Server features are grouped for use by the three general role categories within an organization, with the skill sets shown.

Role | Expected knowledge
Site developers | Dynamic Hypertext Markup Language (DHTML), Extensible Markup Language (XML), Microsoft ActiveX Data Objects (ADO), HTML Components (HTC), and Active Server Pages (ASP)
System administrators | Microsoft Windows 2000 Server, Microsoft SQL Server 2000, and Internet Information Services (IIS) 5.0
Business managers | Business goals, strategies, and processes for creating and running a successful e-commerce Web site

In your organization these roles may be combined in various ways or they may have different names. However, they represent the three distinct skill sets required to use Commerce Server features.

The following table lists the three distinct roles, and provides examples of the tasks performed by each one.

Role Responsibilities Tools and user interfaces
Site developer
  • Builds the Web site

  • Integrates the Web site with existing systems

  • Migrates existing e-commerce sites and databases

  • Customizes Commerce Server Business Desk

  • Builds new Business Desk modules

  • Adds new extension snap-ins to the Microsoft Management Console (MMC)

  • Creates custom reports

  • Extends the Data Warehouse
  • Programmer's Reference

  • Pipeline Editor

  • Pipeline Component Reference

  • Using Site Packager
System administrator
  • Packages and moves sites to the production computer

  • Configures and optimizes Commerce Server resources

  • Schedules Data Warehouse import tasks

  • Schedules Direct mailer jobs

  • Builds new analysis models

  • Maintains Commerce Server databases

  • Troubleshoots the Web site environment
  • Using Site Packager

  • Administering Commerce Server
Business manager
  • Creates specifications for developing the Web site

  • Determines how the Web site should be updated in order to meet business goals

  • Requests new and customized modules for Business Desk

  • Creates advertising campaigns

  • Manages product catalogs

  • Analyzes user activity and site effectiveness

  • Manages registered users and trading partners
  • Working with Business Desk


Profiles

A profile is a set of characteristics that define any business-related item, such as a user, a company, or a context (date and time). For example, a user profile may include characteristics such as first name, last name, city, gender, age, and e-mail address. A company profile may include different characteristics, such as the company name, contact, city, and e-mail address. A context profile may include characteristics such as the date and time when a page is displayed, and the path the user takes to get to that page.

The following figure shows different types of profiles.

A figure showing different types of profiles
Click history
Length of session
Company Name
Contact
City
E-mail address
Click history
Length of session
First Name
Last Name
City
Gender
Age
E-mail address
Click history
Length of session

Company Profile

Anonymous User Profile

Registered User Profile

In Commerce Server, you use profiles to store information about business-related items. For example, you use profiles to collect data from users on your Web site. You can also enter data directly into the users and organizations profiles by using Business Desk.

The Commerce Server Profiling System consists of the Profiles resource, managed using Commerce Server Manager, and the Users modules, managed using Commerce Server Business Desk. Profile data is stored in the Profiles data store in Microsoft Active Directory™, SQL Server, both, or in any OLE DB-compliant data store. You can export data from the Profiles data store into the Data Warehouse, and then use Business Desk to analyze the profile data that is collected.

Note

  • Commerce Server does not include the Microsoft Site Server 3.0 Membership Directory. For information about migrating profile information from the Membership Directory to Commerce Server, see Migrating from Site Server 3.0.

Using Profiles in Web Site Management

Profile Structure

Collecting and Storing Profiles

Analyzing User Data

Sample Profile Definitions

Using Profiles in Web Site Management

Profiles are essential to Web site management because they provide information about the users who visit your Web site and how they use it. You use profiles to analyze user data, and you use them to target content to users.

Using Commerce Server Business Desk, you can:

  • Determine what information to collect about users visiting your site.

  • Analyze profile information.

  • Create target expressions to match content to users.

  • Create advertising, discount, and direct mail campaigns to target specific user groups.

  • Deliver personalized direct mail messages to users.

For example, assume you have a site that sells sporting goods. The following workflow provides an example of how you can use Business Desk to analyze user activity and target content to users.

  1. Your system administrator creates profile definitions for registered users and guest users.

  2. After your site has been running for a period of time, you can analyze profile data to determine who is visiting your site:
    • Run reports to analyze who is visiting your site.

    • Run reports to analyze which products in your catalog are selling well, and which ones are not selling well.
  3. Use the results of your analysis to create a campaign to target content to users:
    • Use the profiles to create target expressions and target groups.

    • Create a discount campaign to offer these specific users a discount.
  4. After the discount has been in production for a period of time, analyze the results of the campaign.
    • Run reports to analyze the success of the campaign.

    • Run reports to find out whether this group of users increased their purchases of discounted items.
  5. If your users did not increase their purchases of discounted items, create a direct mail campaign to deliver personalized messages offering the users a discount on a certain product.

For information about creating expressions and targeting content to users, see Targeting and Personalization.

Profile Structure

A Commerce Server profile consists of the following parts:

  • Profile definition. A description of the data to be collected for a given type of profile. You can have multiple profiles based on a single profile definition. For example, "User" is a profile definition, and "Address" is a profile definition. System administrators create profile definitions by using the Profiles resource in Commerce Server Manager.

  • Profile property. A characteristic that specifies the profile data to be collected when a user visits your Web site. For example, the First Name property specifies that the first name of the user should be collected. Use the Profile Designer module in Business Desk to create profile properties and add them to profile definitions.

  • Attribute. A characteristic that specifies information about the property such as the data type of the property (for example, number, string, decimal, and site term).

  • Profile. A single instance of a profile definition that contains data. Every profile is based on a single profile definition.

The following table shows a sample User profile definition, and then a single instance of the sample User profile definition with data for Sean Chai.

Profile definition: User | Profile: Sean Chai
First name | Sean
Last name | Chai
City | Seattle
Gender | M
Age | 52
E-mail address | seanchai@microsoft.com

Profile Definitions

Before system administrators create new profile definitions, they must first determine where the profile data will be stored in the database, and add the appropriate table and columns for the data. For example, assume the business manager requests a new profile definition named Music, and wants to store the following profile properties: First Concert, Last Concert, Favorite CD, and two more properties that are not yet determined. You determine that the best place to store this data is in a new table name Music, in a new SQL Server database named Arts. To create the Music profile definition, you do the following:

  • Use SQL Server Enterprise Manager to:
    1. Create the SQL Server database named Arts.

    2. Create the Music table in the Arts database, and add columns for the five data members that are to be stored there.
  • Use the Profiles resource to:
    1. Map to the new data source, Arts. You only need to perform this step once. After you have mapped a new data source to the Profiles resource, you do not need to do so again.

    2. Create a data object named Music and map it to the Music table in the Arts database.

    3. Create data members named First Concert, Last Concert, Favorite CD, Placeholder1, and Placeholder2, and map them to the appropriate columns in the Music table.

    The following figure illustrates how elements in a SQL Server database, the Profiles resource, and a profile definition map to each other.

A figure illustrating the relationships among SQL Server, Profiles, resource, and a profile definition
Enterprise Manager
Profile Resource
SQL Server Database
Data Source
Profile Definition
Table
Column
Data Object
Property
Attributes
Data Member

Arts
Database

Arts Data
Source

Music Profile Definition

Music Table
Music Object
First Concert Property
First Concert Column
First Concert Column
Single
Value Required

For detailed instructions about using the Profiles resource to extend your profiles schema, see Running the Profiles Resource.

After you create the profile definition and the properties, the business manager can use the Profile Designer module in Business Desk to add First Concert, Last Concert, and Favorite CD to the definition. To perform this step, the business manager maps these properties to the data members you created, so you need to provide the data member names. If you want to map the properties to the data members, you can do so using Commerce Server Manager.

At a later date, when the business manager determines other information to collect using the Music profile definition, the business manager can use the Profile Designer module to create two new properties and map them to the placeholder data members you created in the Music table.

The Commerce Server Solution Sites include the following sample profile definitions: Addresses, BlanketPOs (purchase orders), Organization, User Object, and Target Context. In the User Object, five unnamed properties are included so you can add properties to the User profile definition without extending your database. For a list of properties included with each profile definition, see Sample Profile Definitions.

Profile Properties

After the system administrator creates the profile definition, you can add profile properties to it by using the Profile Designer module in Business Desk. Profile properties determine what information is collected in a profile. For example, the User profile definition could contain the following properties: first name, last name, city, gender, age, and e-mail address.

The following figure shows the parts of a sample User profile definition.

A figure showing the parts of a profile definition
Profile property
Profile attributes
User Profile Definition
First Name
Single valued Required Indexed
Last Name
Single valued Required Indexed
City
(Site Term: City)
(String)
(String)
(Site Term: City)
Mexico City Montreal
New York
Gender
(Site Term: Gender)
Gender
Male
Female
Unknown
Age
(Number)
E-mail Address
(String)
E-mail Address
E-mail Address
Data type

Attributes

Each profile property has attributes. Attributes provide information about the property such as the data type of the property (for example, number, string, decimal, and site term), whether the property is single-valued (for example, only one First Name is allowed) or multi-valued, and whether the profile property is indexed, that is, whether a user visiting the Web site can perform a search using this property.

A site term is a data type that you create. It is a list of specific values that are pertinent to your site. You use a site term to assign this list of values to a property as an attribute. For example, you could create a site term named Gender, and define the following possible values: Female, Male, and Unknown. When you create a profile property named Gender and assign it the data type "site term," only one of the possible values can be assigned to the profile. You create Site Terms by using the Site Terms Editor module in Business Desk, and then you assign them to the profile definition by using the Profile Designer module.

You apply site terms to profile properties, establishing common words that you can use throughout Commerce Server, for example, to match the user preferences to content. For more information about how profiles are used to deliver content, see Targeting and Personalization.

Collecting and Storing Profiles

Profile data is collected at a Commerce site in two ways. Users visiting your site provide profile data about themselves; this is called explicit profiling. For example, when users purchase products from your site, they typically provide their name, mailing address, phone number, and e-mail address. This information is used to populate their user profile.

You can also collect data through implicit profiling. In implicit profiling, the actions of all users (anonymous and registered) are recorded in Web log files as the users interact with your Web site. For example, Web log files record the links that anonymous users click, what products they search for, the length of their sessions, and how long they visit a given Web page. Even though the users are anonymous — you do not know their names, e-mail addresses, or other information — how they use your site is still important information. For example, a click history provides a path through the Web pages visited; you can use this information to determine a particular set of interests. For information about how cookies are used in Commerce Server, see Cookies and Authentication.

Another form of implicit profiling is performed by the Commerce Server Predictor resource. If some information about a user is missing—for example, the Music Preference associated with a user—this information can be guessed by the Predictor resource based on the aggregate properties of the user population who visits your site and the CDs they purchase. For information about the prediction feature, see Prediction and Data Mining.

All the information that is collected during a specific user session is collected in a single profile, that is, one instance of a profile definition.

When profile data is initially collected, it is first stored in the Commerce Server databases and the Web server logs. The system administrator imports the profile data into the Data Warehouse on a regular basis. After the profiles are imported into the Data Warehouse, you can use Business Desk to analyze user data, and then use the results of your analysis to update your Web site or apply values to user profile properties.

Analyzing User Data

You can analyze user data in reports, or in segment models. For information about analyzing segment models, see Analyzing Population Segments.

The following table lists the reports included with Commerce Server that you use to analyze user data.

Report | Description
Distinct Users and Visits by Week | Determine whether a few people are visiting your site many times, or if many people are visiting your site at the same time.
Distinct Users by Day | Determine how many unique users visit your site on a particular day.
New Registered Users | Identify new registered users. This data can be used to create special promotional campaigns. For example, you can export the report to List Manager, and then send these users a direct mail promotion.
Registered User Properties | Review information provided by registered users. This data can be used to create special promotional campaigns. For example, you target advertisements or discounts to users who have certain properties.
Registered Users by Date Registered | Review the registration behavior of your users.
User Days to Register | Track the average number of days it takes guest users to register on your site.
User Registration Rate | Determine how successful you have been in convincing guest users to register on your site.
User Trends | Determine how successful you have been in attracting repeat visitors.

For a list of all Commerce Server reports, see Commerce Server Reports. For information about running reports, see Running Reports.

Sample Profile Definitions

Commerce Server Solution Sites include sample profile definitions. If your site developer used a Solution Site to build your site, you should have the five profile definitions listed in the following table.

Profile Definition | Properties (data type) | Description
Address | Address ID (string) | Address identifier
 | ID (string) | Organization/User Identifier
 | Last Name (string) | User last name
 | First Name (string) | User first name
 | Address Name (string) | Name for this address
 | Address Type (number) | Address/Ship to address/Bill to address
 | Description (string) | Description for this address
 | Address Line 1 (string) | First line of address
 | Address Line 2 (string) | Second line of address
 | City (string) | City name
 | Region Code (string) | State, region, or province code
 | State Name (string) | State, region, or province name
 | Postal Code (string) | Postal code
 | Country Code (string) | Country International Standards Organization (ISO) code
 | Country Name (string) | Country name
 | Telephone Number (string) | Telephone number at this address
 | Telephone Extension (string) | Telephone number extension at this address
 | Locale ID (number) | Locale in which to render the address form
 | Changed by (string) | Name of person who last changed this profile
 | Date last changed (date/time) | Date this profile was last changed
 | Date created (date/time) | Date this profile was created
BlanketPOs | Purchase Order ID (string) | Globally unique identifier (GUID) referring to the Blanket Purchase Order
 | Organization ID (string) | Organization ID
 | PO Number (string) | Blanket purchase order number
 | Description (string) | Description of purchase order
 | Changed by (string) | Name of person who last changed this profile
 | Date last changed (date/time) | Date this profile was last changed
 | Date created (date/time) | Date this profile was created
Organization | Organization ID (string) | Organization ID
 | Name (string) | Name of the organization
 | Trading partner number (string) | Trading partner number
 | Administrative contact (string) | GUID for the administrative contact
 | Receiver (string) | User ID of the person to receive products shipped from the supplier
 | Organization catalog set (string) | Organization catalog set
 | Changed by (string) | Name of person who last changed this profile
 | Purchasing manager (string) | User ID of the purchasing manager of the buying organization
 | Date last changed (date/time) | Date this profile was last changed
 | Date created (date/time) | Date this profile was created
User Object | User ID (string) | User ID
 | Logon name (string) | Logon name
 | User password (password) | User password
 | E-mail (string) | User e-mail address
 | User type (number) | User type
 | User title (string) | User title
 | Last name (string) | Last name of user
 | First name (string) | First name of user
 | Telephone number (string) | Telephone number for user
 | Telephone extension (string) | Telephone number extension for user
 | Fax number (string) | Fax number for user
 | Fax extension (string) | Fax number extension for user
 | Changed by (string) | Name of person who last changed this profile
 | Organization ID (string) | Organization ID
 | Account status (number) | Account status
 | User catalog set (string) | User catalog set
 | Date registered (date/time) | Date the user registered
 | Campaign History (string) | Campaign history
 | Partner service role flags (number) | Partner service role
 | Date last changed (date/time) | Date this profile was last changed
 | Date created (date/time) | Date this profile was created
Targeting Context | Page Group (string) | Name of the page group (for example, Sports pages)

See Also

Running the Profiles Resource

Migrating from Site Server 3.0

Migrating the Membership Directory

Business Desk Users

Commerce Server Reports


User Lists and Mailing Lists

User lists and mailing lists are text files that contain user profile properties. You use user lists to search and update user profile properties; you use mailing lists to send direct mail campaigns.

Using Lists in Web Site Management

Mailing Lists

User Lists

Generic Lists

Dynamic and Static Lists

Using Lists in Web Site Management

You use the List Manager module in Commerce Server Business Desk to import and export users lists and mailing lists in Business Desk.

  • Adding Lists to List Manager. You can export a Commerce Server Analysis report as a list to List Manager. You can import a list that you created using another application, such as SQL Server (to create a SQL table), Notepad (to create an ASCII text file), Microsoft Excel (to create a spreadsheet), or Microsoft Outlook (to export a .pst file which contains a list of addresses) into List Manager.

    For example, if you have a list of addresses in a Microsoft Excel spreadsheet, you can use List Manager to import it into Business Desk, and then use the list in a direct mail campaign. If you identify a list of users in an Analysis report, you can export the report results as a list to List Manager, and then use the list in a direct mail campaign.

    For information about importing a list into List Manager, see Importing and Exporting Lists. For information about exporting a Commerce Server Analysis report to List Manager, see Exporting a Static Report.

  • Using Lists from List Manager. You can import a user list from the List Manager module to the Users module, and then update the user profiles in the list. For example, you run the Commerce Server Customer Sales report to identify users who buy the most products, and then export the report as a list to the List Manager. You import the user list from List Manager into the Users module, and then update the user profiles in the list by assigning a special value a profile property in the user profiles. You use that value to target specific ads or discount campaigns to the users whose profiles you have modified. For information about importing a list into the Users module, see Importing a List of User Profiles. For information about modifying multiple user profiles, see Editing Multiple Users.

    You can also export the list to another application. For example, you can export a list generated from an Analysis report to a Microsoft Excel spreadsheet. For information about exporting a list to a file, see Importing and Exporting Lists.

Mailing Lists

Mailing lists contain rows of e-mail addresses for a direct mail campaign. Each row in the list contains a single recipient and is comprised of the following elements in a comma-delimited format.

Element | Description
E-mail address | Required. Name or <name@domain>.
GUID | Optional. The unique user ID that will be used to provide content in a personalized mail message.
Message format | Optional. Controls the message format type that the Collaboration Data Object (CDO) translates the results into. For example, text, MIME Encapsulation of Aggregate HTML Documents (MHTML) or Multipurpose Internet Mail Extensions (MIME).
Language | Optional. The code-page value for the mail message.
URL | Optional. Provides the ability to pass individual URLs per user to CDO.

You can create a list using any text editor, such as Notepad. You can add a mailing list to Business Desk by using the List Manager module to import ASCII text files, files from Microsoft Excel or Microsoft Outlook, or tables from SQL Server databases. To create a mailing list by using information in a .pst file from Microsoft Outlook, see the topic "Export items to a file or to a personal folder file" in Microsoft Outlook Online Help.

For information about importing mailing lists for a direct mail campaign, see Importing a Mailing List.

User Lists

User lists contain rows of user IDs and optionally, other user profile properties. You can export user lists from the List Manager module to the Profile Designer module, and then perform bulk updates on the properties for the specific users.

For example, you can import a list from the Segment Viewer module and set a property in the user profile for each user to indicate their membership in a particular segment. You can then use this information to target ads and discounts to that specified user segment.

Generic Lists

Generic lists can contain anything, and they can include headers, as in the following example:

ProductID | ProductName | Unit
1 | Socks | 100
2 | Shirts | 20

Unlike user lists and mailing lists, generic lists do not have content requirements. To use generic lists, a site developer must customize your application.

You may want to use generic lists to set product properties, for example. You run the Commerce Server Product Sales report to identify the most popular products (in terms of sales) on your Web site. You then use the List Manager module to import the result of this report as a list of products, and use the Catalog Editor module to set a property on these products that identifies them as strong sellers. You can then use this property to create target expressions, or to increase the price of these products by five percent.

Another way you can use generic lists is to mail coupons to your frequent online customers for use in your brick-and-mortar store. You can do this by running a report to analyze user purchases, exporting the results of the report as a list which includes the mailing addresses, and then using List Manager to export this list for use in a labeling application.

Dynamic Lists and Static Lists

User lists, mailing lists, and generic lists can be either dynamic or static:

  • Dynamic lists are created at run time; for example, when the list is being exported from List Manager for use in a direct mail campaign. Each time the list is requested, List Manager gathers the most recent data in the Data Warehouse. Only the information needed to create the list is stored in the database used by the List Manager. Use dynamic lists for direct mail campaigns that you will run frequently, or for lists of recipients that are updated frequently.

  • Static lists are created immediately upon request, and then stored in the database used by the List Manager. Use static lists for direct mail campaigns that you run infrequently, or for lists of recipients that do not change often.

See Also

Importing and Exporting Lists

Importing a List of User Profiles

Managing Lists of User Records

Creating a Mailing List


Cookies and Authentication

A Commerce Server cookie contains information about a user visiting your site, such as a logon ID, the date when the user last visited your site, and a time window that indicates how long the cookie is valid. Commerce Server uses cookies to identify and authenticate users, and to associate user IDs with the profile information it collects about them.

Commerce Server includes the CS Authentication resource that the system administrator uses to determine how cookies will be implemented on your site. To configure the CS Authentication resource, the system administrator uses Commerce Server Manager.

Using Cookies

Types of Cookies

CS Authentication Resource

Authenticating Users in a Web Farm

Commerce Server and the Use of Cookies

Using Cookies

Commerce Server provides different features you can apply to cookies on your site:

  • Encrypt cookies. You can configure Commerce Server to encrypt cookies generated by your applications. By encrypting cookies, you ensure that only your Commerce Server applications can read the cookies.

  • Share cookies among domains. The system administrator can configure Commerce Server to share cookies among different domains. Each cookie has a domain property that determines the domain in which the cookie is valid. The domain is determined by the string that precedes ".com" (or another extension). For example, assume you have two domains: premier.microsoft.com and msn.microsoft.com. In this example, the domain is .microsoft.com.

  • Share cookies among applications. The system administrator can configure the CS Authentication resource so that cookies can be shared among applications on the same site.

    In some cases, you may not want to share cookies among applications in the same site, because the presence of cookies will impact the analysis results of user activity on your site. For example, if you have a site that sells office supplies, and you share cookies between a supplier application and a retail application, your analysis results will not differentiate user activity between the two applications. The purchases made at the supplier site may show one user purchasing office supplies in very large quantities, but the retail site may show users purchasing supplies in small quantities.

The system administrator specifies how cookies are used in Commerce Server Manager by configuring the authentication properties for the application. For information about configuring an application, see Configuring an Application.

Types of Cookies

Commerce Server creates two types of cookies: persistent cookies and non-persistent cookies:

  • Persistent cookies. Used by Commerce Server to track anonymous users who visit your site. For anonymous users who allow cookies, these cookies are stored on the computers of the users. When you configure the CS Authentication resource, you determine how long the persistent cookie is valid, typically for several years. Persistent cookies store MSCSProfile tickets.

  • Non-persistent cookies (also known as session cookies). Used by Commerce Server to track authenticated users who visit your site. When the session ends, the cookies are deleted. Non-persistent cookies store MSCSAuth tickets.

A ticket is a property/value pair such as userID and the value of userID. For example, userID/joeuser is a ticket. Commerce Server uses tickets to store information about users visiting a site. A ticket can be stored in a cookie or in a URL query string.

Both persistent cookies and non-persistent cookies can be encrypted. These cookies contain the following data:

  • User ID. Used for persistent and non-persistent cookies. A site developer can determine the value to use as the user ID. For example, it can be either the login name or the e-mail address of a user. For anonymous users, the user ID can be, for example, a globally unique identifier (GUID) generated by one of your ASP pages. (Commerce Server includes the GenID object, which you can use to generate GUIDs.)

  • Time of last login. Used for non-persistent cookies. If a user is authenticated, leaves the computer without logging off (or is inactive for a period of time), and then returns before the close of the Time Window, then the user does not need to be authenticated again. However, if the user returns after the close of the Time Window, then the user must log in again.

  • Time Window. Used for non-persistent cookies to determine how long, in minutes, the cookie is valid.

After a user logs off a site, the authentication expires.

A site developer can add custom properties to both types of cookies.

CS Authentication Resource

The CS Authentication resource includes two parts:

  • AuthManager. A Component Object Model (COM) object that is used on every secured ASP page to check whether the user is authenticated to view the page. The Solution Sites use AuthManager. AuthManager is not dependent on any of the configuration settings that are applied during the unpacking process.

    AuthManager supports cookieless shopping. Ticket data (for example, a GUID) is appended to the query string.

  • AuthFilter. An Internet Server API (ISAPI) filter that is used at the Internet Information Services (IIS) 5.0 Commerce Server site level. It can be applied to all users visiting the site. You configure AuthFilter after the unpacking process.

    AuthFilter has three modes:

    • Windows Authentication mode. Checks the user login and password against Active Directory (or a local Security Access Manager account).

    • Custom Authentication mode. Checks the user login and password against a SQL Server database or other type of database.

    • Autocookie Generation mode. You can automatically generate cookies for anonymous users, which enables you to collect profile data about how anonymous users navigate and use your site. When anonymous users register, their persistent cookies can be updated, and you do not lose the profile data gathered when the user was anonymous.

    • AuthFilter does not support cookieless shopping.

Authenticating Users in a Web Farm

When a user logs in to your site, Commerce Server authenticates the user by verifying the login and password against the login and password stored in the Profiles data store. After Commerce Server verifies the user information, it creates a non-persistent cookie and stores it in the ISAPI filter cache for the application. The cookie specifies that the user is authenticated and is allowed to see secured pages on your site.

Commerce Server supports the single authentication of a user in a Web server farm. For example, if a user is authenticated on one Web server, and then is redirected or load-balanced to another Web server, the second Web server does not prompt the user to log in again. To support this functionality, you can use ISAPI filter (AuthFilter) that Commerce Server installs at the IIS Web site level. When the user is redirected to the second Web server, the ISAPI filter reads the user cookie and identifies that the cookie contains the user ID and that it is valid. If you are using Custom Authentication mode, no other steps are performed. If you are using Windows Authentication mode, Commerce Server performs the following steps:

  • It redirects the request for the secured page to Login.asp, which is not shown to the user.

  • On Login.asp, using the user ID, it queries the Profiles data store for the user profile. This returns the user login ID and password in clear text.

  • It appends the login ID and password to the URL, and then redirects the request for the secured page.

  • The filter intercepts the request for the secured page, and removes the user ID and password from the URL and stores the login ID and password in the ISAPI filter cache.

  • The filter then displays the secured page to the user. The user ID and password are not transmitted to the user.

Commerce Server and the Use of Cookies

When a user browses your site, the cookie is stored in the Web log files. The system administrator uses Commerce Server DTS tasks to import the site usage data in the Web log files, and the profile data in the Commerce Server database into the Data Warehouse. The Commerce Server Web log import DTS task reads the cookie data and decrypts the user ID, enabling the cookie data to be associated with the profile data. This enables you to analyze the user data.

When the data is imported, it is parsed by the user ID. Each instance of the user ID becomes a row in the Data Warehouse. The user ID is the primary key of the row, so that when analysis is performed on the user data, the data is accessed by the user ID.

If a user does not allow cookies, and you have implemented AuthManager, then the ticket data (including the GUID) is placed in an encoded URL string. The URL string may be used to pass user information between pages. By associating the GUID with the user activity that takes place on the site, Commerce Server enables you to analyze the activities of anonymous users.

See Also

Commerce Server Security

Planning for Security

Working with Site Security and Filters

Site Security Objects

Managing the CS Authentication Resource


Catalogs: Products for Sale

A catalog is a way of organizing the products you want to sell. Business Desk helps you create and organize catalogs by maintaining a description of what properties various catalog items must have. This description is called the catalog schema. The schema lists all the types of categories, products, and properties allowed in your catalog.

In Commerce Server 2000 you use catalogs to organize and manage the product data in your database for display on your site, and to target products to users.

Using Catalogs in Web Site Management

Populating Your Catalog with Product Data

Exchanging Catalogs using BizTalk Server

Catalog Structure

Catalog Organization: Hierarchies and Relationships

Unique Identifiers in a Catalog

Base Catalogs, Custom Catalogs, and Catalog Sets

Product Pricing Methods

Analyzing Catalog Sales

Using Catalogs in Web Site Management

You use the Catalogs modules in Commerce Server Business Desk to maintain, analyze, and enhance your catalogs. For example, when your site is in production, you can run reports from Business Desk to identify which products are not selling, and then create a discount campaign to sell more of these products.

Using Business Desk, you can:

  • Import catalogs from other data sources. You can import catalogs in Extensible Markup Language (XML) or comma-separated value (CSV) format from external sources. For example, if you have catalogs in other databases, you can import them to the Commerce Server catalogs database, and then use Business Desk to manage them.

    To convert a catalog to XML or CSV format, you can use your existing database management system to save the catalog in XML or CSV format, or a site developer can write a script using Microsoft Visual Basic to convert the catalog for you.

    Before you can import a catalog, the system administrator must create a shared folder on Commerce Server. You can use Windows Explorer to copy the catalog to the shared folder, and then use Business Desk to import it to the Commerce Server database.

  • Export catalogs. You can export your catalogs in XML format. You may want to export a catalog if, for example, you are selling products wholesale, and you want to export your catalogs to retailers. Or you may want to export a catalog to another application, for example, an inventory system or a pricing system.

    Before you can export a catalog, the system administrator must create a shared folder on Commerce Server or you must know the name of a directory on the server that you have access to. You can then use Business Desk to export the catalog to the shared folder or the directory.

    If you want Commerce Server to import or export catalogs on a scheduled basis, a site developer can provide this functionality.

  • Apply discounts to products. You can apply discounts to all products in a category, or to certain products that meet specified criteria. For example, if a Product.price = 20.00, then a discount of 10 percent is applied to the price of that product when users add it to their shopping baskets. For information about applying discounts to products, see Campaigns: Ads, Discounts, and Direct Mail. For instructions about adding a discount campaign, see Adding a Discount Campaign Item.

  • Edit products in the catalog. You can change the product name, price, description, and so on.

  • Update product information in real time. You can update product information, such as the product price, and then publish the changes to your Web site. For example, if shoppers have added the product to their baskets, and your site is updated before they check out, Commerce Server applies the new price to their basket. If shoppers have saved their baskets, and then return to them after you have updated the price, the new price is displayed.

  • Identify which products are selling. You can run Commerce Server reports to identify the top-selling products by units sold and by total sales, and you can identify the top-selling categories by units sold and by total sales. You can use the results of your analysis, for example, to discount products that are not selling well, or to promote accessories for products that are selling well. In addition, your site developer can customize your site to support related sells such as up sells and intelligent cross-sells.

  • Search for products. You can find products easily by performing a property search or a free-text search.

Populating Your Catalog with Product Data

You can use the Catalog Editor module in Business Desk to manually enter product data, or you can use it to import data from an XML file or a CSV file. If, for example, you already have a catalog in another database, your system administrator can export it as an XML file, and then you can use the Catalog Editor module to import the catalog into your Commerce Server Catalogs database.

Exchanging Catalogs Using BizTalk Server

BizTalk Server 2000 acts as a gateway for sending business documents between your company and your trading partners (also known as vendors). If your company and your trading partners all use BizTalk Server, you can trade catalogs, orders, documents, and other electronic forms. For example, vendors can send you their catalogs, and you can post them on your Web site with your own catalog. When users enter orders on your Web site, the orders are sent to the vendor directly to fill them.

Each of your trading partners can send you one or more catalogs of their products. Depending on how you set up your site, you can present these catalogs on your Web site as one catalog, or as different catalogs. For more information about using BizTalk Server, see Using BizTalk Server and Integrating with BizTalk Server.

Catalog Structure

A Commerce Server catalog consists of two main parts:

  • Catalog schema. A description of the categories and products for a site. The catalog schema is available to all catalogs in the site.

  • Catalog. A single instance of the catalog schema that contains data.

The following table shows a sample catalog schema, Clothes, and then a single instance of the Clothes catalog schema with data for the catalog Sports Clothes.

Catalog schema | Catalog: Sports Clothes
Category Definition: Department Category Properties Name Description Image_filename Image_width Image_height | Category: Sport Shirts Department Sport Shirts Department 2000 catalog of sports shirts Sports_shirts.gif 100 200
Product Definition: Shirts Product Properties: Name Manufacturer Price Product Variant Properties: Size Color SKU | Product: Ace Soccer Shirt Ace Soccer Shirt Ace Shirts $20.00 M Green 23354

Catalog Schema

The catalog schema describes the characteristics of the categories and products in a particular type of catalog. For example, the catalog schema for a Sports Clothes catalog could contain the following product definitions: Shirts, Pants, and Shoes. To create a catalog schema, you use the Catalog Designer module in Business Desk.

The catalog schema consists of category definitions, product definitions, and property definitions. Category definitions and product definitions are created by using property definitions. The following figure shows how property definitions are shared by both product definitions and category definitions.

A figure illustrating how properties are used in both product definitions and category definitions
Name (Text)
Manufacturer (Text)
Price (Currency)
Catagory Definition
Color (Multiple Choice) Description (Text) Image_filename (File Name) Image_width (Number) Image_height (Number) Manufacture (Text)
Name (Text)
Price (Currency)
Size (Multiple Choice)
SKU (Number)
Properties
Product Definition
Color (Multiple Choice) Description (Text) Image_filename (File Name) Image_width (Number) Image_height (Number) Manufacture (Text)
Name (Text)
Price (Currency)
Size (Multiple Choice)
SKU (Number)
Name (Text) Description (Text) Image_file name (File Name) Image_width (Number) Image_height (Number)
Variant Properties
Size (Multiple Choice)
Color (Multiple Choice)
SKU (Number)
Catalog Schema

Category definitions describe the specific qualities of the categories in your catalog. These category qualities are called category properties. You create a category definition by assigning category properties to it. For example, the Department category definition might have the following category properties: Name, Description, Image File Name, Image Height, and Image Width. When you create a category based on the Department category definition, you will enter values for the category properties. For example, the Name category property might be "Sport Shirts Department."

Product definitions describe the specific qualities of a particular product. These product qualities are called product properties. You create a product definition by assigning product properties to it. For example, you might create a product definition named Shirt that would include three product properties: Name, Manufacturer, and Price. When you create a product based on the Shirt product definition, you will enter values for the product properties. For example, the Name product property might be "Ace Soccer Shirt."

Both product properties and category properties are based on property definitions. A property definition describes information about the property such as the data type of the property (for example, number, text, and decimal), the name of the property, and a minimum value for the property. For example, you can create a property named Shirt_Size with the values Small, Medium, and Large, or a property named Length with a minimum value of 10 and a maximum value of 120.

Catalog schema can be changed. You can edit a catalog schema even after a catalog has data in it. For example, you can add, remove, or rename property definitions, and you can change the data type of the property, for example, from a number to a string.

For instructions for creating catalog schema, see Creating a Catalog Schema.

Catalogs

A catalog is an instance of a catalog schema that contains data about individual products and the categories in which they are organized. To create a catalog, you use the Catalog Editor module in Business Desk.

A catalog consists of categories, products, product variants, and properties. The following figure shows the parts of a sample catalog schema, and how they map to the parts of a catalog. Properties are used in the category definition and the product definition. The category definition "Dept" is the used for the "Soccer Shirts" category. The product definition "Soccer Shirt" is used for the "Ace Soccer Shirt" product.

A figure illustrating the parts of a sample catalog schema and catalog
Catalog Schema
Catalog Data
Category Definition
Category Type 'DEPT'
Property Name
Property Size
Property Color
Property 'SKU'
Price: 20
Properties
Product Definition
Soccer Shirt
Soccer Shirt Category
Ace Soccer Shirt Price: 20
Sports Clothes Catalog
Size: S
Size: S
Size: M
Size: M
Size: L
Color: Green
SKU:115
Category
Catalog
Product Family Unique ID = Name
Product Variants Unique ID = SKU

Categories are individual instances of a category definition. For example, a category definition named Department might be used to create the category Soccer Shirts.

Products are single items in your catalog. A product is defined by a combination of property definitions. For example, if you have a product definition named Soccer Shirts, which has the properties Name, Color, and Size, you create a product for each name, color, and size combination that you want to include in your catalog.

Products can be arranged into groups of closely related items, which are called product families. A product family is a group of products that contain product variants. For example, a large-sized, green shirt with the SKU 114 is one product variant of the Soccer Shirt product; taken together, size, color, and SKU form one variant. A product variant always includes a unique identifier, such as a SKU, and a price. Each product variant is based on the same product definition.

For instructions about creating a catalog, see Creating a Catalog.

Catalog Organization: Hierarchies and Relationships

To organize the products in your catalog and make it easier for users to navigate to what they want, you can create category hierarchies and relationships among categories and products. For example, you can create a parent category that includes two different categories, known as child categories. When users navigate to the parent category, the child categories are displayed, enabling users to quickly find the products they want.

The following figure illustrates how a parent category can have several child categories, and how each child category can also be a parent category.

A figure illustrating a sample catalog
Catalog Collection
Catalog B
Catalog C
Sport Clothes Catalog
Pants
Shirts
Soccer Shirts
Two-Piece
Track Suits
Ace Soccer Shirt
Ace Soccer Shorts
Accessory

Size:
Color:
SKU:

Size:
Color:
SKU:

Size:
Color:
SKU:

S
Black
113

M
Blue
114

L
Green
115

In the above figure, the Sports Clothes Catalog has two categories: Shirts and Pants. The Shirts category has two children categories: Soccer Shirts and Two-piece Track Suits. This organization gives users two paths to the Two-piece Track Suits category. They can navigate to track suits through the Shirts category or through the Pants category. This figure also illustrates an accessory relationship between Ace Soccer Shirt and Ace Soccer Shorts. If the users are interested in the shirts, they may also be interested in the shorts.

For instructions about creating hierarchies, see Creating Category Hierarchies. For instructions about creating relationships, see Creating Category and Product Relationships.

Unique Identifiers in a Catalog

Both products and product variants have unique identifiers. The unique identifiers are either a text or a number type of property. For example, if you have a catalog of books, the title of the book might be the unique identifier for the product, and the ISBN number might be the unique identifier for the product variant. For the book The Quest Ahead, the hard cover version would be one variant, the paperback version another, and the audio version a third. All three product variants are part of the product family The Quest Ahead.

The following example shows the components of the product family The Quest Ahead.

Product Family = The Quest Ahead
Unique ID = Title: The Quest Ahead

Product Variant = The Quest Ahead hardback
Unique ID = ISBN: 1102334
Price = 20.00

Product Variant = The Quest Ahead paperback
Unique ID = ISBN: 1102335
Price = 10.00

Product Variant = The Quest Ahead audio
Unique ID = ISBN: 1102336
Price = 15.00

When you create a catalog, you specify which properties are the unique identifiers for products and product variants.

Base Catalogs, Custom Catalogs, and Catalog Sets

You can create two types of catalogs. You can also join two or more catalogs into catalog sets.

  • Base catalogs contain categories and products, but they do not contain any specific pricing rules. For information about creating a catalog, see Creating a New Catalog.

  • Custom catalogs are derived from base catalogs, but they contain specific pricing rules for the products in that catalog. The prices in a custom catalog override the prices in a base catalog. You use custom catalogs in a supplier site, for example, when you want to give one or more companies a custom price on certain products. You use custom catalogs in a retail site, for example, when you have different membership levels for customers, and you want to price products according to the membership level. Or you might want to show different prices to users who shop at your site frequently. For information about creating a custom catalog, see Creating a Custom Catalog.

You determine which catalog a user sees on your site by creating catalog sets. A catalog set is a group of one or more catalogs that you make available to different users or organizations. For example, you may create one custom catalog, and then combine it with a general catalog, and then display that catalog set to members of a specific organization. The following figure illustrates how members of a soccer club can view a team clothes catalog that has special pricing.

A figure illustrating how different users can view different catalog sets
Sports Clothes Catalog
Winter Clothes Catalog
Sports Clothes Catalog
Winter Clothes Catalog
Team Clothes Catalog (Custom pricing at the category level)
Soccer Member Catalog Sets
Members of a Soccer Club
All Users
General Catalog Set

For information about creating catalog sets, see Creating a Catalog Set.

You specify which catalog set a user sees in the Users module in Business Desk. When you create a new user, you specify the catalog set name. For information about creating a new user and specifying the catalog set, see Adding a User.

Product Pricing Methods

You can set the price of a product in a catalog using one of three methods:

  • Direct pricing. You define the price for a product in the product definition. You can do this either when you create the product or when you edit it to change the price. For instructions about applying direct pricing, see Pricing a Product and Pricing at the Product Variant Level.

  • Indirect pricing. The price is determined by its association with a particular pricing category. When a product is associated with a pricing category, the price on the product is overwritten by the price defined on the pricing category. Indirect pricing is typically used when you want to price a group of products the same way, for example, to create special category where all products are $1.99. For instructions about applying indirect pricing, see Pricing Products in a Category.

  • Custom pricing. You apply the price to a category. By doing this you create a custom catalog. There are three types of custom pricing that you can apply to a custom catalog:
    • Percentage adjustment. Specifies the percentage of the list price that should be charged for a product. For example, to apply a 10 percent discount, you would type 90, indicating that the product is selling for 90 percent of the list price.

    • Fixed adjustment. Specifies the exact amount to either increase or decrease the list price. For example, to take $2.00 off, you would type –2, indicating that the product is selling for $2 less; to increase the cost by $2.00, type 2, indicating that it is selling for $2.00 more.

    • Set Price. Specifies the exact price of the product. For example, the product is selling for exactly $10.00.

    For instructions about applying custom pricing, see Pricing a Custom Catalog.

Analyzing Catalog Sales

The following table lists the reports included with Commerce Server that you use to analyze catalog sales data.

Report | Description
Customer Sales | Review customer details, total sales, and total orders. This information can be used to target those customers with online campaigns, for example direct mail promotions.
Shopping Basket Events | Determine when items have been added to or removed from shopping baskets.
Buyer Browsing to Purchase | Analyze user visit patterns. This report provides data such as average number of visits, visits per buy, total sales, count sales, and visitor count.
Product Sales | Analyze product sales volume and revenue by date. This report provides quantity and revenue data.
Order Events | Analyze when orders are placed on your site. This report provides data such as date, time, event, and user type.
Customer Spend Summary | Analyze sales volume and revenue by customer.

For a list of all Commerce Server reports, see Commerce Server Reports. For information about running reports, see Running Reports.

See Also

Business Desk Catalogs

Adding a Discount Campaign Item

Integrating a Third-Party Product Catalog


Data Warehouse

The Commerce Server 2000 Data Warehouse is a set of processes that a system administrator uses to import and maintain data in a combination of a SQL Server database, and an Online Analytical Processing (OLAP) database. The Data Warehouse imports a large amount of site usage data collected from different data sources. This data is gathered from your Web server logs, the Commerce Server databases (profiles, catalogs, campaigns, and transactions) and other data sources that you specify. The Data Warehouse then manages the data in the SQL Server and OLAP databases. These databases are then used to produce reports and to analyze and view population segments.

The Data Warehouse is designed to support robust query and analysis. You use the Analysis modules in Commerce Server Business Desk to analyze the data in the Data Warehouse, for example, to identify user trends or to analyze the effectiveness of a campaign, and then update your site to target content to specific user groups or to sell specific products.

Using the Data Warehouse in Web Site Management

Data Warehouse Structure

Importing Data to the Data Warehouse

Preparing Data for Analysis with OLAP Server

Analyzing Your Data

Using the Data Warehouse in Web Site Management

The Data Warehouse combines data from multiple sources into one common structure, giving the data consistency for producing reports and analyzing and viewing population segments. This is called the Commerce Server Business Analytics System. Business analytics is a way of looking at your Web site data to answer specific questions about the performance of your Web site. You can use the information provided by business analytics to improve your customer service and to target content to users.

Business analytics provides you with specific measurements of your Web site performance, including:

  • What URL did the user visit before accessing your site (the referring URL)?

  • What type of advertising works?

  • What pages are the most popular on your Web site?

  • Which products sell the best?

  • Which users buy the most?

You can use these measurements to make changes to your Web site that will increase sales and retain users. For example, assume you display an advertisement to promote a new product. After the ad is displayed for a week, you can run a report to determine whether the ad increased sales of the product. If it did not increase sales, you can update you site, for example, to display a 10 percent discount for the new product, and then after a week, determine whether the discount improved sales.

Data Warehouse Structure

The Data Warehouse has two main parts:

  • Physical store. A Microsoft SQL Server database that you can query using SQL queries, and an OLAP database that you can use to run reports.

  • Logical schema. A conceptual model that maps to the data in the physical store.

The following figure shows the relationship between the physical store and the logical schema.

A figure showing the relationship between the physical store and the logical schema
Commerce Server Data Warehouse
Logical Schema

Class 1
Data member
Data member

Class 2
Data member
Data member

Class 3
Data member
Data member

maps to

Physical Store
Report preparation DTS Task

OLAP Server

SQL Server

Physical Store

The physical store for the Data Warehouse includes one database that you can query using SQL queries. The physical store contains all the data that you have imported from different sources.

Commerce Server automatically builds the physical store for the Data Warehouse in both the SQL Server database and in the OLAP database. The Data Warehouse provides the data necessary for all the Commerce Server reports available in the Analysis modules in Business Desk .

There is no need for you to directly modify the physical store for the Data Warehouse. If you need to extend the Data Warehouse, for example, to encompass third-party data, a site developer can programmatically add the fields you need through the logical schema.

Logical Schema

The logical schema provides an understandable view of the data in the Data Warehouse, and supports an efficient import process. For example, a site developer uses the logical schema to modify the location of data stored in the underlying physical tables. When a site developer writes code to add, update, or delete data in the Data Warehouse, the developer interacts with the logical schema. When Commerce Server accesses data in the Data Warehouse, it accesses the data through the logical schema. Only the site developer needs detailed knowledge of the logical schema.

A logical schema includes the following:

  • Class. A logical collection of data members. For example, the RegisteredUser class contains data members describing a registered user.

  • Data member. A structure that stores a piece of data. For example, the E-mail data member of the RegisteredUser class stores the e-mail address for a registered user.

  • Relation. A connection between two classes in a parent-child relationship. This relationship defines the number of instances of each class, and it provides the mechanism for sharing data members between classes. For example, RegisteredUser is a parent to the child class Request. There can be many requests for one registered user.

The logical schema uses classes, data members, relations, and other data structures to map data in the physical store.

Importing Data to the Data Warehouse

The data that populates the Data Warehouse typically comes from multiple data sources: Web server logs, Commerce Server databases, and other data sources that you specify. The following figure shows the sources for operational data, and how the data might be used to support tasks run from Business Desk.

A figure that shows how data is imported into the Data Warehouse
Business Desk
Run Reports and Analyze Data
Manage User Profiles
Run Direct Mail Campaigns
Commerce Server Data Warehouse
Direct Mailer Database
Commerce Server Databases
User Profile data Event data Transaction data Campaigns data Catalog data
Other
Catalog Data
Campaigns Data
Transaction Data
Web Usage Data
User Profile Data
Web Server Log Files
Web Site
User

Because the Data Warehouse is not part of your run-time environment, a system administrator must determine how frequently to import the operational data into the Data Warehouse. For example, you can set up the Data Warehouse so that it automatically imports new data every day or every week. The frequency with which you will need to import data depends on the amount of new data collected every day in your operational data sources. Commerce Server includes custom Data Transformation Service (DTS) tasks that simplify the importing of data into the Data Warehouse. These DTS tasks import data that is used with the reports available from Business Desk.

Even though the operational data can be imported from different types of databases—or from storage media that are not databases—all of the data is structured in a consistent manner after it is gathered into the Data Warehouse. For example, you might have one data source in which the first and last name of a user are stored in the same field, and another in which the first and last names are stored in separate fields. When this data is imported into the Data Warehouse, it is automatically structured to be consistent, thus enabling your analysis activities.

Preparing Data for Analysis with OLAP Server

After data is imported into the Data Warehouse SQL Server database, it must be prepared for analysis so business managers can run reports against it. To prepare data for reporting, the system administrator runs a DTS task that exports a selected subset of data from the SQL Server database to the OLAP database. In the OLAP database, the data is stored in multidimensional cubes.

By storing data in OLAP cubes, instead of in relational tables in SQL Server, the Data Warehouse can retrieve data for reporting purposes more quickly. The data can be retrieved from the cubes faster because it is aggregated. That is, data that belongs together is already associated so it is easier to retrieve than searching an entire relational database for the smaller parts. For example, using OLAP server you can run a report that lists users who visit your site based on the time of their visit and on the ASP page that they access first. It would be extremely difficult to run such a report against a large SQL Server database.

In multidimensional cubes, data is grouped in two kinds of structures:

  • Measures. The numeric values that are analyzed.

  • Dimensions. A business entity, such as color, size, product, or time. For example, you would use the color dimension to contrast how many red products and blue products were sold, the size dimension to contrast how many large and small products were sold.

It is the relationship between the dimension (for example, color) and measure (for example, number of products sold) structures that provides the basis for your reports about user activity.

The following figure illustrates the dimensions and measures in a report.

A screenshot of a report with callouts from dimensions and measures

Click the illustration to enlarge or reduce.

Analyzing Your Data

To analyze data about user activity on your site, you use the Analysis modules in Business Desk. You can use the Analysis modules to run reports against the Data Warehouse, or to view and analyze Segment models, which identify segments of the user population visiting your site.

Reports

Commerce Server provides two types of reports that you can use to analyze user data:

  • Dynamic reports are created at runtime. Each time the report is run, it gathers the most recent data in the Data Warehouse. Only the report definition, which remains the same over time, is stored. Commerce Server does not save completed dynamic reports; however, you can export dynamic report results to Microsoft® Excel and store them there. For information about exporting the results of a dynamic report to Microsoft Excel, see Exporting a Dynamic Report.

  • Static reports are run immediately upon request, and then stored, with the data, in Completed Reports. The reports appear in a browser window in HTML format. You can export static report results to the List Manager module, and then use the list in a direct mail campaign. You can send these reports to others using e-mail, post them on your Web site, and edit them in other applications. For example, using Microsoft Internet Explorer, you can export the report into a Word document, and then edit it.

Commerce Server 2000 includes several reports that you can run from Business Desk, such as the Executive Summary Report, the Products by Quantity Sold Report, and the Hits by User Report. You can use one or more of these reports, or you can customize a report to retrieve other data. For a list of reports included with Commerce Server, see Commerce Server Reports.

Segment Models

Segment models identify groups of users who share similar characteristics. You can use the Commerce Server Predictor resource to search the data in the Data Warehouse to generate Segment models. You analyze Segment models using the Segment Viewer module in Business Desk. For conceptual information about Segment models, see Prediction and Data Mining.

See Also

Working with the Data Warehouse

Running the Data Warehouse

Business Desk Analysis


Prediction and Data Mining

The Commerce Server Predictor resource is a powerful data-mining tool that you use to to provide predictive capabilities for your Web site, for example, to display product recommendations. You can also use the Predictor resource to analyze the characteristics of the users visiting your site, and discover relationships among the characteristics. You can then use this information to target content to users who have similar characteristics.

The Predictor resource mines data collected in the Data Warehouse. The Data Warehouse database can store all site data, including user profile data, click-history data, and transaction data. Although the Data Warehouse database is quite large, the capabilities of the Predictor resource can efficiently mine the data.

Using Prediction in Web Site Management

Analysis Models

Creating Analysis Models

Using Prediction in Web Site Management

Your site developer uses the Predictor resource in Commerce Server to add predictive capabilities to your site. The Predictor resource enables you to perform the following profiling and targeting activities:

  • Provide intelligent cross-sell support. Suggest items that a user may be interested in by correlating properties about the user, or items the user has ordered, with a database of items that other users have ordered previously. You can restrict the items that are suggested to a particular part of the catalog.

  • Segment users based on their behavior or profile. Analyze these segment models to discover the characteristics that partition those users into population segments. Your system administrator builds segment models that you can analyze using the Segment Viewer module in Commerce Server Business Desk.

  • Fill in missing values in your user profile data. Predict a missing value, for example, a user profile property that the user did not supply.

Analysis Models

The Predictor resource builds analysis models from data. An analysis model is a set of statistical relationships based on known properties of past site users, their purchase history, click history, or other behavior. The model contains information about the types of users who visit your site, but it does not contain information about specific users. The detailed information used to create an analysis model is stored in the Commerce Server Data Warehouse, or another data source.

You can use analysis models to perform implicit profiling and to target content to users:

  • Implicit profiling. If profile information about a user is missing — for example, the gender of a user — this information can be extrapolated by the analysis model based on the aggregate properties of the entire user population who visits your site.

  • Targeting content. You can use analysis models to add predictive capabilities to your Web site. For example, you may want to present users with a ranked list of recommendations for products in your catalog or to display advertisements that may be of interest. You can also view analysis models to analyze the characteristics of the users visiting your site, discover relationships among the characteristics, and then target content to users who have similar characteristics.

Two types of analysis models are used in Commerce Server: Prediction models and Segment models.

Prediction Models

You use a Prediction model, a collection of decision trees also known as a dependency network, to provide real-time purchase recommendations to users visiting your site, and to guess unknown profile properties about users. A Prediction model summarizes relationships in the data in the form of rules. For example, a Prediction model may say that if a visitor to your site is male, over 55, and purchases sports clothes, then he is also likely to purchase golf equipment. You can use this model to make real-time recommendations for golf equipment to users who match this profile.

Prediction models typically provide recommendations that are more accurate than human-generated rules, as they predict based upon the previous activity on the site; consequently, they usually result in more sales.

To analyze Prediction models, you use the Prediction Model Viewer in Commerce Server. For information about viewing Prediction models, see Viewing Analysis Models.

Segment Models

A Segment model, also known as a cluster model, partitions users who tend to have similar properties or behavior into segments. You can use these segments to gain an understanding of the users who visit your site and also for subsequent marketing. For example, you notice that sales have skyrocketed for a popular fantasy book for children. You discover that users in a segment with the following characteristics make most of the purchases of that book: female, over 40, income above $50,000 per year, and college educated. You can now offer similar products to users in this segment.

You use the Segment Viewer module in Business Desk to analyze Segment models. For information about the Segment Viewer, see Analyzing Population Segments.

Creating Analysis Models

Each analysis model is based on a model configuration, which is a description of the data to be used to build the model. A model configuration specifies:

  • A data source for building the analysis model. Typically the data source is the Data Warehouse since it contains vast amounts of user data. However, you can use an external database to build an analysis model.

  • Attributes for the model. An attribute identifies which columns of user data (represented in a table) should be included in the model. An attribute may include user profile data, purchase history, or click history.

Commerce Server includes the transactions model configuration, which is defined in the Data Warehouse schema. You use the transactions model configuration to build models based upon purchase history. If your site requires a custom model configuration, a site developer can build a new one. For information about creating custom model configurations, see Predictor Schema.

As soon as you have collected data, you can use the model configurations to build analysis models. To build an analysis model, the system administrator uses the Predictor resource in Commerce Server Manager. Models are not built on the Web server, so the building process does not impact the performance of your site.

After the model is built, the system administrator can move a copy of the model to each of your Web servers (all Web servers use the same model), and then enable predictive capabilities on your site. You can view the Prediction model or the Segment model to analyze the patterns of the users visiting your site.

After you have gathered a significant amount of new data, your system administrator should rebuild your analysis models. You build analysis model configurations infrequently, however, only when you change what you are trying to predict or analyze.

See Also

Predictor Schema

Running the Predictor Resource

Analyzing Population Segments

Programmer's Reference

Targeting and Personalization


Pipelines

A pipeline is an extensible software framework that defines and links together one or more stages of a business process, running them in sequence to complete a specific task. For example, the Order Processing Pipeline provides the sequence of steps that are used to process purchases from your site. In the first stage in the Order Processing Pipeline, you retrieve the product information from the database that stores catalog data. In the next stage, you add the address of the user to the order. Each stage in the pipeline represents a category of work. The sequence of the stages determines the sequence in which the work is to be done.

Commerce Server 2000 includes a set of pipelines that perform much of the standard processing required by a Commerce Server site. A site developer can tailor these pipelines to meet the specific needs for the site. For example, a site developer can add new stages to the pipeline, integrate the pipeline components with your existing system, or replace the components with other components supplied by third parties.

Types of Pipelines

Pipeline Structure

Creating and Editing Pipelines

Types of Pipelines

Commerce Server includes the following types of pipelines:

  • Content Selection Pipeline. Selects content to be displayed to users. For example, it determines which advertisements a user should see or which discounts a user should receive, based on the targeting expressions you created using Commerce Server Business Desk, how many advertisements are to be delivered, and other factors.

  • Event Processing Pipeline. Records events related to the displayed content (for example, a user clicking on an ad) and stores it in the Commerce Server databases. This information is then used for reporting purposes, for example, how many users have clicked on an ad.

  • Direct Mailer Pipeline. Constructs and delivers messages for direct mail campaigns. It can construct personalized e-mail messages or messages with static content.

  • Order Processing Pipeline. Processes either business-to-consumer (retail) orders or business-to-business (supplier) orders. These pipelines ensure an order goes through all the necessary stages to be processed appropriately. For example, it retrieves the product description from the catalog, retrieves the shipping address for the user, computes the amount of tax, and computes the total price.

    Commerce Server includes the following types of Order Processing Pipelines:

    • Product Pipeline. Computes price and discount information for a product.

    • Plan Pipeline. Verifies the integrity of the order. For example, if the order does not contain any items, then an error is generated.

    • Purchase Pipeline. Accepts the final purchase of an order form, writes an order to database storage and, optionally, finalizes a receipt and writes the contents of the order to the receipt database

Pipeline Structure

A pipeline is defined in a pipeline configuration file, which has a .pcf file extension. In the .pcf file, you can see the stages of the pipeline. Each stage contains one or more pipeline components. A site developer can configure each stage to work with the unique requirements of your site.

The following figure shows the stages of the Retailing Purchase Pipeline (the Purchase.pcf file).

A figure that shows the stages of the Retailing Purchase Pipeline

Click the illustration to enlarge or reduce.

Information is passed from an ASP page to the pipeline using the following two dictionaries:

  • Context dictionary. A read-only dictionary that provides the pipeline with information about the environment. For example, it might contain the connection string for a database.

  • Order dictionary. A read-write dictionary that provides the data that the pipeline is to process. For example, when a user submits an order, all the information is gathered together in the order dictionary, and is then passed to the Order Processing Pipeline.

The content of each dictionary is dependent on the type of pipeline. A site developer specifies the information that must be included in the dictionary on the ASP page.

Commerce Server pipelines can be run as transactions, which allow the pipeline to roll back the process if an error occurs. In addition, Commerce Server pipelines take advantage of Microsoft Windows 2000 Server object pooling to greatly increase the processing speed. For information about object pooling, see the Windows 2000 Server online documentation.

Creating and Editing Pipelines

A site developer uses the Pipeline Editor to create new pipelines and to change existing pipelines. Commerce Server provides seven pre-configured pipeline templates that you can use as a basis for your own custom pipeline. The template files for creating new pipelines have the .pct (pipeline configuration template) file extension. You can change the names of stages and add or delete stages. You can add or delete any component in any stage. For more information, see "Working with Pipelines" in Commerce Server 2000 Help.

See Also

Working with Pipelines

Building Pipeline Components

Pipeline Component Reference

Extending the Content Selection Framework


Targeting and Personalization

Targeting and personalization are the processes of delivering personalized content to one or more users, or any other business entity that has a profile. For example, if you are running a sports Web site, you may want to deliver tennis-related information only to tennis players, or to users who are interested in tennis. You may want to deliver announcements about upcoming tennis tournaments, or advertisements and promotions for tennis products.

You can use Commerce Server 2000 to perform two types of targeting:

  • Expression-based targeting. Also known as explicit targeting. This is used when you know the profile properties of the users to whom you are delivering content, or you know the context, and you know what content is to be delivered. You use the Campaigns modules in Commerce Server Business Desk to specify this information and deliver the content to the user.

  • Prediction. Also known as implicit targeting. This is used when you do not know all the necessary profile properties to target the user, or you do not have specific content to deliver. You use the Commerce Server Predictor resource to extrapolate this information from existing user data so that you can deliver content of interest to each user. For conceptual information about prediction, see Prediction and Data Mining.

Both expression-based targeting and prediction improve your ability to deliver content that may be of interest to the users who receive it. Users are more likely to return to your site when they can expect to receive a personalized experience.

Using Targeting Methods in Web Site Management

Expression-based Targeting

Expression Builder

Processing Expressions

Using Targeting Methods in Web Site Management

You can target content to any business-related item that has a profile. For example, you can target content to anonymous users, registered users, companies, or contexts. For conceptual information about profiles, see Profiles.

You use Business Desk to target content to business-related items. For example, you can do the following:

  • Create a direct mail campaign that delivers personalized messages to users.

  • Deliver content such as advertisements to users based on certain user profile properties. For example, you might display advertisements for bicycles to users who have their Favorite Sport property set to "Biking."

  • Identify groups of Web pages, and then target content to be displayed only on those pages, or only when users with specific properties access those pages.

  • Display content on a page based on the properties of other content on the page. For example, if your Web site provides news, you can assign profiles to the content specifying whether Weather_Type property is "Hot" or "Cold." If Weather_Type = Hot, you can display an advertisement for air conditioners.

  • Apply discounts to certain products in your catalog, based on characteristics of the product itself, or based on the user profile.

  • Choose when to display a discount and when the discount is to be applied to the order. For example, you can apply the discount when users put the item in their basket or when they check out.

Expression-based Targeting

Expression-based targeting is the process of creating expressions that define the users or context you want to target and the content you want to deliver. An expression is a condition that is evaluated against profiles to determine whether to deliver content, or perform another action. For example, an expression might be user.totalvisit > 100. If this expression evaluates to "True," then a specific piece of content is displayed to the user.

You use the Campaigns modules in Business Desk to create expressions, and then combine the expressions with the action you want to perform after the expression is evaluated. You can create two types of expressions:

  • Target expressions. Identify where, when, and to whom content should be displayed. For example, you can target content to users who have specific profile properties. You can also target content to specific sections of a Web site, called page groups. For example, you can create a target expression that will display certain ads only on sports pages.

  • Catalog expressions. Specify the products in a catalog that a discount can be applied to. For example, a catalog expression might be Product.price = 20.00. If this expression evaluates to "True" for a particular product, then a discount of 10 percent is applied to the price of that product when users add it to their shopping baskets.

After you have created target expressions, you can combine them to form a target group. A target group is a collection of expressions and actions. For example, you might create one expression to show a specific piece of content to users who have visited the site 10 times, and another expression to show content to users who have purchased a soccer shirt. You can combine the two expressions in a target group with AND or OR statements. For example:

If the user has visited the site 10 times AND the user has purchased a soccer shirt,

Display an advertisement for a soccer product.

In a target group you combine expressions by specifying the action to be taken when each expression evaluates to "True." Each action has two multipliers: a multiplier to apply if the expression is true, and a multiplier to apply if the expression is false. When the multiplier is applied, the expression is given a score, which affects whether the content is eligible for delivery. You can specify the following actions:

  • Target. If the expression evaluates to "True," the score is increased, as is the probability the content will be shown. If the expression evaluates to "False," the score is not changed. In both scenarios, the content is eligible for delivery.

  • Require. If the expression evaluates to "True," the content is eligible for delivery; if it is "False," the content is not eligible for delivery.

  • Exclude. If the expression evaluates to "True," the content is not eligible for delivery; if it is "False," the content is eligible for delivery.

  • Sponsor. If the expression evaluates to "True," the content is eligible for delivery and no other content is eligible unless it too has an expression with action = Sponsor. (Sponsor has only one multiplier.) For example, if Microsoft sponsors an advertisement on a home page, only Microsoft advertisements are displayed; however, if there are more advertisements from other companies sponsoring the home page, those advertisements would also be eligible for display.

A site developer can change the values of the multipliers provided with Commerce Server. You may want to do this to give expressions with one action type a higher priority than expressions with a different action type.

Expression Builder

The Commerce Server feature that business managers use to create, edit, and view expressions is called the Expression Builder. The Expression Builder provides the user interface for building expressions. It accesses the appropriate properties for building an expression, and it names and stores the expression in the Commerce Server databases.

The Expression Builder is designed so that site developers can easily embed its functionality and user interface in other Business Desk modules. In addition, it can be invoked by any Web application that uses and manipulates expressions, enabling you to integrate it with other processes. For example, if you have an existing content management process, you can incorporate Expression Builder functionality, and then target content to users.

To create applications that use the Expression Builder, you do the following:

  • Define profiles. You specify which profiles the expression should use, and the Expression Builder loads those profile definitions for constructing the expression. You can also specify a profile properties filter to limit the properties in the profile that will be available to an Expression Builder user.

  • Save expressions. You can specify the expression/profile store to use, and the Expression Builder loads and saves expressions in that database.

  • Display messages to users. You can customize the messages that are displayed in the Expression Builder user interface (UI). For example, the default title message is "Create an expression," but for your implementation, you might change it to "Create an Ad Targeting Expression."

The Expression Builder uses Dynamic Hypertext Markup Language (DHTML) for its UI, so the stylesheets of the application will apply to the Expression Builder UI, giving your application a consistent look and feel.

Processing Expressions

Commerce Server performs several steps to specify the piece of content that is to be shown to a user. The following components are used in the process:

  • ExpressionEval. This Component Object Model (COM) object takes the expression and user data as input, and then processes the expression to determine whether it evaluates to "True" or "False."

  • Content Selection Framework (CSF). This platform-level framework includes a set of components and pipelines (the Content Selection Pipeline and the Event Processing Pipeline) that determines the action to be performed as a result of the expression.

The following figure illustrates how target expressions, catalog expressions, user data and context data are input into the Expression Evaluator, which results in True, False, or undefined results. The result is input to CSF, which then determines the action to perform.

A figure illustrating how Expression Evaluator and CSF process expressions
Target expression
Catalog expression
User data

Context data
Expression Evaluator
True, False, or undefined result
Content Selection Framework
Determines the action on this result

See Also

Extending the Content Selection Framework

Prediction and Data Mining

Campaigns: Ads, Discoutns, and Direct Mail

Business Desk Campaigns


Campaigns: Ads, Discounts, and Direct Mail

A campaign is a marketing program that uses many communication vehicles to accomplish a specific result, such as increasing market share, introducing new products, or retaining customers. Commerce Server provides several different delivery mechanisms for your online campaigns. For example, you can create campaigns for advertisements, discounts, and direct mail, and you can use analysis features to target your campaigns to specific groups of users.

Using Campaigns in Web Site Management

Campaign Structure

Campaign Goaling

Reference Tables

Ads

Discounts

Direct Mail

Analyzing Campaign Effectiveness

Using Campaigns in Web Site Management

The Campaigns modules are designed so you can work with your customers to maximize the effect of ads, discounts, and direct mail. With Campaigns, you can:

  • Target ads or discounts to users of a specific profile. You set up a user profile using the Profile Designer module, and then integrate it into a campaign. For each individual ad page, you can specify whether the profile for the user browsing that page should be considered for targeted content, or ignored.

  • Run campaigns for customers who compete within the same industry. The competing ads are never shown on the same page.

  • Charge your customers based on the number of ad requests they want their ads to receive. The Content Selection Framework considers this in ranking the content.

Campaign Structure

Campaigns and the associated campaign items are grouped by customer. Customer information, such as billing address, is used for all campaigns created for that customer and for reporting purposes. You can view all your customers in alphabetical order in the Campaign Manager.

Campaigns are a grouping structure for campaign items. There are three types of campaign items: ads, discounts, and direct mail campaigns. Each campaign may have multiple campaign items. For example, a campaign to promote a new product may include three campaign items: an advertisement banner on the Home page, a personalized direct mail message announcing the new product, and a discount campaign item offering a 10 percent discount to users who purchase the product during the month of June.

All campaign items within one campaign have a common customer and date ranges. For example, in the travel section of a Newspaper site, an advertiser might request the delivery of 10,000 requests within a week to users from the Northwest. The advertiser might decide to run three different ads to fill those 10,000 requests and then see which one of the three ads creates the highest click rate. Each ad is a campaign item.

Campaign Goaling

Campaign goaling is the process of specifying the number of ads to deliver (the goal) in a certain amount of time. You can goal by clicks on an ad or by requests for an ad. You can goal campaigns at the campaign level or at the ad level.

  • Campaign level goaling applies the goals to all of the campaign items (ads) in the campaign by using a weighted distribution of the total number of requests.

    For example, say you perform goaling at the campaign level for a customer. The customer gives you two ads, and orders 25,000 ad requests. At the campaign level, one ad is set up to display 60 percent of the ad requests, and the other ad is to display 40 percent of the ad requests. If the customer changes the number of ad requests, for example, to 40,000, you do not have to manually change the number of times the ads are to display; they are still 60 percent and 40 percent.

  • Ad level goaling applies the goals at the campaign item level. The total requests for the campaign will be equal to the total number of ordered requests for each campaign item. For example, a customer might order 50,000 requests to be delivered in one month. One ad item must be delivered 50,000 times.

You can switch between campaign level goaling and ad level goaling. For example, a customer orders two ad campaign items to run in even proportion for a quantity ordered of 1000 ad requests. You perform the following steps:

  1. You add the campaign items to a campaign, and assign each item a weight of 1. The quantity ordered for each item is 500 ad requests.

  2. Later, the same customer requires 500 more requests for Ad 1. You open the campaign and change the goaling to Advertising, select Ad 1, and then add 500 items to the quantity.

    The quantity ordered for Ad 1 is 1000. The quantity ordered for Ad 2 is 500. The total quantity ordered is not visible in the Campaign Manager for ad goaled campaigns.

  3. Finally, the customer wants to redistribute the order so that Ad 1 is run at a rate of 3 to 1 with Ad 2. You change the goaling to Campaign level goaling. The quantity ordered reappears containing the sum of the quantity ordered for all ads or 1500. Now the weights for each of the ads are the same as the quantity ordered.

    At this point you can edit the weights of each ad so that the weights are 3 and 1 and Commerce Server will calculate the new quantities, or figure out that the new paid weights would be 1125 and 375.

In a different situation, for example, after step two the customer wants the campaign run at a rate of 2 to1 and the third ad to also have weight of 1. If you add an ad to a campaign that has been converted from an ad level goaling to Campaign level goaling, and leave the weight of 1 without changing the paid weights of the other ads, the ad delivery will be skewed. You should reopen the Campaign Manager and assign new weights to all of the ads, and then verify the actual calculations.

Reference Tables

You use the Reference Tables module in Business Desk to set the sizes of content that is displayed on your site, to manage the names of Page Groups, and to establish industry codes that you can use to prevent two ads from the same industry showing up on the same page at the same time. The properties in the Reference Table module ensure the consistency of advertising content across your site.

  • Content Sizes are the sizes you want for your content (ads and discounts). Commerce Server 2000 provides several default content sizes. These content sizes are taken from a list of commonly used sizes approved by the Internet Advertising Bureau (IAB). Content sizes are validated through the Content Size section in the Reference Tables module.

    The content sizes in the reference tables are available when you select the size you want for your campaign item content. You can view, edit, and delete any of the predefined sizes, or you can create a new content size to fit your needs.

  • Industry codes are codes for different industries, such as the automotive, aviation, and beverage industries. You use industry codes to identify the associated industry of an advertisement, thus preventing two ads from competing companies in the same industry from appearing on the same page. Industry codes do not apply to discounts.

    You can update your industry codes, for example, to include more than one beverage code, such as one for coffee and one for milk, so that ads for different types of beverages can appear on the same page. For example, it may be acceptable for an ad for coffee to compete with an ad for milk on the same page. You can set the level at which the industry conflict is monitored by controlling the number of entries in this table.

    Commerce Server provides several popular industry codes for your use. The industry codes used in ads are validated through the Industry Codes section in the Reference Tables module. The industry codes in the reference tables are available when you select the industry code for a campaign item. You can view a list of all current industry codes, add new industry codes, edit industry codes, and delete industry codes from the Industry Code section in the Reference Tables module.

  • Page groups are a set of related Web pages that is tagged with a particular page group name and used for targeting ads. For example, if you are running a newspaper site, you might create a page group for Sports, one for the Top Story, and another for Local News. You can then target ads to display only on pages in certain page groups.

    When you bill customers for displaying ads on your site, you can base the advertising rates by page group. For example, you can charge a premium for ads displayed on your home page, but less for ads displayed on other pages.

    Note

    • Before a page group can be used, you must ad-enable the page. For instructions, see the Commerce Server Software Development Kit.

Ads

Commerce Server supports two types of ads: paid ads and house ads.

  • Paid ads are pieces of content to be delivered by Commerce Server based on a specific formula for delivery referred to as Need of Delivery (NOD).

  • House ads are pieces of content that are served when paid ads are ahead of the Need of Delivery schedule specified for them. For example, a customer orders 1000 paid ads to be delivered over four months, but in the first two months the ad has been served 850 times. To balance the Need of Delivery schedule, house ads would be served.

    House ads are critical to ensure the smooth delivery of your paid ads. House ads are also displayed when there are no paid ads eligible for the request. For example, a house ad would be served because all paid ads missed a required target.

    House ads may also be used to sell leftover inventory at discounted prices. They may also be used if the ads on the site do not have specific delivery goals, but you want to have the ads run at specified weights.

Components of an Ad

In Commerce Server, ads are treated as having four parts:

  • Ad Properties are the name of the ad, the type (paid ad or house ad), the weight or number of requests or clicks scheduled to be delivered (paid ad versus house ad), the exposure limit, and the industry associated with the ad.

  • Ad Schedule is the start date/time and end date/time. You can select on which days of the week the ad will be displayed, and what times of each day.

  • Ad Target identifies on which pages the discount will be displayed, and to which target groups.

  • Ad Display identifies the size of the ad, the type (for example, image, text, or HTML), and if needed, the image and/or URL that the user can click to go to another page (or Web site). You can display ads as images, text, HTML, non-clickable images, Buy Now ads, Windows Media Services, or vignette. (A vignette ad is composed of text that is displayed adjacent to the image where the ad is displayed.)

Targeting Ads

Using Commerce Server, you can determine when an ad is displayed, where, and to whom. When you create an ad, you specify the following:

  • Exposure limit. The number of times the ad can be shown to a user within a session.

  • Weight. A means of determining how frequently an ad is displayed, relative to all of the campaign items for a given customer. In a campaign, weight only applies to ads that are goaled at the campaign-level. If the ads are goaled at the item level weight is not used for paid ads.

    For house ads the weight is relative to all other house ads for all customers and all campaigns. For paid ads, the weight is relative to other paid ads in the same campaign. The weight of an individual campaign item is relative to the weight of all the other campaign items.

    For example, assume you have four ads to sell paint, and you assign the weight as follows:

Ad | Weight | Percentage of times served
Blue paint | 1 | 10
Green paint | 2 | 20
Red paint | 3 | 30
Yellow paint | 4 | 40
Total Weight | 10 | 100

The total weight of all the ads is 10 (1+2+3+4 = 10). The Blue paint ad has a weight of 1 so it will be displayed once out of every ten ad requests.

For paid ads, the weight is the ratio of a single ad to the sum of all the campaign items for that campaign. For house ads, the weight is the sum of the weights of all other house ads in the campaign.

For ads that are goaled at the campaign item-level, weight is not used to determine the delivery of the ad. Instead, you directly specify the number of requests or clicks that should be served.

  • Page Groups. A set of related Web pages is tagged with a particular page group name and used for targeting ads. For example, if you are running a newspaper site, you might create a page group for Sports, one for the Top Story, and another for Local News. You can then target ads to display only on pages in certain page groups.

    You create page groups using the Reference Tables module.

  • Target Groups. A collection of targets to which content will be displayed. For example, you can target ads to users who have specific profile properties. For more information about targets and target groups, see Targeting and Personalization.

Processing Ad Campaign Items

The Content Selection Framework (CSF) processes the variables that you specify for an ad: campaign goaling, exposure limit, schedule, weight, page groups, and target groups. Each time a user visits your site, it determines whether the ad is to be displayed.

The Content Selection Framework for advertising uses a formula called Need of Delivery (NOD) to initially score the advertisements based on how far behind schedule they are. This formula takes into account the total quantity of content to be delivered, and the length of time over which the quantity must be delivered. Need of Delivery is calculated for each ad request by the Content Selection Framework after it has processed the ad request. Need of Delivery is applied to paid ads only; it is not applied to house ads.

If you have several ads and want to know on what basis they are being displayed, contact your site developer. Commerce Server includes a tool named TraceScores that your site developer can use to trace the selection process. Use TraceScores to see exactly how the internal content decision process works.

If you plan to run many campaigns simultaneously on Commerce Server, using the same target group and the same priority, the Content Selection Framework selects which ad to display based on the ad type. If the ads are both house ads, an ad is selected at random using the weights as relative probabilities. If the ads are paid ads, an ad is selected for display based on the Need Of Delivery Calculation (which takes into account the start date, end date, number of events scheduled, and number of events served to date). One of the score modifications is History Penalty, which applies a decreasing penalty to ads recently seen by a user. When the History Penalty is enabled, ads are "rotated" over time.

Discounts

You can apply discounts to any item in your catalog. You can apply a discount against an entire order (an order-level discount), or you can apply it against specific items in the order (an item-level discount).

  • Order-level discounts apply to all products in a shopping basket. For example, free shipping is a type of order-level discount: you can give users free shipping for all products in their basket. Free shipping is the only order-level discount delivered with Commerce Server. If you want to offer another type of order-level discount besides free shipping, for example, a 10 percent discount for preferred users, a site developer must make custom changes to your site.

  • Item-level discounts apply to specific products in the basket.

If you apply a discount to an entire order, the discount is applied to each item individually. Only one discount can be applied to a quantity one of an order line item. Two discounts cannot be applied to the same quantity one of an item.

You can use Commerce Server to create and apply the following discount types:

  • Click-required discounts are only applied if the user clicks the discount URL, which may be an image of the product that says, for example, "10 percent off." Site developers can extend this type of discount for other uses, such as offering coupons, which the customer must have in order to enjoy the discount.

  • Leverage discounts are based on the purchase of other products. For example, when users add a telephone to their basket, you can offer them a free address book at checkout that they can then accept by adding it to their basket. Or, you can offer users another accessory at a discounted price.

  • Percentage-off discounts reduce the price of products by a percentage, rather than by dollar amount. For example, you can discount products by 10 percent, and then change the price of the products as needed. When you change the price of the products, the discount amount is updated automatically.

  • Dollar-off discounts reduce the price of products by a fixed amount. For example, you can offer a $5.00 discount on certain products. Even though you may change the price of the products, the discount amount ($5.00) always stays the same.

  • "Happy Hour" discounts reduce the price of products during certain dates. To schedule discounts to apply during certain hours, you can build expressions that evaluate the Current Time property. For example, if Current Time > 5:00 pm and Current Time < 9:00 pm, discount the product by 10 percent.

You can apply these discounts to individual products, all the products in a category, or you can create an expression to discount products that meet specific criteria, for example, offer a 10 percent discount on all items from a certain manufacturer.

For example, you can create discounts to apply in the following situations:

  • Price of product is greater than $20.00. This is a discount condition expression. Discount condition expressions are based on a product property.

  • User buys 2. This is part of a required discount condition criteria.

  • User clicks a discount ad on the Sports page. This is the click-required part of a discount.

  • User is registered. This is a discount eligibility expression. Discount eligibility expressions are based on user profiles and context profiles.

You cannot apply multiple discounts to one product simultaneously. A customer can enjoy only one discount per product, or a condition can be applied toward only one discount. After a product as been used as a condition or an award for one discount, it cannot be used as a condition or award for another discount.

Components of a Discount

A discount campaign item has the following components: discount properties, discount definition, discount target, and discount display. You use the Campaign Manager to define these components when you create the discount.

  • Discount properties are the name of the discount, priority, start date and end date.

  • Discount definition is a specification of what you are discounting, how much, and for whom. A discount definition has the following parts:
    • Target expression identifies what is discounted. For example, the target expression Book_price > 20 applies the discount to all books meeting that criteria.

    • Requirement identifies the user and/or context in which the discount is advertised. For example, if the user is a registered female who purchased $50.00 of merchandise during her last visit, you can offer a discount. Or, if the user shops your site during a certain day, or views a specific page, the user may meet the context requirements and receive a 10 percent discount.

    • Award identifies what the users get, for example, a 10 percent discount or free shipping. An award condition must be true for the discount to apply. The award condition is evaluated for each item in the order form. An award condition can be an expression specifying that the discount applies to a particular item, or it can specify that it applies to all items.
  • Discount Target identifies the pages on which the discount will be advertised, and to which target groups.

  • Discount Display identifies how many times you will display the discount to a user, the image and/or URL that the user clicks to get the discount, and the discount information that will be displayed in the basket when the user checks out.

Discount Priority

You give every discount a priority that determines when it should be applied relative to other discounts that may also apply to a product. (Unlike ads, discounts do not use weights to determine when they are delivered.) For example, you create three discounts and assign each a priority as shown in the following table.

Discount | Priority
10 percent discount for telephones | 10
30 percent discount for premier users who buy telephones, radios, or computers | 20
Free shipping | 30

If a premier user shops your site and purchases a telephone, among other items, only the 10 percent discount would be applied to the telephone. Neither the 30 percent discount nor the free shipping discount would apply to the telephone purchase because those discounts are a lower priority.

If two discounts have the same priority, the type of database you are using may influence which discount is applied. The results will be undetermined for those with the same priority.

Discounts based on Quantity or Value Purchased

You can apply discounts based on the quantity that users purchase, or on the value of the purchase. For example, you can create a discount that applies when a user buys three cases of juice (quantity), or a discount that applies when a user buys $20.00 worth of juice (value).

You can apply one discount per quantity or value. For example, the beverage department of your online store has a special offer for summer: buy one case of juice; get the second case for half price. However, your online store has another special offering 10 percent discount on each product in the beverage category. Assume you prioritize these discounts as shown in the following table.

Discount | Priority
Buy one case of juice, get the second case at a 50 percent discount | 10
10 percent discount on each product in the beverage category | 20

If a user buys four cases of juice, the discounts are applied as follows:

  • Case 1: No discount

  • Case 2: 50 percent discount

  • Case 3: 10 percent discount

  • Case 4: 50 percent discount, only if no limit was placed on the "Buy one get second half price" discount. The 50 percent discount would apply again instead of the 10 percent discount because you gave it a higher priority.

Discount Limits

You can limit the number of discounts that can be applied to a basket. If the discount limit has a value of zero (0), discounts are unlimited: the discount can apply multiple times, assuming the condition for the discount is met multiple times in the basket. The discount limit is a basket limit and does not apply across baskets. For example, if a user checks out and comes in and buys the same discounted items then the user will enjoy the same discount again.

Processing Discount Campaign Items

Discount campaigns are processed by the discounts Content Selection pipeline and the OrderDiscount pipeline component. You use the discounts CSF pipeline to advertise the most appropriate discount to a user. The OrderDiscount component in the Basket pipeline is used to apply discounts to the shopping basket.

  • Discounts Content Selection pipeline checks the start date and end date of the discounts, and then adjusts the scores in the list of possible discounts. It ensures that the discounts that are most relevant to the current user receive the highest priority.

  • The OrderDiscount pipeline component first applies the requirements to the available discounts. Depending on the discount involved, it uses the user profile and context profile information to evaluate target expressions. In addition, if a discount requires a click, it checks a list of campaign item IDs of every item clicked. Next, the Order pipeline processes each item, testing the conditions and awards. Discounts are applied from highest to lowest priority. If two discounts have the same priority, the discount is nondeterministic—that is, properties other than the priority determine the order in which the discounts are applied.

Direct Mail

You create a direct mail campaign item to distribute e-mail message ads to a targeted group of users. The objective is to achieve a high response rate from the mailings. You can send personalized e-mail messages from a Web page, or non-personalized messages from a flat text file. You can create direct mail messages that include attachments, such as pictures, discounts, or URLs. The Direct Mail service is designed to send bulk personalized e-mail messages to millions of users.

To set up a direct mail campaign you use the Campaign Manager module in Business Desk. Direct mail campaign items are processed by the Direct Mailer service, a powerful engine that can send a large number of e-mails very quickly.

To create a direct mail campaign item, you perform the following steps:

  • Create the message. To create personalized e-mail messages your site developer must first create ASP pages with the personalized text, and then add them to the Web server. The site developer must give you the URL for the location of the ASP pages. To create a non-personalized message, you can type the text in the flat text file, for example, using Notepad.

  • Generate a list of recipients. You can generate a list of recipients for the direct mail campaign using the powerful analysis tools in Commerce Server. For example, using the Reports module in Business Desk, you can run a report against the data in the Data Warehouse to obtain a list of specific users. You can then export the resulting list to the List Manager. Or, you can use the Predictor resource to generate a list of users in a population segment, and then export that list of users to the List Manager. After a list is in the List Manager, it is available to the Direct Mailer.

    You cannot use target groups to send direct mail directly to user e-mail addresses.

  • Create and schedule the direct mail campaign. Use the Campaign Manager module to specify the name of the campaign, the name of the list of recipients, the start time and date of the campaign item, and the URL (for personalized messages) or static file where Direct Mailer will receive the message body.

For more information about adding direct mail campaign items, see Adding a Direct Mail Campaign Item.

Opt Out Lists

Direct Mailer supports an opt-out feature. For direct mail jobs running as part of a campaign item, individual recipients can request to opt out of a direct mail campaign item. You can filter a mailing list against an opt-out list using an opt-out ASP page that is shipped as part of the Solution sites.

The developer that authors the ASP page for the Direct Mailer jobs from the Web server can provide links to an opt-out.asp page, which the recipient can use to either opt out from the site or the direct mail campaign item by clicking the appropriate link. When a Direct Mailer job running as part of a campaign item is executed, Direct Mailer checks for the presence of the site level opt-out list and the campaign item level opt-out list. If either list exists, they are subtracted from the original mailing list and the resulting list acts as the new mailing list.

Processing Direct Mail Campaign Items

Direct Mailer performs the following tasks:

  • Manages direct mail jobs.

  • Constructs personalized and non-personalized message bodies.

  • Formats e-mail message headers.

  • Sets the code-page value (language) and converts message bodies to the correct message type: MIME Encapsulation of Aggregate HTML Documents (MHTML), Multipurpose Internet Mail Extensions (MIME), or text.

  • Sends e-mail messages to recipients.

The Direct Mailer pipeline is used to process lists of recipients. You can add new components to the pipeline, integrate the components with line-of-business systems, or replace them with components supplied by third parties.

Analyzing Campaign Effectiveness

The following table lists the reports included with Commerce Server that you use to analyze the effectiveness of a campaign item.

Report | Description
Campaign Item Summary | Review a summary of campaign activity on your site. This report displays information such as the number and percentage of clicks and the number of ad requests remaining.
Ad Reach and Frequency per Day | Analyze the behavior of daily unique users who interact with your campaign. Use this report to understand the interaction of daily unique users with your campaigns.
Ad Reach and Frequency per Campaign Item | Analyze the interaction of unique users with your campaign items. This report displays the behavior of unique users who interact with your campaign items for all time.
Ad Reach and Frequency per Campaign | Analyze the interaction of unique users with your campaigns. This report displays the behavior of unique users who interact with your campaign for all time.
Campaign Event Summary | Analyze the effectiveness of campaigns on your site. This report displays a summary of campaign activity on your site.
Ad Placement | Analyze where in your site ads are most effective. This report displays a summary of the activity of campaigns by location on your site.

For a list of all Commerce Server reports, see Commerce Server Reports. For information about running reports, see Running Reports.

See Also

Business Desk Campaigns

Running Direct Mailer

Working with Pipelines

Extending the Content Selection Framework

Targeting and Personalization


Commerce Server Security

Commerce Server provides two tools to manage user authentication and identification: the AuthManager object and the AuthFilter.

  • AuthManager is a Component Object Model (COM) object that exposes methods for identifying users and controlling access to dynamically generated content. For example, a site developer could invoke the GetUserID method of AuthManager object to identify a user based on a cookie or a query string.

  • AuthFilter is an Internet Server API (ISAPI) filter that is used at the Internet Information Services (IIS) Commerce Server application level. It can be applied to all users visiting the application. You configure properties used by AuthFilter at the global CS Authentication level. You configure the authentication mode at the application level. You can choose the following authentication modes: Windows Authentication, Custom Authentication, and Autocookie.

When you configure the AuthManager object and AuthFilter, the authentication properties are stored in the Administration database. The CS Authentication resource interacts with the Config objects to store and retrieve the properties from the Administration database.

The Solution Sites do not use AuthFilter because they are designed to support cookieless shopping.

The following table summarizes the differences among the features supported by AuthFilter, the AuthManager object, and the Solution Sites.

Feature | AuthFilter | AuthManager | Solution Sites
Checks whether session cookies (non-persistent cookies) are supported | Yes | No | Yes
Supports cookieless shopping | No | Yes | Yes
Provides granular access control using access control lists (ACLs) | Yes | No | No
Supports custom login pages for retrieving Windows credentials | Yes | Yes | No
URL case correction | Yes | No | Yes

This section contains:

  • General Security Elements. Describes the main security elements that are used on a Commerce Server installation.

  • Commerce Server Authentication Methods. Describes the AuthManager object and the AuthFilter.

  • Authentication Tickets. Describes the MSCSProfile ticket and the MSCSAuth ticket, and explains how Commerce Server uses them to identify guest and registered users.

  • IIS Authentication Methods. Describes the Internet Information Services (IIS) 5.0 authentication methods used with Commerce Server.

  • For Additional Security Information. Lists additional resources for information about developing with the AuthManager object and AuthFilter, and lists links to topics about securing a site.

See Also

Planning for Security

Working with Site Security and Filters

Site Security Objects

Managing the CS Authentication Resource

Commerce Server Security Checklist

Securing Your Site


General Security Elements

This topic describes the main security elements that are used on a Commerce Server installation: authentication, access control, encryption, auditing, and certificates.

Authentication Overview

Access Control Overview

Certificates Overview

Encryption Overview

Auditing Overview

Authentication Overview

Commerce Server supports seven authentication methods: three authentication methods that Commerce Server provides (Windows Authentication, Custom Authentication and Autocookie), and four authentication methods that Internet Information Services (IIS) provides (Anonymous, Basic, Integrated, and Certificates).

Commerce Server does not know which of the IIS authentication methods take place. When you use any of these authentication methods, except anonymous, Commerce Server can access the Active Server Pages (ASP) environment and programmatically ask for the name of the user (currently logged on) using server request variables.

IIS provides security features that are fully integrated with Windows. Commerce Server supports four IIS authentication methods so that you can confirm the identity of anyone requesting access to your Web sites. These IIS authentication methods are:

  • Anonymous authentication allows anyone access without asking for a user name or password.

  • Basic authentication will prompt the user for a user name and password, which are sent unencrypted over the network.

  • Integrated Windows authentication uses hashing technology to identify your user without actually sending the password over the network.

  • Certificates are digital credentials that can be used for establishing a Secure Sockets Layer (SSL) connection. They can also be used for authentication.

You can use these methods to grant access to public areas of your site, while preventing unauthorized access to your private files and directories. For more information about these methods, see IIS Authentication Methods.

Access Control Overview

With NTFS access permissions, the foundation of the security for your Web server, you can define the level of file and directory access granted to Windows users and groups. For example, if a business decided to publish its catalog on your Web server, you would need to create a Windows user account for that business and then configure permissions for the specific Web site, directory, or file. The permissions would enable only the server administrator and the owner of the business to update the content for the Web site. Public users would be allowed to view the Web site, but cannot alter its contents. For more details about setting NTFS permissions, see "Setting NTFS Permissions for a Directory or File" in the IIS 5.0 Documentation.

WebDAV is an extension of the HTTP 1.1 protocol that facilitates file and directory manipulation over an HTTP connection. Through the use of WebDAV "verbs," or commands, properties can be added to and read from files and directories. Files and directories can also be remotely created, deleted, moved, or copied. Additional access control can be configured through both Web server permissions and NTFS. For more information, see "About Access Control" or "WebDAV Publishing" in the IIS 5.0 Documentation.

Certificates Overview

Certificates are digital identification documents that allow both servers and clients to authenticate each other. They are required for both the server and the browser belonging to the client to set up an SSL connection over which encrypted information can be sent. The certificate-based SSL features in IIS consist of a server certificate, a client certificate, and various digital keys. You can create these certificates with Microsoft Certificate Services or obtain them from a mutually trusted, third-party organization called a certification authority (CA). For more information about setting up certificates and keys, see "Setting Up SSL on Your Server" in the IIS 5.0 Documentation.

Server Certificates

Server certificates provide a way for users to confirm the identity of your Web site. A server certificate contains detailed identification information, such as the name of the organization affiliated with the server content, the name of the organization that issued the certificate, and a public key used in establishing an encrypted connection. This information helps to assure users of the authenticity of Web server content and the integrity of the secure HTTP connection.

Client Certificates

With SSL, your Web server also has the option of authenticating users by checking the contents of their client certificates. A typical client certificate contains detailed identification information about a user and the organization that issued the certificate and a public key. You can use client certificate authentication, along with SSL encryption, to implement a highly secure method for verifying the identity of your users.

Encryption Overview

You can enable users to exchange private information with your server, such as credit card numbers or phone numbers, in a secure way by using encryption. Encryption "scrambles" the information before it is sent, and decryption "unscrambles" it after it is received. The foundation for this encryption in IIS is the SSL 3.0 protocol, which provides a secure way of establishing an encrypted communication link with users. SSL confirms the authenticity of your Web site and, optionally, the identity of users accessing restricted Web sites.

Certificates include keys used in establishing an SSL secure connection. A key is a unique value used to authenticate the server and the client in establishing an SSL connection. A public key and a private key form an SSL key pair. Your Web server uses the key pair to negotiate a secure connection with the Web browser to determine the level of encryption required for securing communications.

For this type of connection, both your Web server and the Web browser must be equipped with compatible encryption and decryption capabilities. During the exchange an encryption, or session, key is created. Both your server and the Web browser use the session key to encrypt and decrypt transmitted information. The degree of encryption, or strength, of a session key is measured in bits. The greater the number of bits comprising the session key, the greater the level of encryption and security. Although these greater encryption key strengths offer greater security, they also require more server resources to implement. The session key of your Web server is typically 40 bits long, but can be 128 bits long depending upon the level of security you require.

You can use Commerce Server to generate new encryption keys. For information, see Generating a New Encryption Key.

Auditing Overview

You can use security auditing techniques to monitor a broad range of user and Web server security activity. It is recommended that you routinely audit your server configuration to detect areas where resources may be susceptible to unauthorized access and tampering. You can use the integrated Windows utilities, or the logging features built into IIS 5.0, or use ASP applications to create your own auditing logs. For more information, see "Auditing" in the IIS 5.0 Documentation.


Commerce Server Authentication Methods

Commerce Server 2000 extends the authentication methods supported by Internet Information Services (IIS) 5.0 in two ways. First, it adds granular access control for dynamic content through AuthFilter, an Internet Server API (ISAPI) filter. Second, it provides a way to use Windows Authentication or Custom Authentication in an Internet environment where you need to address a wide range of browsers. Commerce Server provides this support for Windows and Custom Authentication.

When you use AuthFilter, you can choose the following authentication modes:

  • No Filter mode. AuthFilter is not enabled.

  • Windows Authentication. AuthFilter uses Windows Authentication to control access to the site. It checks the user login and password against Active Directory (or a local Security Access Manager account). When you use Windows Authentication, you can require login access for only certain Active Server Pages (ASP) pages and directories that you specify. To use Windows Authentication, see Enabling Windows Authentication.

  • Custom Authentication. AuthFilter checks the user login and password (MSCSAuth ticket) against a SQL Server database or other type of database. Login access is required for every ASP page and directory in the Commerce Server site. AuthFilter checks against the virtual directory for the Commerce Server site, and it checks the Commerce Server Administration database to determine whether Custom Authentication is enabled for that site. If the MSCSAuth ticket is not valid, AuthFilter requires the user to enter login information.

    When you use Custom Authentication, login access is required for every ASP page and directory in the Commerce Server site. To use Custom Authentication, see Enabling Custom Authentication.

  • Autocookie mode. You can automatically generate cookies, which store tickets, for guest users. (When an anonymous user gets an MSCSProfile ticket, the user becomes a guest user.) MSCSProfile tickets enable you to collect profile data about how guest users navigate and use your site.

    If you select Autocookie mode and No Filter mode, then there are no registered users.

    If you are using Autocookie and either Windows Authentication mode or Custom Authentication mode, known as mixed mode, then when guest users register, their persistent cookies can be updated, and you do not lose the profile data gathered when the user was a guest. To use Autocookie mode, see Enabling Autocookie Generation.

If you enable mixed mode, AuthFilter generates the following tickets:

  • The first time the user logs in to the site, it generates an MSCSProfile ticket.

  • If the user is authenticated, it generates the MSCSAuth ticket, which will contain the user ID. You can use the MSCSAuth ticket for access control.

  • If the user is not authenticated (no MSCSAuth ticket), the MSCSProfile ticket will indicate that the user is anonymous.

For more information about tickets, see Authentication Tickets.

See Also

Planning for Security

Working with Site Security and Filters

Site Security Objects

Managing the CS Authentication Resource

Commerce Server Security Checklist

Securing Your Site


Authentication Tickets

A ticket is a property/value pair such as userID and the value of userID. For example, userID/joeuser is a ticket. Commerce Server uses tickets to store information about users visiting a site. A ticket can be stored in a cookie or in a URL query string.

Commerce Server supports two types of tickets:

  • MSCSProfile ticket is used to identify and track anonymous/guest users who visit your site. MSCSProfile tickets are stored in persistent cookies for users who allow persistent cookies. When you configure the CS Authentication resource, you determine how long the cookie is valid, typically for several years.

    Although anonymous users do not have a ticket, in some configurations of Windows Authentication, anonymous users must get a ticket, thereby becoming guest users. If you use Autocookie mode, for example, anonymous users become guest users.

  • MSCSAuth ticket is used to identify and track registered (authenticated) users. MSCSAuth tickets are stored in non-persistent cookies for users who allow cookies. If users do not allow cookies, the ticket data is stored in a URL query string. When the session ends, the cookies are deleted.

The type of ticket issued determines which resources the user can access on your Web site.

Both persistent and non-persistent cookies can be encrypted. These cookies contain the following data:

  • User ID (ticket). Used for persistent and non-persistent cookies. A site developer can determine the value to use as the user ID. For example, it can be either the login name or the e-mail address of a user. For anonymous users, the user ID can be, for example, a globally unique identifier (GUID) generated by one of your ASP pages. (Commerce Server includes the GenID object, which you can use to generate GUIDs.)

  • Time of last login. Used for non-persistent cookies. The "Time of last login" determines when users need to be re-authenticated. For example, users do not need to be re-authenticated if they register at your Web site, and then leave their computer without logging off (or are inactive for a period of time), and then return to their computer before the close of the Time Window. However, if users return after the close of the Time Window, then they must log in again.

  • Time Window. Used for non-persistent cookies to determine how long, in minutes, the cookie is valid.

After a user logs off a site, the authentication expires. A site developer can add custom properties to both types of cookies.

See Also

Cookies and Authentication

Planning for Security

Working with Site Security and Filters

Managing the CS Authentication Resource

Commerce Server Security Checklist

Securing Your Site


IIS Authentication Methods

Commerce Server supports the following four authentication methods provided by Internet Information Services (IIS) 5.0:

Anonymous Authentication

Basic Authentication

Integrated Windows Authentication

Certificate Authentication

Anonymous Authentication

Anonymous authentication gives users access to the public areas of your Web site without prompting them for a user name or password. When a user attempts to connect to your public Web site, your Web server assigns the user to the Windows user account called IUSR_<computername>, where <computername> is the name of the server on which IIS is running.

By default, the IUSR_<computername> account is included in the Windows user group Guests. This group has security restrictions, imposed by NTFS permissions that designate the level of access and the type of content available to public users.

If you have multiple sites on your server, or if you have areas of your site that require different access privileges, you can create multiple anonymous accounts, one for each Web or FTP site, directory, or file. By giving these accounts differing access permissions, or by assigning these accounts to different Windows user groups, you can grant users anonymous access to different areas of your public Web and FTP content.

IIS uses the IUSR_<computername> account in the following way:

  1. The IUSR_<computername> account is added to the Guests group on the computer.

  2. When a request is received, IIS will impersonate the IUSR_<computername> account before executing any code or accessing any files. IIS is able to impersonate the IUSR_<computername> account because the user name and password for this account are known by IIS.

  3. Before returning a page to the client, IIS checks NTFS file and directory permissions to see if the IUSR_<computername> account is allowed access to the file.

  4. If access is allowed, authentication completes and the resources are available to the user.

  5. If access is not allowed, IIS will attempt to use another authentication method. If none is selected, IIS returns an "HTTP 403 Access Denied" error message to the browser.

Notes

  • If Anonymous authentication is enabled, IIS will always try to authenticate using it first, even if other methods are enabled.

  • In some cases the browser will prompt the user for a user name and password.

You can change the account that is used for Anonymous authentication in the IIS snap-in, either at the Web server service level, or for individual virtual directories and files. The anonymous account must have the user right to log on locally. If the account does not have Log On Locally permission, IIS will not be able to service any anonymous requests. The IIS installation specifically grants the Log On Locally permission to the IUSR_<computername> account. By default, the IUSR_<computername> accounts on domain controllers are not given to guest accounts; they must be changed to Log On Locally to allow anonymous logons.

Note

  • You can change the requirement for Log On Locally permissions by using the Active Directory Service Interfaces (ADSI). For information, see the "LogonMethod" reference in the Active Server Pages Guide of the IIS 5.0 Documentation.

You can also change the security privileges for the IUSR_<computername> account in Windows by using the Group Policy Manager snap-in in the Microsoft Management Console (MMC). However, if the anonymous user account does not have permission to access a specific file or resource, your Web server will refuse to establish an anonymous connection for that resource. For more information, see "Setting Web Server Permissions" in the IIS 5.0 Documentation.

Important

  • If you change the IUSR_<computername> account, the changes will affect every anonymous HTTP request that is serviced by a Web server. Use caution if you modify this account.

Basic Authentication

The Basic authentication method is a widely used, industry-standard method for collecting user name and password information. Basic authentication proceeds as follows:

  1. The Web browser on the client computer displays a dialog box where users can enter their previously assigned Windows 2000 account user names and passwords.

  2. The Web browser then attempts to establish a connection using this information. (The password is Base64 encoded before being sent over the network).

  3. If the server rejects the information, the Web browser repeatedly displays the dialog box until the user either enters a valid user name and password or closes the dialog box.

  4. When your Web server verifies that the user name and password correspond to a valid Windows user account, a connection established.

For information about setting up Basic authentication, see "Enabling and Configuring Authentication" in the IIS 5.0 Online Documentation.

The advantage of Basic authentication is that it is part of the HTTP specification, and is supported by most browsers. The disadvantage is that Web browsers using Basic authentication transmit passwords in an unencrypted form. By monitoring communications on your network, someone could easily intercept and decipher these passwords by using publicly available tools. Therefore, Basic authentication is not recommended unless you are confident that the connection between the user and your Web server is secure, such as a direct cable connection or a dedicated line.

Note

  • Integrated Windows authentication takes precedence over Basic authentication. The browser will choose integrated Windows authentication and will attempt to use the current Windows logon information before prompting the user for a user name and password. Currently, only Internet Explorer, version 2.0 and later, supports integrated Windows authentication.

Integrated Windows Authentication

Integrated Windows authentication (formerly called NTLM or Windows NT Challenge/Response authentication) is a secure form of authentication because the user name and password are not sent across the network. When you enable integrated Windows authentication, the browser of the user proves its knowledge of the password through a cryptographic exchange with your Web server, involving hashing. (The authentication credentials pass through a one-way process, often referred to as hashing. The result of this process is called a hash, or message digest, and it is not feasible to decrypt it. That is, the original text cannot be deciphered from the hash.)

Integrated Windows authentication can use both the Kerberos v5 authentication protocol and its own challenge/response authentication protocol. If Directory Services is installed on the server, and the browser is compatible with the Kerberos v5 authentication protocol, both the Kerberos v5 protocol and the challenge/response protocol are used; otherwise only the challenge/response protocol is used.

The Kerberos v5 authentication protocol is a feature of the Windows 2000 Distributed Services architecture. In order for Kerberos v5 authentication to be successful, both the client and server must have a trusted connection to a Key Distribution Center (KDC) and be Directory Services compatible. For more information about the protocol, see the Windows 2000 documentation.

Integrated Windows authentication proceeds as follows:

  1. Unlike Basic authentication, it does not initially prompt users for a user name and password. The current Windows user information on the client computer is used for the integrated Windows authentication.

    Note

    • Internet Explorer, version 4.0 and later, can be configured to initially prompt for user information if needed. For more information, see the Internet Explorer documentation.
  2. However, if the authentication exchange initially fails to identify the user, the browser will prompt the user for a Windows user account user name and password, which it will process by using integrated Windows authentication.

  3. Internet Explorer will continue to prompt the user until the user enters a valid user name and password, or closes the prompt dialog box.

Although integrated Windows authentication is secure, it does have three limitations:

  1. Only Microsoft Internet Explorer, version 2.0 or later, supports this authentication method.

  2. Integrated Windows authentication does not work over HTTP Proxy connections.

  3. Additional TCP ports have to be opened in the firewall.

Therefore, integrated Windows authentication is best suited for an intranet environment, where both user and Web server computers are in the same domain, and where administrators can ensure that every user has Microsoft Internet Explorer, version 2.0 or later.

Certificate Authentication

You can also use the Secure Sockets Layer (SSL) security features of your Web server for two types of authentication. You can use a server certificate to allow users to authenticate your Web site before they transmit personal information, such as a credit card number. Also, you can use client certificates to authenticate users requesting information on your Web site. SSL authenticates by checking the contents of an encrypted digital identification submitted by the Web browser for the user during the logon process. (Users obtain client certificates from a mutually trusted third-party organization.) Server certificates usually contain information about your company and the organization that issued the certificate. Client certificates usually contain identifying information about the user and the organization that issued the certificate.

Client Certificate Mapping

You can associate, or map, client certificates to Windows user accounts on your Web server. After you create and enable a certificate map, each time a user logs on with a client certificate, your Web server automatically associates that user to the appropriate Windows user account. This way, you can automatically authenticate users who log on with client certificates, without requiring the use of either Basic, Messaging Digest, or integrated Windows authentication. You can either map one client certificate to one Windows user account or many client certificates to one account. For example, if you had several different departments or businesses on your server, each with its own Web site, you could use many-to-one mapping to map all of the client certificates of each department or company to its own Web site. This way each site would provide access only to its own clients. For more information, see "Mapping Client Certificates to User Accounts" in the IIS 5.0 online documentation.


For Additional Security Information

Commerce Server 2000 Help provides the following topics on security:

  • Cookies and Authentication. Describes Commerce Server cookies and how Commerce Server uses them in a Web farm scenario.

  • Planning for Security. Provides recommendations for questions about your security implementation.

  • Working with Site Security and Filters. Provides detailed information about developing a site using AuthFilter.

  • Site Security Objects. Describes how to use the AuthManager object, and the BizDeskSecurity object. Provides example code for the site security objects.

  • Managing the CS Authentication Resource. Explains how to use the CS Authentication resource to establish or change the authentication method for your Commerce Server site. Provides Login.asp code samples for enabling AuthFilter for the Retail and Supplier Solution Sites.

  • Commerce Server Security Checklist. Provides a list of security issues specific to Commerce Server, such as securing Commerce Server Business Desk sessions, and explains how to implement them.

  • Securing Your Site. Explain how to secure a Commerce Server site, including how to limit access to your site, Business Desk module, and the Administration database.

For additional information about security, see the following resources:

  • The Commerce Server 2000 Resource Kit. Describes how to implement security when developing with a Commerce Server Solution Site. The Commerce Server 2000 Resource Kit is available from Microsoft Press.

  • The Internet Information Services (IIS) Online Documentation

  • The Microsoft Windows 2000 Server Resource Kit

  • The Microsoft Security site at http://www.microsoft.com/security/

  • The Microsoft Windows Security site at http://www.microsoft.com/ntserver/security/default.asp


Planning Your Commerce Server Installation

You must make some planning decisions before developing and deploying your Microsoft Commerce Server 2000 installation. To successfully develop and deploy Commerce Server, it is important that you carefully consider these planning issues and research the implications by consulting other areas of Commerce Server 2000 Help.

Planning your Commerce Server implementation is the first and perhaps most crucial phase in the Planning-Developing-Deploying-Managing cycle. This is because planning your site carefully, including taking future growth into account, can prevent the need to make expensive and time-consuming modifications later.

Five tightly integrated sub-systems comprise Commerce Server. In addition to planning for these sub-systems, you will need to plan for the management and administration of your implementation. The topics in this section cover planning for each of the sub-systems.

This section contains:

  • Planning for Administration and Management Tools. Provides recommendations for questions about managing and administering your site.

  • Planning for the Business Analytics System. Provides recommendations for questions about accessing and updating your data.

  • Planning for Business Process Pipelines. Provides recommendations for questions about pipeline functionality.

  • Planning for the Product Catalog System. Provides recommendations for questions about your Product Catalog system.

  • Planning for the Profiling System. Provides recommendations for questions about your Profiling System.

  • Planning for the Targeting System. Provides recommendations for questions about your Targeting System.

  • Planning Your Site Architecture and Security. Provides recommendations for questions about your site architecture and security.

  • Planning for Deployment. Provides recommendations for questions about planning the deployment of your site.


Planning for Administration and Management Tools

Commerce Server 2000 includes three tools for managing and administering your installation: Commerce Server Business Desk, Partner Service, and Commerce Server Manager.

You use Business Desk to configure many site options and to manage the day-to-day marketing and analysis of site activity. You must make some decisions about your site in order to optimize your use of Business Desk.

The following table lists some of the questions that you need to answer in planning for the administration and management tools.

Planning question | Recommendation
Will your site be aimed primarily at consumers or at trading partners? | If your site is aimed at consumers, you should start development with the Retail Solution Site because it includes the Customer Service, which provides users access to their profile information. If your site is aimed at trading partners you should start development with the Supplier Solution Site because it includes the Partner Service, which provides trading partners with access to their accounts. To download the Solution Sites, see http://www.microsoft.com/commerceserver/solutionsites.
If you are planning to interact with trading partners, do you need to exchange business documents with them? | You should plan on integrating Microsoft BizTalk Server 2000 with your implementation if you will exchange business documents with trading partners.
What payment options will your site support? | You must make arrangements with a banking institution if you plan to support credit card processing.
Which currencies will your site support? | If your site will display information in multiple currencies, you need to extend the Product Catalog System.
Do business managers need to access large sets of data? | Some aspects of site management do not lend themselves to accessing large data sets through Business Desk. For example, if your product catalog includes over 100,000 items, you may need to publish updates with a script, rather than through the Catalogs modules provided in Business Desk. You should plan for the capacity requirements of your Business Desk.

See Also

Localizing Currencies

Using BizTalk Server and Commerce Server

Planning for Capacity and Performance

Configuring App Default Config Resource Properties


Planning for the Business Analytics System

You use the Commerce Server 2000 Data Warehouse to collect day-to-day operational data about users who visit your site, including user profile data, transaction data, and click-history data. You use the Analysis modules to analyze the data, for example, to identify user trends or analyze the effectiveness of a campaign, and then update your site to target specific user groups, sell specific products, and so forth.

The following table lists some of the questions that you need to answer in planning for the Business Analytics System.

Planning question | Recommendation
How will data analysis affect the key business decisions you need to make about your site? What reports do you need in order to make those decisions? | To examine the reports available from the Business Analytics System, see Commerce Server Reports. If the reports do not meet your requirements, see Creating Custom Reports to learn more about modifying existing reports or creating new reports. There are also a number of third-party software vendors who provide reporting solutions that interact with the Business Analytics System.
Who in your organization needs access to the data? How often do they need to run the reports, and how much detail do they require from updates? | You should establish a schedule for running reports. You need to run static reports periodically or the data will become outdated. You should time running reports with running the Data Transformation Services (DTS) tasks.
How often will you process your Web server logs? | The size and nature of the data stored in your logs will determine your answer. The more frequently you process the logs, the smaller they will be. Larger log files provide a richer data set, but they also take longer to process. You should determine the appropriate processing frequency in your test environment, and then apply it to your production environment.

See Also

Commerce Server Reports

Custom Reports

Data Warehouse

Working with the Data Warehouse


Planning for Business Process Pipelines

You use pipelines to define and link together one or more stages of a business process, and then run them in sequence to complete a specific task. Each stage of a pipeline contains one or more pipeline components, which are (Component Object Model (COM) objects that can be configured to work with the unique requirements of a site.

Site developers use this infrastructure to implement two pipeline models: the Order Processing pipeline (OPP) and the Content Selection pipeline (CSP).

The following table lists some of the questions that you need to answer in planning for Business Process Pipelines.

Planning question | Recommendation
Do the pipeline components included with Commerce Server meet your requirements? If not, do you want to build your own components or purchase them from a third-party pipeline component developer? | Examine the functionality provided by the pipelines included with Commerce Server 2000. Determine whether the processing stages meet your needs. If they do not, either extend the pipelines yourself or purchase pipeline components from a third-party pipeline component developer. For example, you can add third-party pipeline components to perform complex tax or shipping calculations and credit card processing.

See Also

Working with Pipelines

Building Pipeline Components

Extending the Content Selection Framework


Planning for the Product Catalog System

You use the Product Catalog System to create catalogs of products and to add and update product data. This system provides both import and export functionality, and allows you to define and modify the schema for catalogs.

The following table lists some of the questions that you need to answer in planning for the Product Catalog System.

Planning question | Recommendation
Do you plan to synchronize information in the Product Catalog System with an offline catalog? | If you synchronize information in the Product Catalog System with your offline catalog, you must develop custom software. If you require this functionality, consult with your system administrator.
What is the best organizational schema for your catalog? | The Product Catalog System is flexible enough to accommodate a variety of schemas. If you are designing a new catalog, make sure to include plenty of opportunities for expanding the schema.
Do you use complex pricing models or other requirements beyond the functionality of the Product Catalog System? | If so, consider using a third-party catalog management solution. A number of catalog solution vendors offer products that support Commerce Server and provide additional functionality. You can also extend the Product Catalog System by building your own pipeline components to accommodate complex pricing requirements.
Will you provide custom catalogs to different user groups? | Create a base catalog that you can then modify based on user properties. Planning for these custom catalogs should be done in conjunction with planning for the Profiling System.
What catalog data will you export to the Data Warehouse? | You should export the information required to create the reports you identified when you planned for using the Business Analytics System.
Will you exchange catalogs with your trading partners? | If you will, then include Microsoft BizTalk Server 2000 in your deployment plan. It provides the functionality required to exchange catalogs.

See Also

About Catalogs

Business Desk Catalogs

Using BizTalk Server and Commerce Server

Integrating a Third-Party Product Catalog


Planning for the Profiling System

In Commerce Server 2000, you use profiles to collect and store information about the users who visit your Web site. The data that forms a profile comes from multiple data sources, such as Web log files and Commerce Server databases. You import the profile data into the Data Warehouse for analysis, and then you can use the results to target content to groups of users.

The following table lists some of the questions that you need to answer in planning for the Profiling System.

Planning question | Recommendation
What are the business decisions you will make with the information you collect in the Profiling System? | Begin planning for the Profiling System by answering this question. Your answer will determine the rest of your planning decisions for this system.
What kinds of business entities (for example, customers, companies, products, purchase orders, and accounts) do you currently store information for? Of these, which entities will you need to store information about in the Profiling System? | The Profiling System is flexible enough to capture and store information about a wide variety of business entities. The system can aggregate this information from disparate data sources. You set up the system by defining the entities and data sources. You should coordinate this planning effort with your database administrator to make sure that the data entities defined are consistent with entities that exist in your database management system.
What profile information will you export to the Data Warehouse? | You need to export the information you use to create the reports that you identified in response to the question listed in Planning for the Business Analytics System.
What information will you collect about users? | You can either collect information from users directly or you can use the Predictor resource to fill in the information you need (implicit targeting).
Which data store will you use for storing profiles? | If you need to authenticate users with their Microsoft Windows 2000 security context, you will need to store some profile information in Microsoft Active Directory. If you do not have this requirement, use Microsoft SQL Server 2000 to store profile data.
Are there existing user accounts that you need to transfer into the Profiling system? Will you need to transfer all of the attributes from the current system? | If you are transferring user accounts from Microsoft Site Server 3.0 Membership Directory, use the Directory Migration Toolbox to transfer this information. Do not plan on maintaining the Membership Directory after you have migrated.

See Also

About the Profiles Resource

Running the Profiles Resource

Running the Predictor Resource

Migrating the Membership Directory


Planning for the Targeting System

You use the Targeting System to deliver content to one or more users. The Targeting System includes four distinct sub-systems, which you should consider in planning for the Targeting System.

This section contains:

  • Planning for the Content Selection Framework

  • Planning for Direct Mailer

  • Planning for the Expression Evaluator

  • Planning for the Predictor Resource


Planning for the Content Selection Framework

Content Selection Framework (CSF) is a framework based on the Commerce Server 2000 pipeline architecture. You use CSF mainly for campaign management (the delivery of advertisements and promotions), but it is flexible enough to rank, select, and schedule any type of content.

The following table lists some of the questions that you need to answer in planning for your online campaigns

Planning question | Recommendation
Will you target campaigns to particular user groups? If so, which user attributes will you target? | Use the Business Analytics System to determine common buying patterns on your site and then incorporate this information into your Targeting System. Planning for this area will be an ongoing process.
Will you sell advertising to other organizations? If so, what is the price schedule for the advertising? | Establish a price schedule if you do not already have one. You will need this information when setting up your campaigns in Commerce Server Business Desk.
Who will make decisions about discounting inventory? What policies will you have for these decisions? | Coordinate your discounts with your advertising campaigns to maximize their effectiveness.
What information do you require from the Business Analytics System to make pricing decisions? | Determine your information requirements for the CSF and use this determination to evaluate and modify, if necessary, the reports provided by the Business Analytics System.
Will your campaigns use the Predictor resource? If so, what are the key user segments you need to target? | Collect information about usage patterns in the Commerce Server Data Warehouse, use the Predictor resource to identify user segments, and then incorporate this information back into your campaigns.

See Also

Extending the Content Selection Framework

Running the Predictor Resource


Planning for Direct Mailer

You use Commerce Server Direct Mailer to manage user mailing lists and to coordinate the sending of direct e-mail to list members. The e-mail you create can be personalized using Active Server Pages (ASP), or it can be a static file. You can use the List Manager module to import e-mail addresses from a flat file or a Microsoft SQL Server database into a mailing database.

The following table lists some of the questions that you need to answer in planning for your direct mail campaigns

Planning question | Recommendation
Who will receive the direct mailings you create? What rules will you use to define the direct mail list? | Use the Business Analytics System to identify the user segments you want to target, and then create corresponding lists.
How will users tell you they want to be removed from the direct mail list? | Always include an opt-out choice in your direct mailings.
How often will you send direct mail? | Establish a schedule and develop a script to automate the process.
Will the direct mail be personalized? If so, what user profile information will you include in the personalization? | Personalized mail is more effective. Design your user profiles to include the attributes you want to use for your direct mail targets.

See Also

About Direct Mailer

Direct Mailer Pipeline

Running Direct Mailer

Developing Direct Mail Content


Planning for the Expression Evaluator

You use the Expression Evaluator to create business rules for delivering personalized ads, discounts, and content. These rules are conditional expressions.

The following table lists some of the questions that you need to answer in planning for the Expression Evaluator.

Planning question | Recommendation
What experience do you want to create for your users? What business rules do you need to create in order to implement that experience? | You must create expressions for the Expression Evaluator to evaluate in order to create the specific user experience you want. Base your expressions on the personalization requirements you have developed for the Targeting System. For example, if you have decided to display content based on a referring Uniform Resource Locator (URL), you might create the expression Referrer equals URL.
What site terms are needed to create the required business rules? | Create site terms to support the expressions you have identified. In the previous example, you would need to develop a site term named "Referrer."

See Also

Expression Builder

Expression-based Targeting

Targeting an Ad or Discount

Adding a Site Term


Planning for the Predictor Resource

You use the Predictor resource primarily to augment analysis of some form of data, such as transaction data or Web log data. The Predictor resource is also used to recommend products to users online and to fill in missing user profile properties.

Before you use the Predictor resource, you must verify that the Analysis reports are providing the information you require. You should collect data on at least a few thousand distinct users before you build models with the Predictor resource.

The following table lists some of the questions that you need to answer in planning for the Predictor resource.

Planning question | Recommendation
Do you plan to offer users product recommendations and enhanced targeting? | Implement the Predictor resource on your site by building models of user behavior after you have collected enough initial data in the Commerce Server Data Warehouse.
What are the key user segments that you must identify in order to make meaningful recommendations? | Use the Predictor resource to identify meaningful segments, and then view them with the Segment Viewer.
Will you use inference to augment user profile data, or will you make recommendations based only on data explicitly provided by users? | You can use the Predictor resource to infer data about users for whom you do not have complete information (for example, guest users). If you plan to infer user properties, use the Segment Viewer in Business Desk together with the Dependency Network view in Commerce Server Manager to focus on the key user attributes you will use to make predictions. You can then use these attributes to target content to users who have similar characteristics.

See Also

About the Predictor Resource

Running the Predictor Resource

Predictor Schema

Prediction Objects


Planning Your Site Architecture and Security

Planning the overall architecture of your e-commerce presence includes planning for growth, setting performance expectations, and establishing security requirements. This section describes some of the planning considerations in each of these areas.

Notes

  • The site architecture for Commerce Server 2000 can include either Microsoft SQL Server 2000 or SQL Server 7.0.

  • The full-text search feature of SQL Server 7.0 used by the full-text index feature of the Product Catalog System cannot be used in a Microsoft Windows NT clustering environment.

This section contains:

  • Planning for Capacity and Performance

  • Planning for Growth

  • Planning for Integration with Existing Systems

  • Planning for High Availability

  • Planning for Security

  • Planning for Active Directory Integration


Planning for Capacity and Performance

It is difficult to predict how variables in site design, coding practices, user behavior, and site architecture will combine to affect site performance. Therefore, it is important to plan and test the capacity and performance of your site before "going live" in a production environment.

If you are migrating an existing site, you can analyze your existing data as a basis for planning the new site. If you are creating a site for the first time, use the sizing guidelines provided in the Commerce Server 2000 Resource Kit to set up a test site, which you can then load, test, and optimize before going live.

Performance planning and capacity planning go hand in hand; however, each addresses a different perspective. Performance planning addresses the technical aspects of the site, focusing on performance metrics, such as Active Server Pages (ASP) page throughput and ASP latency. Capacity planning addresses the business perspective, focusing on maximizing the number of users that the site can handle.

Of the two, performance planning is the more straightforward. It is relatively easy to measure the number of checkout transactions per second and make comparisons to other commerce sites. For information about tools for measuring performance, see Using Performance Monitoring Tools. Additional tools are available in the Commerce Server 2000 Resource Kit.

Analyzing user capacity is a little more complex. Before you can predict the maximum user capacity, you first need to profile user behavior, and then use the user profile information in conjunction with your performance metrics to calculate capacity. User behavior varies from site to site, depending on the richness of the shopping experience (page design, site design, and response time), as well as the types of products being sold and the extent of the product line. One site may support 1,000 users, while another site installed on an identical platform may support only 200 users because of differences in user behavior.

For more information about performance analysis and capacity planning, see the white paper Sizing Guidelines for Windows 2000 Domain Controller and Global Catalog Server, available at http://www.microsoft.com/WINDOWS2000/library/planning/management/dcsize.asp.

The following table lists some of the questions that you need to answer in planning for performance.

Planning question | Recommendation
What are the key items to measure to determine site performance? | Select the factors that closely match your goals for user experience. For example, if it is your goal to enable users to browse the catalog quickly, measure the speed at which a catalog browse request is returned.
What are the key usage profiles for measuring site performance? | Determine how you expect users to connect to your site and the expected load. Use this usage profile in your test environment, and then confirm that the profiles are correct when you have collected usage information in the Commerce Server Data Warehouse.
What tools and resources will you need to measure the performance of your site? | Review the performance tools provided in the Commerce Server 2000 Resource Kit to determine if they meet your requirements.
How many servers do you require for your site? How should they be configured? | Start by reviewing the usage scenario configuration information provided in the Commerce Server 2000 Resource Kit. Compare these scenarios to your site requirements and modify the configurations to meet your needs.
What are your expectations about the rate at which your site usage will grow? | Include excess capacity in the early stages of your site deployment. Compare actual growth to projections at regular intervals.
How will you balance the load across the servers in you site installation? | See the Windows 2000 Resource Kit and the Commerce Server 2000 Resource Kit for information about using Network Load Balancing (NLB).

See Also

Optimizing Commerce Server

Using Performance Monitoring Tools

Monitoring Commerce Server Sites


Planning for Growth

Your initial site design should take future expansion into account. A well-planned site can expand, or scale, cost-effectively to accommodate increased site traffic while maintaining performance.

To plan for the future growth of your site, you should divide your site architecture into two broad layers: front-end Web servers, and back-end systems where data is stored and your business-processing systems are located. Each of these layers may be subdivided into multiple tiers to match the projected growth pattern for your site. Because Commerce Server 2000 is flexible, you can choose an architecture that best suits your needs.

You typically scale the back end first by scaling vertically — that is, by upgrading the server and adding mass storage. Then, you can also subdivide the data layer by function among two or more servers. For example, the Commerce Server Data Warehouse could be placed on one server, and the database for storing profile information on another. With Commerce Server, you can divide functions onto different servers during setup, or do it later using Commerce Server Manager. For very large sites, individual databases can be partitioned onto multiple servers.

The following table lists some of the questions that you need to answer in planning for growth.

Planning question | Recommendation
What site architecture best meets your requirements for increasing your capacity over time? | Review the usage scenario configuration information provided in the Commerce Server 2000 Resource Kit. Select a configuration that best meets your needs.
How will you increase your site capacity as usage requirements increase? | Plan a scaling path for each type of server, each network connection, and each Commerce Server function. This path should include your plan for scaling the site when specified thresholds (such as number of concurrent users, memory usage, or disk usage) are reached.

See Also

Deploying Your Site


Planning for Integration with Existing Systems

During the planning process, you need to assess your existing systems and data to determine the most effective methods to either integrate them with Commerce Server 2000 components or convert them to formats that can be imported into Commerce Server databases. In addition, you will need to plan the integration of your e-commerce business sub-systems.

The following table lists some of the questions that you need to answer in planning for integration.

Planning question | Recommendation
Will you integrate existing databases and database servers that contain such data as catalogs and user profiles or customers? | If you will maintain separate data sources for your offline and online businesses, you must establish a system for synchronizing the data. Consider integrating Microsoft Host Integration Server 2000 and Microsoft Application Center 2000 into your overall system design.
Will you integrate your existing order processing, payment transaction, inventory management, and order fulfillment systems with Commerce Server? | If you plan to integrate these systems, develop Component Object Model (COM) components to connect them to Commerce Server. Consider incorporating Microsoft BizTalk Server 2000 in your overall system design.
Do you need to integrate Enterprise Resource Planning (ERP) systems with suppliers and trading partners? | If you plan to integrate ERP systems, you should incorporate BizTalk Server into your overall system design.
What are your requirements for converting data? | Establish a system for transforming data from its existing format to a format you can use in Commerce Server. For example, you will need to convert existing catalog data in a tab-delimited format to Extensible Markup Language (XML) before importing it into the Product Catalog System.
What are your requirements for custom development? | Although Commerce Server is a full-featured product, it has been designed so that you can customize many features to suit your business requirements. Examine the features list in Commerce Server Features at a Glance carefully and read both Commerce Server 2000 Help and the Commerce Server 2000 Resource Kit before you plan for custom development.
Will you complete the custom development in-house or work with a software vendor? | Review the information about Microsoft Solution Providers and Partners at http://microsoft.com/commerce.

See Also

Integrating with BizTalk Server

Integrating a Third-Party Product Catalog

Adding a Non-Commerce Application and Web Server


Planning for High Availability

Availability is a measure of fault tolerance for a computer, cluster, or system, and its programs. This measure takes into account both the mean time between failures (MTBF) and the mean time to repair (MTTR), and includes downtime for both planned and unplanned events. Many e-commerce sites are mission-critical, so they should be designed to be highly available, meaning they are up and operating at an acceptable service level at least 99.9 percent of the time.

Planning for high availability includes planning hardware and software configurations, as well as defining and testing operational procedures.

The following table lists some of the questions that you need to answer in planning for availability.

Planning question | Recommendation
What level of availability do you require? | Weigh the cost of availability against the business cost of downtime and establish an appropriate availability level.
How will you replicate data across your servers? | Use Microsoft SQL Server to replicate databases.
How will you monitor availability? | Create a process to determine whether you are meeting your availability goals.
How will you respond to disasters? | Develop a plan for recovering data in the event of a catastrophic failure of all or part of your system. Test this plan by simulating a disaster.

See Also

High Availability Checklist


Planning for Security

You plan for Commerce Server 2000 security by planning how to defeat site security threats for all the features deployed on your site and by selecting the policies and tools necessary to achieve the level of security you want.

To build a site that adheres to best security practices, you need to configure Secure Sockets Layer (SSL) so that certain pages (such as pages that request credit card information) are served through SSL. To set this up, you need to get a server certificate and configure Microsoft Internet Information Services (IIS) 5.0 to use SSL. For more information, see the IIS product documentation at http://localhost/iisHelp.

In addition, you can specify a Secure Host Name for each Commerce Server application in the Microsoft Management Console (MMC). The AuthManager object uses the Secure Host Name to create links to secure pages. The links could lead to a different Commerce Server application or to a secure section of the same application.

To minimize the likelihood of a security breach, you must be able to:

  • Lock down the site, which means controlling access to files, pages, and applications with access control lists (ACLs) on files that use the NTFS file system (NTFS).

  • Control access to read, run script, and write access on various folders that are defined in your site for IIS security.

  • Authenticate site visitors.

The following table lists some of the questions that you need to answer to decide what to lock down, how to control access, and how to authenticate.

Planning question | Recommendation
Do you need to authenticate site visitors with their Windows 2000 security context? | Include Microsoft Active Directory in your site configuration if you plan to authenticate users with their Microsoft Windows 2000 security context.
What type of content do you need to lock down? | If you are securing static content, you will need to use the AuthFilter Internet Server Application Programming Interface (ISAPI) filter, because the AuthManager object works on only dynamically generated content.
Will you require users to accept cookies? | The AuthFilter can automatically generate a cookie for new visitors to your site.
Do you plan to use a form-based authentication scheme? | If you are planning to authenticate users using a custom authentication scheme, you will need to run the AuthFilter in Custom mode.
What site architecture best meets your security requirements? | Review the firewall solution summaries in Firewall Configurations and determine which solution is the most appropriate for your installation.

See Also

Commerce Server Security

Firewall Configurations

Commerce Server Security Checklist

Managing the CS Authentication Resource


Planning for Active Directory Integration

Active Directory is the directory service built into Microsoft Windows 2000. You can use Active Directory to add, modify, delete, and organize the business entities of your organization. For example, the Windows 2000 user accounts, computer accounts, security and distribution groups, and published resources are all accessible through Active Directory.

You can use Active Directory as a data source for profile data. The Profiling System aggregates data from Active Directory and other data sources into a single business entity that you can then use in your Commerce Server implementation. For example, you could store the account number and password of a user in Active Directory and store the rest of the account information (contact information, credit limit, preferences, and so forth) in Microsoft SQL Server. The Profiling System would then assemble data from these two data sources into a single profile that you can use for targeting and analysis.

Active Directory is a highly robust and scalable technology; however, it is important that you design your site architecture to use it appropriately.

If you plan to divide users into groups within Active Directory, extra care should be taken to assure that the performance of the Active Directory server is adequate. Adding users to groups is a relatively expensive operation in Active Directory, and there is a limit of 5000 users per group. To work around this limit, the Commerce Server Software Development Kit (SDK) includes an object called the Subgroup Manager that enables you to store more than 5000 users in a "virtual" group, hiding the actual groups in which the users are stored. For more information, see Subgroup Manager. Since the use of this object will introduce even more overhead into an already expensive operation, it should be considered when determining the appropriate hardware for this component of your Web site.

The following table lists some of the questions that you need to answer to determine how you will best use Active Directory in your site design.

Planning question | Recommendation
What data will you store in Active Directory? | You should store only non-volatile data in Active Directory.
What volume of data will you store in Active Directory? You can include up to one million user accounts in a single Active Directory domain. This estimate is based on the following assumptions:
  • At any given time, 1 percent (10,000) of the users will be actively using the site.

  • The ratio of the number of items written to Active Directory to the number of items read from Active Directory is no more than 14 percent.

If you need to accommodate more than one million users in your Active Directory store, you can assemble multiple domains containing one million users each.

If you intend to use Active Directory for larger scale implementations, engage Microsoft Consulting Services (MCS) to assist you with planning.

See Also

Small Site Configuration With Active Directory

Setting Up Your Active Directory Servers

Migrating the Membership Directory

Example: Creating a Profile Definition with Two Data Sources


Planning for Deployment

Deploying Commerce Server 2000 and your Web site applications requires careful planning. Take the time to develop a comprehensive deployment plan so you will meet your business requirements in a timely and organized manner. Before you actually move your development applications onto a Web site, review the information presented here and in the Commerce Server 2000 Resource Kit.

More importantly, make sure your organization has developed its own plan, and that it includes input from business managers, system administrators, and site developers.

Deployment involves the movement of your Web site between three distinct hardware environments – from development, to test, to production. The following figure illustrates these environments in a simplified manner.

Development, test, and production environments
Corporate LAN
Internet
Firewall
Firewall
Production
Test
Development
ISP/ASP LAN

The actual appearance of these environments depends on the size of your site and your business goals. Commerce Server 2000 Help provides basic information about deploying a small-scale site consisting of four to six computers. Information about larger deployments is contained in the Commerce Server 2000 Resource Kit.

This section contains:

  • Small Site Configuration. Describes hardware configurations for a Web site containing four to six computers.

  • Large Site Configuration. Describes the production environment for a site containing 10 to 100 computers.

  • Global Site Configuration. Describes the concept of a production environment for a global site.

  • Firewall Configurations. Describes the advantages and disadvantages of different firewall configuration options.

See Also

Deploying Your Site

Migrating from Site Server 3.0

Migrating the Membership Directory


Small Site Configuration

Although it is possible to install all Commerce Server 2000 components on one server, a four-computer configuration is required to separate the business logic and database tiers, and to provide failure protection.

This four-computer configuration has two servers at each tier: two identical Web servers and two identical database servers. The following figure shows a four-computer production environment.

A small-scale deployment of Commerce Server 2000
Client
Corporate LAN
Database tier:
Administration
Catalog
Data Warehouse
Marketing
Profile
Transaction
Business Processing Logic:
Business Analytics
Catalog
List Manager
Pipeline components
Predictor client
Profile Service
Targeting System
NLB Cluster
Firewall
Web
Server
SQL Server
SQL Server
ISP/ASP
LAN
Web
Server
Server Cluster
Firewall
Database
Client
Internet Access

In this configuration, the Web servers are replicated by using Network Load Balancing (NLB). A single Internet Protocol (IP) address is placed in front of the Web servers to provide high availability. Both Web servers contain the Commerce Server administration tools, services, Commerce Server Business Desk, and applications. The database servers are configured as a Windows Server Cluster with a shared Microsoft SQL Server database. They contain the Administration database, the Commerce Server Data Warehouse, and the other Commerce Server databases.

Two firewalls are used in this configuration: one to secure input from the Internet, the other to secure input and output to the corporate network.

The following table lists the hardware specifications for a small configuration.

Server type | Hardware specification
Web servers | Two two-processor servers running at 400 MHz with 1 GB of RAM
Database servers | Two four-processor servers running at 500 MHz with 2 GB of RAM

This configuration uses SQL Server to authenticate users. You can also use Microsoft Active Directory to authenticate users. This provides additional security, but requires the inclusion of domain controllers in your production environment.

Small Site Configuration With Active Directory

Small Site Development Environment

Small Site Configuration With Active Directory

You may decide to use Active Directory to provide a security context for your Commerce Server site. Active Directory is useful if you need to:

  • Control access to site resources based on the security credentials of a user.

  • Provide security for other applications.

If you decide to implement Active Directory on your site, you should add two additional servers to your configuration. The following figure illustrates a small Commerce Server configuration that includes Active Directory servers.

A small-scale deployment of Commerce Server 2000 with Active Directory
Client
Corporate LAN
Database tier:
Administration
Catalog
Data Warehouse
Marketing
Profile
Transaction
Business Processing Logic:
Business Analytics
Catalog
List Manager
Pipeline components
Predictor client
Profile Service
Targeting System
NLB Cluster
Firewall
Web
Server
SQL Server
SQL Server
ISP/ASP
LAN
Web
Server
Server Cluster
Firewall
Database
Replication
Active Directory
Client
Internet Access

To provide high availability, it is a good idea to use a pair of replicated Active Directory domain controllers. Active Directory uses its own replication to ensure that its data remains consistent between domain controllers. The Web servers and database servers in this configuration are identical to those in the four-computer configuration. Because the Active Directory processing load is relatively light, you can put the Active Directory server on the same cluster as the SQL Server computers.

Small Site Development Environment

The following figure shows an example of a small site development environment.

A small-scale development environment for Commerce Server 2000
Source Repository
Legacy System
Administrator
Developer(s)
Business Manager(s)
SQL Server
Web Server
Internet

This development environment is physically separated from the staging/test and production environments. It is located inside the corporate network.


Large Site Configuration

As your capacity needs grow, you can improve site performance by doing any of the following:

  • Adding servers to your production environment

  • Upgrading existing servers

  • Improving site architecture

The following figure shows an example of a large site production environment of 10 to 100 servers.

Data Warehouse Management Tasks
Data Warehouse Storage
Data Warehouse
Profile Server Cluster
Catalog Replication System
Large site configuration

Client

NLB Cluster

Catalog Servers

Corporate LAN

NLB Cluster

Direct Mailer
Server

Marketing
Server Cluster

Business Desk
Server

Domain Controller 2

Domain Controller 1

Business processing logic:

Business Analytics
Catalog
List Manager
Pipeline components
Predictor client
Profile Service
Targeting System

Transactions
Server Cluster

Administration Server Cluster

Web Server Cluster

Active Directory

Internet
Access

This configuration separates each of the component databases onto its own Microsoft SQL Server cluster. In addition, the Catalogs database is installed over multiple load-balanced clusters. Additional Web servers are added to spread out the load on Commerce Server services and applications.

For more information about planning and deploying a large site configuration, see the Commerce Server 2000 Resource Kit.


Global Site Configuration

A global site will typically have several large sites across the world connected by a dedicated wide area network (WAN) or one or more ISPs/ASPs provided by a WAN.

The following figure shows an example of a global site configuration.

Global site configuration
Albuquerque
Sao Paulo
WAN Internet
Production
Production
Production
Test
Test
Test
Development
Development
Development
Brisbane

For more information about planning and deploying a global site configuration, see the Commerce Server 2000 Resource Kit.


Firewall Configurations

Regardless of the size of your Commerce Server 2000 configuration, you need to decide how to deploy firewalls. Additional firewalls increase your costs, but help you isolate customers, corporate employees, and sensitive data. Cost is not the only issue, however. Each firewall solution has advantages and disadvantages.

This section contains:

  • Using a Single Firewall Configuration

  • Using a Two-Firewall Configuration

  • Using a Three-Firewall Configuration


Using a Single Firewall Configuration

The least expensive option in a small site configuration is to have one firewall separate Internet browsers, your site, and your internal network. This is possible if the firewall contains three network adapters, each connected to one of the three environments.

One place you might want to use just one firewall is in your development environment. For a figure showing a single firewall configuration, see Small Site Development Environment.

Advantages of the single firewall solution include the following:

  • The ISP network (containing Web servers and database servers) is separated physically from the other networks, thereby limiting intrusions into the site. If someone is able to exploit any server that is accessible publicly, they do not have direct access to the internal network.

  • There is only one firewall to purchase and manage.

  • The internal network is not dependent upon the Web site environment to function. If the site has network problems, the internal network does not necessarily lose connectivity.

  • This design is implemented easily in an existing architecture where a firewall is already serving to separate the internal network from the Internet. You might only need to add a third network adapter to the existing firewall.

Disadvantages of the single firewall solution include the following:

  • The database servers are not separated from the Web servers. Hypertext Transfer Protocol (HTTP) and Hypertext Transfer Protocol Secure (HTTPS) are the only protocols allowed from the Internet to the Web site.

  • An intruder who gains access to a server in the ISP network might gain access to other servers on the site. Additional security is necessary to protect these servers.

  • Communication between Web servers and database servers travels unprotected within the ISP network.

  • Because Commerce Server Business Desk computers share network traffic with Web servers, you need to run HTTPS on the Business Desk computers to ensure the security of data.

  • Some firewall vendors may not support three interfaces.


Using a Two-Firewall Configuration

In this configuration, one firewall separates the Internet from the Web servers, and the second firewall separates the Web servers from the internal network, which contains the database servers and the Commerce Server Business Desk computers. For a figure showing a two-firewall configuration, see Small Site Configuration.

Advantages of the two-firewall solution include the following:

  • The system administrator is able to separate the internal network from the Web servers and Internet browsers. Site management is carried out outside the ISP network, on the internal network. The internal network becomes much more difficult for an intruder to access.

  • A layer of protection is implemented to protect the database servers from vulnerabilities that are not dependent upon the relationship between the Web servers and database servers. Such vulnerabilities can result in denial-of-service attacks.

  • The number of computers that are accessible to Internet browsers is minimized. By using two firewalls, it is more difficult to disrupt or abuse the database servers and the Business Desk server.

  • Business Desk does not have to run over the Hypertext Transfer Protocol Secure (HTTPS) protocol, because the Business Desk client and server computers are on the same network.

  • Communication between Business Desk and the database servers does not have to be encrypted because the communication never goes over a public network.

  • It is easier to prevent an Internet browser from impersonating an authorized user. For example, a Web server can be told to listen only for database server requests from one specific IP address. Because both connections are controlled with a firewall, these addresses cannot be used improperly.

  • The Web servers are separated physically from the other networks, thereby limiting intrusions into the site. If someone is able to exploit any server that is accessible publicly, they do not have direct access to the internal network.

Disadvantages of the two-firewall solution include the following:

  • It is more difficult and costly to maintain two firewalls with different configurations.

  • Communication between Web servers and database servers is unprotected within the ISP network. Additional security is needed to protect this communication.

  • The internal corporate network is dependent on the Web site to function. If the Web site has network problems, the internal network could lose connectivity. You should provide a separate network line to connect internal network computers to the Internet, bypassing the ISP network. This separate connection would bypass the firewall separating the ISP network from the internal network.

  • Any traffic that is allowed between the internal network and the Internet is also allowed between the ISP network and the Internet and between the database-server network and the Internet. The security ramifications are determined by which protocols are allowed by the default security policy of the user.


Using a Three-Firewall Configuration

This configuration is like the two-firewall configuration, with the addition of a firewall that separates the internal network from the database servers and Commerce Server Business Desk computers. For a figure showing a three-firewall configuration, see Large Site Configuration.

Advantages of the three-firewall solution include the following:

  • The Web site (Web servers, database servers, and Business Desk server) is separated physically from the other networks, providing maximum protection from intruders.

  • It is easier to prevent an Internet browser from impersonating an authorized user. For example, a Web server can be configured to fulfill requests only for database server requests from one specific IP address. Because both connections are controlled with a firewall, these addresses cannot be used improperly.

  • A layer of protection is implemented to protect the database servers from vulnerabilities that are not dependent upon the relationship between the Web servers and database servers. Such vulnerabilities can result in denial-of-service attacks.

  • Adding three firewalls minimizes the number of computers that are accessible directly through the Internet. It is more difficult to disrupt or abuse the database servers and the Business Desk server.

  • The database and Business Desk servers are protected from intruders residing in the internal network.

Disadvantages of the three-firewall solution include the following:

  • It is more difficult and costly to maintain three firewalls with different configurations.

  • Communication between Web servers and database servers is unprotected within the ISP network. Additional security is needed to protect this communication.

  • Any traffic that is allowed between the internal network and the Internet is also allowed between the ISP network and the Internet, and between the database server and the Internet. The security ramifications are determined by which protocols are allowed by the default security policy of the user.

  • This is a more difficult configuration to set up and manage.

See Also

Deploying Your Site

Migrating from Site Server 3.0

Migrating the Membership Directory


Migrating from Site Server 3.0

Commerce Server 2000 provides tools that you use to migrate your Site Server 3.0 site or your Site Server 3.0 Commerce Edition site to Commerce Server. These tools are designed for use by site developers, who can customize them to meet the migration needs of your site.

This section contains:

  • Site Server 3.0 Features that Migrate

  • Planning a Migration from Site Server to Commerce Server

  • Overview of Migration Tools

  • Overview of Migration Documentation


Site Server 3.0 Features that Migrate

Commerce Server provides a migration path for those Site Server 3.0 and Site Server 3.0, Commerce Edition (SSCE) features that were incorporated into Commerce Server.

The majority of the Site Server 3.0 features have been incorporated into Commerce Server. Some of the features, however, have been incorporated into other Microsoft products. The following tables lists the Site Server 3.0 and SSCE features that migrate, and identifies the products and features to which they have migrated.

Site Server 3.0 and Site Server 3.0, Commerce Edition (SSCE) features incorporated into Commerce Server.

Site Server 3.0 Features | Commerce Server 2000 Features
Ad Server / Ad Manager | Content Selection Framework / Campaign Manager
Analysis: Report Writer, Custom Import, Usage Import | Analysis: Reports, Custom Import, Data Warehouse, Business Analysis
Direct Mail | Direct Mail
Pipelines | Pipelines
Online Store | Catalog System
Personalization & Membership | User Profiles
Site Vocabulary | Site Terms
Rule Builder | Expression Builder
Predictor | Predictor resource
Starter Sites | Solution Sites
Transactions | Transactions
Content Deployment and Content Replication System | Commerce Server Site Packager (handles some aspects of content deployment and replication)

Site Server 3.0 and Site Server 3.0, Commerce Edition (SSCE) features incorporated into other Microsoft products.

Site Server 3.0 Features | Microsoft Products
Content Deployment and Content Replication System | Microsoft Application Center 2000 (handles some aspects of content deployment and replication)
Commerce Interchange Pipeline | Microsoft BizTalk Server 2000
Internet Locator Service (ILS) / Dynamic Directory | Microsoft Windows 2000 – Site Server ILS Services
Search: Index, Crawl, Scripts | Incorporated into Microsoft Pre-Release Product (code named "Tahoe") Beta 2
Knowledge Manager | Incorporated into Tahoe
Posting Acceptor | Microsoft WebDAV

The following Site Server 3.0 features were not incorporated into Commerce Server or other Microsoft products and are no longer supported: Publishing Wizard, Push (Active Channel Multicaster, Active Channel Server), Content Analyzer, and Tag Tool.

Note

  • Internet Information Services (IIS) has changed the default setting for response buffering in version 5.0. In version 4.0, response buffering was off by default; in 5.0, it is on by default. ASP pages that are migrated from a Site Server 3.0 Commerce Edition site to a Commerce Server 2000 site should take this into account.


Planning a Migration from Site Server to Commerce Server

There are several considerations to keep in mind when you plan the migration of your site from Site Server 3.0 Commerce Edition to Commerce Server 2000. These considerations are:

  • It is not possible to migrate to individual components of Commerce Server one at a time.

  • You must create a new site, which will be moved into production after the new site behavior, content, and data are migrated successfully.

  • Migration of site code is necessary to successfully move your SSCE site to Commerce Server.

While there are several strategies available for planning a successful migration, there are two primary strategies that you may want to consider: parallel Web farm and dual boot.

Parallel Web Farm

The parallel Web farm strategy involves running Commerce Server and Site Server side-by-side simultaneously from two different locations during the entire migration process. Building a parallel Web farm will replicate the functionality of the existing SSCE site using Commerce Server technologies. Even though migration using a parallel Web farm is resource intensive, it is the migration method that provides the best risk management for sites that are actively managing site stability risks.

Advantages of using a parallel Web farm

  • The SSCE site in production is not disturbed until the Commerce Server site is fully operational and supporting customers.

  • The new Commerce Server site can be fully tested for functionality and performance under stress of simulated user load generated by tools such as the Microsoft Web Application Stress tool.

  • Migration of site code and data can be fully tested prior to opening the site to users.

  • All operational procedures can be established and documented prior to going live on the new Commerce Server site.

Disadvantages of using a parallel Web farm

  • Resource intensive in terms of hardware, space, and network infrastructure.

Dual Boot

Using the dual boot strategy means that you will install a new instance of Microsoft Windows 2000 on your SSCE server, in a separate disk system. Once the new operating system in installed, you can install Commerce Server on the new partition. You must install Commerce Server databases on a separate server because SQL configuration for Commerce Server is different than for SSCE.

An example of a dual boot strategy

A server running SSCE might have a disk configuration as follows:

  • C drive: Operating system drive

  • D drive: IIS, SSCE, and site code drive

  • E drive: IIS and system logging drive

After implementing the dual boot strategy by adding additional disk drive(s), the disk configuration of your server may look like the following:

  • C drive: Operating system drive

  • D drive: IIS, SSCE and site code drive

  • E drive: IIS and system logging drive

  • F drive: Operating system drive (Windows 2000 installed for Commerce Server)

  • G drive: IIS, Commerce Server, and site code drive (Windows 2000 installed for Commerce Server)

  • H drive: IIS and system logging drive (Windows 2000 installed for Commerce Server)

In this example, when your server starts, it is configured to either boot on the C drive or the F drive, based on which site is to be operational.

Advantages of a dual boot strategy:

  • Reduced hardware requirements.

  • Use of existing network infrastructure.

  • Use of proven hardware that meets business needs.

Disadvantages of a dual boot strategy:

  • Only one site can be operational at a time. It can be either a SSCE site or a Commerce Server site, but not both.

  • The new Commerce Server site cannot be fully tested for functionality and performance as a whole platform unless the entire SSCE site is taken offline, and the server is booted up to the Commerce Server instance.

  • Databases will need to be migrated to a separate server prior to migration.


Overview of Migration Tools

You can customize Commerce Server migration tools to meet your needs. Source code, as well as a Software Development Kit (SDK) explaining how to customize and extend the tools are provided with Commerce Server 2000. This section provides an overview of the migration tools and how you use them.

Directory Migration Toolbox

Ad Server Migration Tool

Directory Migration Toolbox

The Directory Migration Toolbox is a set of tools and Component Object Model (COM) objects written in C++. It includes the following objects: MigrationMainObj, MigrationReadObj, MigrationWriteObj, MigrationModifyObj, and MigrationLogObj. Use these objects to migrate user data from your Membership Directory in Site Server to your Commerce Server Profiles database. The Directory Migration Toolbox includes source code so that it can be modified to suit the requirements of a given Membership Directory implementation.

The following figure provides an overview of how the migration objects work.

A figure showing an overview of how the Directory Migration tool works
Write Object
Read Object
Membership Directory
AUO/LDAP
Migration Object
Site Server
Commerce Edition
Commerce Server
Migration Request
SQL
Active Directory
User profile object

Modify
Object

A key component of the Directory Migration Toolbox is the Directory Migration tool, which performs the actual migration. The Directory Migration tool is designed to maintain a state between multiple instances of real-time mode and a single instance of batch mode implementations. This balance is to prevent race conditions between instances of the Directory Migration Tool attempting to migrate the same account. You can use the Directory Migration tool in two modes:

  • Real-time mode. Designed to migrate users as they attempt to authenticate through the Login.asp file. The normal Login.asp code is extended so that if an authentication fails due to the user profile not being in the database, the migration tool can be called to perform a "real-time" migration of the user profile to the new Profiling System in Commerce Server. Once the migration is completed successfully, the Login.asp file completes the authentication of the user and normal processing resumes.

  • Batch mode. Designed to migrate users in the Membership Directory to the Profile store used by the Commerce Server Profile service. It processes the entire list of users on a stand-alone server. Once the list is processed, the entire migration process is complete except for addressing migration failures that are logged for resolution. After you resolve the problem causing the failure, you re-submit the migration processes against the failed accounts to migrate them successfully.

Ad Server Migration Tool

The Ad Server Migration Tool is used for migration of ad data from SSCE to Commerce Server. This tool is named adservermigration.exe and it is located in the "SDK\Tools\Migration\Ad Server" folder in the Commerce Server installation folder.

The Ad Server Migration Tool creates expressions for target evaluation and moves the ads between Web sites. This tool also uses current expressions to drive the process of ad selection. For more information about the Ad Server Migration Tool see ''Migrating a Site Server 3.0 Commerce Edition Site to Commerce Server 2000" in the Microsoft Commerce Server 2000 Resource Kit.

See Also

Migrating the Membership Directory


Overview of Migration Documentation

For information about migrating the Membership Directory, see Migrating the Membership Directory.

For more information about migration, see ''Migrating a Site Server 3.0 Commerce Edition Site to Commerce Server 2000" in the Microsoft Commerce Server 2000 Resource Kit.

Pipelines

Commerce Server pipelines are compatible with Site Server 3.0 Commerce Edition (SSCE) pipelines with respect to their application programming interface (API). Third-party pipeline components used with SSCE will work with Commerce Server 2000, with the following exceptions:

  • Currency has changed to a 64-bit value (in SSCE, currency was an 32-bit integer.)

  • Address/shipping information has been changed to handle multiple "Ship To" addresses.

If your third-party components interact with pipeline data at the Dictionary object level, these changes may not affect your site. However, if your third-party components interact with any pipeline data at the database level, where the data is actually stored, your components will be affected because the database layer has changed in Commerce Server.

Catalogs

There is a significant difference between Commerce Server and SSCE catalogs. The SSCE wizard only generated a basic catalog called an online store. In contrast, catalogs created in Commerce Server are more complex and offer greater flexibility. Most customer deployments of SSCE use custom catalog solutions, which preclude development of a generic tool for migration to the Commerce Server Product Catalog System.

Before you migrate your online store or a custom catalog solution to a Commerce Server catalog, you must create a catalog for Commerce Server. In order to create a catalog for Commerce Server, you must create a catalog schema. After you create a catalog schema you create a catalog and populate it with products.

You can use the following strategies to migrate your online store or custom catalog to a Commerce Server catalog:

  • Create an XML file containing your catalog data and import it into the Commerce Server Product Catalog System. The XML file must be in a format that the Product Catalog System is capable of importing. An XML catalog file must contain the schema definition as well as the catalog data.

    Another technique for determining the precise XML format for the catalog data to be imported is to construct the desired catalog schema and populate it with several sample products. Then export this catalog as XML and study the resulting XML file. The data from your online store or custom catalog solution must conform to this format.

    For more information about the XML format expected by the Product Catalog System, see Catalog XML Structures.

    For more information about importing the XML file once you have constructed it, see Importing an XML Catalog File.

  • Create a comma-separated values (CSV) file containing your catalog data and import it into the Commerce Server Product Catalog System. The CSV file must be in a format that the Product Catalog System is capable of importing, and that is compatible with the schema you have defined for your Commerce Server catalog.

    For more information about the CSV format expected by the Product Catalog System, see Catalog XML Structures.

    For more information about the CSV format expected by the Product Catalog System, and about importing the CSV file once you have constructed it, see Importing a CSV Catalog File.

  • Create a utility script that reads the catalog structure and data from your online store or your custom catalog solution, and then use the Commerce Server catalog objects to create a Commerce Server catalog with the desired schema and populate the catalog with product data. A sample script for this scenario can be found on the Microsoft Commerce Server 2000 Resource Kit CD-ROM.

    For more information about the Commerce Server catalog objects, see Product Catalog Objects.

See Also

Creating a Catalog Schema

Creating a Catalog

Adding a Product to a Catalog


Developing Your Site

Microsoft Commerce Server 2000 provides the tools and services that enable you to develop a world-class commercial Web site more quickly and easily. This section introduces you to Commerce Server development, and provides conceptual information about the various aspects of Web site development using Commerce Server.

This section contains:

  • Introduction to Programming with Commerce Server. Describes the Web development aspects of Commerce Server.

  • Programming with Commerce Server Objects. Categorizes the Component Object Model (COM) objects provided with Commerce Server, and provides conceptual information and coding examples for those categories.

  • Working with Site Security and Filters. Describes Commerce Server mechanisms for securing your Web site.

  • Working with Pipelines. Describes Commerce Server pipelines, including where they are employed within Commerce Server, and how they can be used most effectively.

  • Integrating with BizTalk Server. Describes how Commerce Server can be integrated with Microsoft BizTalk Server to provide a comprehensive supply chain solution.

  • Customizing Style Sheets. Describes how the look of the Commerce Server Business Desk can be easily altered using its customizable style sheets.

  • Modifying Your Site for an International Audience. Describes issues related to the creation of an international Web site.

  • Migrating the Membership Directory. Explains how to migrate existing users of a Microsoft Site Server 3.0 Commerce Edition Web site to a Commerce Server 2000 Web site.


Introduction to Programming with Commerce Server

Microsoft Commerce Server 2000 requires the skills of a site developer to optimize its functionality. This section introduces developers to Commerce Server 2000 and describes the opportunities for programming that it presents.

This section contains:

  • Setting Up Your Development Workstation. Provides an overview of the hardware and software prerequisites for working with Commerce Server effectively.

  • Debugging. Provides an overview of techniques for effective debugging in the context of Commerce Server development.

  • Programming Opportunities. Describes the various aspects of Commerce Server that present opportunities for programming.

  • SDK Road Map. Provides a brief overview of the samples that are present in the Commerce Server 2000 Software Development Kit (SDK).

  • Programmer's Reference Road Map. Provides a guide to the reference material available in the Programmer's Reference section of the Commerce Server documentation.


Setting Up Your Development Workstation

The hardware requirements for setting up a Commerce Server 2000 development workstation are the same as for a production server with the exception that a development workstation with 128 MB of RAM is generally adequate. For more information, see Hardware Requirements.

Install Commerce Server on development workstations using the normal installation process. You can perform a custom installation if you want to limit how much of Commerce Server is installed.

In addition, an integrated development environment such as Microsoft Visual Studio 6.0, and specifically Microsoft Visual InterDev (VID), is recommended for the actual development and debugging work involved. Note that you must apply VID Service Pack 4 (SP4) if you choose to use VID. Other debugging tools could also prove useful. For more information, see Debugging.


Debugging

The types of bugs encountered in the course of developing Commerce Server Web sites and extending the Commerce Server platform include:

ASP errors | Generic logic problems | Memory leaks
Hangs | Disk-full situations | Network outages
Crashes | Database access issues | Security issues

It is beyond the scope of this documentation to teach you how to debug Web applications. However, the following topics direct you to sources of additional information about how to debug potential problems that may occur with your use of Commerce Server 2000.

This section contains:

  • More Information about Debugging. Describes where to find additional information about debugging Web applications.

  • Debugging Tools. Describes a number of the tools available for debugging Commerce Server applications.


More Information about Debugging

It is beyond the scope of this documentation to teach you how to debug Web applications. However, the Microsoft Developer Network (MSDN) at http://msdn.microsoft.com contains a large volume of information related to debugging. You may find the following articles instructive (search for them by title, using "Exact Phrase" as your search criteria and including both "MSDN Library" and "Web Workshop" in your search scope):

  • Microsoft Visual InterDev 6.0 Debugging

  • Debugging Distributed Web Applications

  • Debugging Applications and Components

  • Troubleshooting Components Under ASP Technology

  • Debugging ASP Applications

  • Debugging Script Objects in ASP Pages for Microsoft Visual InterDev 6.0 Developers

You can find additional information about debugging in the technical articles on the Visual InterDev Web site at http://msdn.microsoft.com/vinterdev.


Debugging Tools

One of the primary tools used to develop Microsoft Commerce Server 2000 was Microsoft Visual Studio, including Microsoft Visual InterDev, Microsoft Visual C++, and Microsoft Visual Basic. It is the recommend integrated development environment for working with Commerce Server.

The following tools may also prove useful when debugging Commerce Server:

  • Microsoft Script Debugger. Search MSDN for the title "Microsoft Script Debugger for Internet Explorer" (exact phrase search criteria).

  • IIS Exception Monitor. Search MSDN for the title "Troubleshooting with Exception Monitor" (exact phrase search criteria).

  • User Mode Process Dump. This tool is included in the Original Equipment Manufacturer (OEM) support tools. Search MSDN for "OEM Support Tools" (exact phrase search criteria).

  • WinDbg. The WinDbg files are installed when you install the developer tools included with the Platform Software Development Kit (SDK). For information on using WinDbg, see the help file windbg.hlp, which is included with WinDbg.

  • System Monitor, Performance Logs and Alerts, Event Viewer. These three Microsoft Management Console (MMC) snap-ins are included, by default, in the Commerce Server Manager MMC console. You may find them useful for debugging and performance tuning your Web site.

When debugging pipelines, you should consider turning on logging for pipeline execution to help see where failures occur.

The Order sitelet in the Commerce Server 2000 SDK includes the script file DumpOrder.vbs (in the source\pipeline sub-folder) that is designed to be used with the Scriptor pipeline component. It can be used to dump the contents of an OrderForm object at arbitrary points in the execution of the Order Processing pipeline (OPP). For more information, see the instructions at the beginning of the file DumpOrder.vbs.

See Also

Using regtrace.exe with a debugger


Programming Opportunities

You have two programming opportunities available to you through Commerce Server. You can use the existing features and capabilities of Commerce Server to build Web sites, or you can extend the Commerce Server platform.

Extending the Commerce Server platform includes creating new components and resources that are general purpose in nature. You can market these components and resources to companies that are using Commerce Server to create their Web sites.

This section contains:

  • Building Web Sites. Describes issues related to building sophisticated e-commerce Web sites.

  • Customizing and Extending Commerce Server. Describes the various ways in which Commerce Server can be customized and extended by building new components.


Building Web Sites

As a developer, you will build the Web sites that your customers will use, and through which they will ultimately make purchases. Before developing your Web site, you will need to determine where to start, and how Commerce Server can help you achieve your goal of developing a site that meets the needs of your company.

The following articles, available on the Microsoft Developer Network (MSDN) at http://msdn.microsoft.com contain useful information about Web site development (search for them by title, using "Exact Phrase" as your search criteria and including both "MSDN Library" and "Web Workshop" in your search scope):

  • Improving ASP Application Performance

  • ASP Component Guidelines

  • Load Test Your ASP Application

  • ASP Guidelines

In Web sites that run under Internet Information Services (IIS), there is a basic division between the processing that occurs when an application first begins and when a session first begins, and that which occurs as the user moves from page to page. The former type of processing is implemented in the file Global.asa, while the latter type is implemented in the various Active Server Pages (ASP) that compose the site.

This section provides guidance in choosing from where to begin your development, as well as describing some important aspects of the processing that must occur in the Global.asa file.

This section contains:

  • Choosing Where To Start. Describes various options for starting the development of a Web site based on Commerce Server.

  • The Role of the Global.asa File. Describes the role of the Global.asa file in an IIS application.


Choosing Where To Start

As the developer for your Web site, you have two choices regarding where to begin development. Your choices are:

  • You can begin with the Blank site, which, when unpacked, gives you a Web site which is essentially empty. It provides the files Default.asp and Global.asa, but they do not yet contain much in the way of content. The Blank site is included with Commerce Server 2000.

    It also provides you with Commerce Server Business Desk and the set of empty databases upon which the Web site will ultimately depend.

    If you have an existing Web site, you can convert it to take advantage of the features and functionality of Commerce Server 2000. You will still need to begin your development process by unpacking the Blank site, which makes Business Desk available for use in your converted Web site. You would then merge your existing Web site files into the Blank site, converting them as appropriate to take advantage of the features of Commerce Server 2000.

  • You can begin with one of the Solution Sites that can be downloaded from http://www.microsoft.com/commerceserver/solutionsites. Initially, there are two Solution Sites available — Retail, which can be used to create a Web site aimed at the business-to-consumer market, and Supplier, which can be used to create a Web site aimed at the business-to-business market.

    Both of these Web sites, which are based on the same code base, offer a quicker time to market than starting from scratch with the Blank site. However, since they are general purpose in nature, their design will not satisfy the requirements of all possible Web sites. In particular, Web sites that have strict and particularly demanding performance requirements, or unique architectural requirements, might be better developed from scratch.

    Further information about the Solution Sites, as well as the documentation for the Solution Sites themselves, is available on the Solution Sites Web site.


The Role of the Global.asa File

One aspect of optimizing performance is to avoid unnecessary object creation. Internet Information Service (IIS) applications help support this goal through the mechanism of the Global.asa file and the intrinsic Application object. When an IIS application starts, it runs the Global.asa file, allowing initialization code to be executed. Specifically, the Application_OnStart routine is invoked, within which all initialization code for the application can be called. It is common practice to create and initialize objects and services when the application first starts, and then store references to those objects and services within the Application object. Once this is done, any Active Server Page (ASP) in the application can access those objects and services through the Application object. Such access is often faster than creating and initializing, and then destroying, the requisite objects within each ASP page. On the other hand, there are certain classes of objects for which this is not true, and therefore not recommended.

The types of processing that typically occurs in the Global.asa file include:

  • The creation and initialization of special purpose Commerce Server objects that can then be accessed from every ASP page on the site. The MessageManager object, which provides a mechanism for accessing language-specific strings for use in language-neutral ASP pages, is a good example of this type of object. For more information about this object, see MessageManager Object.

  • The establishment of caching objects, including the CacheManager object and the LRUCache object. For conceptual information about the caching objects, see General Purpose Programming Concepts. For more information about the properties and methods of the caching objects, see CacheManager Object and LRUCache Object, respectively.

  • The establishment of global information that is specific to your Web site, or to a custom resource that you develop. A common way to do this is to place the required data into a Dictionary object that is then made accessible to ASP pages through the IIS Application object.

If you begin development using the Blank site, you will find that the Global.asa file contains very little application initialization code. It is up to you, as the Web site developer, to make appropriate decisions about which objects should be shared by all ASP pages, and thus created and initialized in the Global.asa file.

If you begin development using one of the Solution Sites that can be downloaded from http://www.microsoft.com/commerceserver/solutionsites, you will find that the Global.asa file is quite large and complex. This file contains code to create and initialize a large number of Commerce Server objects, references to which are stored in the IIS Application object. For more information, see the Solution Sites documentation, and the code and comments within the Global.asa files included with those sites.


Customizing and Extending Commerce Server

Microsoft Commerce Server 2000 was designed with extensibility in mind. There are numerous areas in which its native functionality can be enhanced and extended.

For example, you could create a Gift Certificate extension to Commerce Server that includes:

  • A new Commerce Server Business Desk module for managing outstanding gift certificates.

  • A custom resource to manage the database tables in which the gift certificate data will be stored.

  • One or more new pipeline components to allow gift certificates to be applied toward purchases.

  • New Active Server Pages (ASP) to be integrated into a Web site to offer the gift certificate functionality to users.

This section contains:

  • Writing New Pipeline Components. Describes the possibility of writing new pipeline components to modify and enhance the execution of various pipelines within Commerce Server.

  • Extending the Business Desk. Describes the possibility of adding a new module to Business Desk.

  • Adding Custom Resources. Describes the possibility of integrating a custom resource into Commerce Server, allowing it to be configured and managed within Commerce Server Manager.

  • Customizing the Data Warehouse. Describes the possibility of customizing the Data Warehouse to allow for the gathering, storage, and analysis of data beyond that for which it was originally designed.

  • Customizing the Content Selection Framework. Describes the possibility of customizing the Content Selection Framework to allow additional algorithms for choosing the content to be delivered to different users.

  • Creating Time-Saving Tools. Describes the possibility of using the COM objects supplied with Commerce Server to create tools designed to automate repetitive tasks.


Writing New Pipeline Components

A pipeline component is a Component Object Model (COM) object that supports a standard set of interfaces that can be invoked in a uniform fashion during the execution of a pipeline, and which performs a particular aspect of the processing performed by the pipeline as a whole. The pipeline architecture allows for new pipeline components to be created and "plugged into" existing pipelines, often replacing an existing pipeline component, and altering the original processing being performed by that pipeline.

A common example of this type of pipeline component replacement is the pipeline that is executed when a user decides to check out, and their shopping cart is being processed for the completion of the transaction. Commerce Server includes several pipeline components designed to calculate sales tax, though these components are only meant to demonstrate the tax stage of the purchase pipeline, and are not guaranteed to perform tax calculations in accordance with the relevant tax law. It is recommended that you use tax component software made by third parties who specialize in this type of software.

You may need to develop additional pipelines to meet your business needs. The architecture of Commerce Server pipelines makes it very easy to insert additional pipeline components into existing pipelines so that extra processing can occur.

Pipelines are used in various capacities throughout Commerce Server. They are used to process transactions, to select personalized content for display, and to process Direct Mail jobs.

Pipelines can be optimized by incorporating the use of the CacheManager object and the corresponding cache loader objects. The Content Selection Framework is a good example of this sort of optimization. For more information about using the CacheManager object, see:

  • Objects and Components of the Content Selection Framework

  • Code to Support the ContentSelection Object

  • Code to Implement Custom Cache Components

For more information about pipelines, existing pipeline components, and building new pipeline components, see:

  • Working with Pipelines

  • Pipeline Component Reference

  • Building Pipeline Components

  • Pipeline Component Interfaces


Extending the Business Desk

Commerce Server Business Desk provides a single application from which business managers can make changes to the Web site without having to go through their technical Web expert. If you add new functionality to Commerce Server that includes data that business managers could change themselves, you should consider adding a new Business Desk module as the user interface through which business managers can make those changes. Doing so will help keep those business managers more effective, allowing them to continuing working with a single, consistent tool.

Business Desk can easily be extended. You can include new modules and new categories to contain those modules. The HTML components (HTCs) that are used by the existing Business Desk modules have been written in a general purpose fashion, which allows you to create new modules that use these same mechanisms for displaying and manipulating data. Business Desk also contains an extensive collection of utility routines, shared global variables, and constants that can help you develop new Business Desk modules.

An example of the type of new module that could be developed is one for offering electronic gift certificates on the site. Business managers may want the ability to examine various data related to the gift certificate functionality. This data would include information such as how many dollars worth of gift certificates have been sold but not yet redeemed, to whom have those gift certificates been issued, how long have they been outstanding, and so on.

For more information about developing new Business Desk modules and the various ways in which the Business Desk framework supports this development, see:

  • Building Business Desk Modules

  • Business Desk Reference

  • Business Desk XML Structures


Adding Custom Resources

Within Microsoft Commerce Server 2000, a resource is defined as any service or facility available to the Web sites that has its own independent configuration data. Commerce Server Manager, which is a Microsoft Management Console (MMC) snap-in, is the user interface designed for use by system administrators to manage the configuration values for these resources. Commerce Server Manager is designed to accommodate an expanding number of resources to be managed in a single, consistent fashion.

Depending on the complexity of the configuration data involved, and the need for a custom user interface, Commerce Server Manager offers varying levels of integration with custom code. At its most simple level, adding new rows to a small number of administration database tables allows the new resource to be displayed in Commerce Server Manager and its configuration values to be edited using the Generic Resource dialog box. At its most complex, the new resource can have its own custom user interface, implemented as an MMC snap-in extension, and take full responsibility for moving its data into and out of site packages from whatever data source it happens to use.

For more information about integrating a custom resource into the existing Commerce Server Manager user interface and Commerce Server Site Packager infrastructure, see:

  • Integrating Custom Resources

  • Site Packager Interface


Customizing the Data Warehouse

Microsoft Commerce Server 2000 includes a Data Warehouse that is pre-configured with a schema designed to allow the capture, storage, and analysis of a wide range of data. Though this schema meets the needs of many Web sites, it is likely that some Web sites are going to have special data warehousing needs that are beyond the capabilities of this schema. The Commerce Server Data Warehouse has been designed so that its schema can be extended to accommodate new types of data.

For more information about extending the Data Warehouse and its schema, see:

  • Working with the Data Warehouse

  • OLE DB Provider for Commerce Server

  • Analysis/Reporting Schema

  • Data Warehouse Schema


Customizing the Content Selection Framework

The Content Selection Framework (CSF) is the sub-system that allows for the efficient selection of custom content for Web pages and Direct Mail based on a number of different, dynamic criteria. These criteria can include such facts as the identity of the user, the time of day, business needs of advertising campaigns, and so on.

Since the CSF is implemented as a Commerce Server pipeline, one of the main ways in which the CSF can be customized is through the development and use of custom pipeline components.

The Samples\Marketing\debug folder in the Commerce Server 2000 SDK contains two ASP pages that can be useful when debugging the scoring and cache loading aspects of a CSF pipeline. For more information, see Marketing Folder.

For more information about extending the Content Selection Framework, see:

  • Extending the Content Selection Framework

  • Content Selection Pipelines

  • Building Pipeline Components


Creating Time-Saving Tools

Microsoft Commerce Server 2000 includes a set of Component Object Model (COM) objects that allow easy programmatic access to much of the data associated with the Web sites being developed and deployed.

For example, there are several objects related to the Product Catalog System, which together allow sophisticated access to the product catalog data associated with the Web site. These are the objects that the corresponding Commerce Server Manager resource and Business Desk modules use to display and make changes to catalog data.

As a Commerce Server developer, it is important that you realize the potential that these objects offer in terms of the development of custom tools. Sometimes these tools will only be used for a limited time early in the development of the Web site. For example, the easiest way to initially get catalog data into Commerce Server might be to write a Microsoft Visual Basic program that reads the data from some existing database and uses Commerce Server catalog objects to write that data to a Commerce Server catalog database. If the alternative is to enter the catalog information by hand through Commerce Server Business Desk, writing a small Visual Basic program to accomplish the same task could represent a huge savings in time, effort, and accuracy.

Programmatic solutions using the COM objects supplied with Commerce Server provide you a way to build your own custom tools to make development and maintenance of your site more effective and efficient.

It is important to note the potential for the development and marketing of third party tools that are generic enough to be useful for a variety of Commerce Server Web sites.

For more information about the COM objects supplied with Commerce Server, see:

  • Programming with Commerce Server Objects

  • Object Reference


SDK Road Map

The Microsoft Commerce Server 2000 Software Development Kit (SDK) includes extensive samples and tools to help developers get started programming with Commerce Server. When installed, all of the files composing the Commerce Server 2000 SDK are in a folder called "SDK" under the "Microsoft Commerce Server" folder. This topic describes the structure and contents of the SDK folder.

Note

  • You must include the following components of the Platform SDK to build the samples in the Commerce Server 2000 SDK (choose at least these options on the Custom Installation screen of the Platform SDK installation program):

    Configuration Options (all)

    Build Environment

    Base Services (all)

    Component Services

    COM

    Data Access Services

    OLE DB

    SQL Server

    Management Services

    Microsoft Management Console

    Minimum Build Tools

    Networking and Directory Services

    Active Directory Services Interface

    Web Services

    Microsoft Internet Explorer

    Microsoft Internet Information Server

    Win32 API

    You may also want to install the following debugging tools at the same time:

    Debugging Tools

    WinDbg

    OEM Support Tools

    UserDump

    For more information, see Debugging Tools.

  • In addition to installing the Platform SDK, you must also update your system include path to contain the Commerce Server 2000 SDK include folder, and update your Microsoft Visual C++ directory options to contain the Commerce Server 2000 SDK include folder.

    Note that the installation of the Platform SDK should have added the path settings that it requires to the user INCLUDE and LIB environment variables:

    • INCLUDE: <Platform SDK folder>\Include

    • INCLUDE: <Platform SDK folder>\Include\ATL30

    • LIB: <Platform SDK folder>\Lib

    To update your user INCLUDE environment variable

    1. Right-click My Computer and select Properties.

    2. In the System Properties dialog box, click the Advanced tab.

    3. On the Advanced tab, click Environment Variables.

    4. In the Environment Variables dialog box, select the variable INCLUDE from the User variables for <username> box, and then click Edit.

    5. In the Edit User Variable dialog box, append the path to the Commerce Server 2000 SDK include directory to the value in the Variable Value box. For example:

      C:\Program Files\Microsoft Commerce Server\SDK\Include\

    6. Click OK three times to exit all three dialog boxes.

    To update Microsoft Visual C++

    1. Open Microsoft Visual C++.

    2. On the Tools menu, click Options.

    3. In the Options dialog box, select the Directories tab.

    4. Verify that the Include files option in the Show directories for box is selected.

    5. Click New, and then enter the path to the Commerce Server 2000 SDK include directory. For example:

      C:\Program Files\Microsoft Commerce Server\SDK\Include

    6. Click OK.

There are three top-level folders in the SDK folder, as follows:

  • Include Folder

  • Samples Folder

  • Tools Folder

Include Folder

The include folder contains numerous C++ header (.h extension) and Interface Definition Language (.idl extension) files that are of general use when using Commerce Server COM objects from C++, and examining the details of interface definition, respectively.

Many of the header files are referenced in the C++ version of the reference topic for the corresponding object.

Samples Folder

The Samples folder contains a number of different samples, divided into the following sub-folders:

  • Business Analytics Folder

  • Management Folder

  • Marketing Folder

  • Order Processing Folder

  • Privacy Folder

  • Sitelets Folder

  • SolutionSites Folder

Business Analytics Folder

The Business Analytics folder contains the following samples:

CreateSchemaObject.vbs

This sample demonstrates how to use the OLE DB Provider for Commerce Server to modify the Business Analytics System logical schema by adding a new class and class members, and associating it with an existing class.

This script is in the Scripts sub-folder.

To run the sample, modify the connection string on line 135 of the script to suit your environment, and uncomment the following lines:

    140 'TestBindToCls cn, "visit"  'visit is valid in DW
    142 'TestBindToMem cn , "visitNum"
    145 'TestCreateClsMem strSQLConn, strURL

DumpFacts.vbs

This sample demonstrates how to use the OLE DB Provider for Commerce Server to read the Fact Tables in the Business Analytics System.

This script is in the Scripts sub-folder.

Analysis - New dynamic OLAP report script.sql

Analysis - New dynamic SQL report script.sql

Analysis - New static OLAP report script.sql

Analysis - New static SQL report script.sql

These sample SQL scripts demonstrate how to create new reports of various types in the Business Analytics System.

These SQL scripts are in the Scripts sub-folder.

Schema Tool

The files in this sample constitute a Microsoft Visual Basic project that provides a schema browser you can use to view Commerce Server Data Warehouse classes, class properties, data members, and class relationships as they are defined in the logical schema. This sample demonstrates how to use the OLE DB Provider for Commerce Server to access the logical schema of the Data Warehouse.

Management Folder

The Management folder contains the following samples:

BizDesk

The files in this sample provide a working code base from which to develop new Commerce Server Business Desk modules. This code base demonstrates how to use XML data-islands, and includes the use of the Business Desk HTML Components (HTCs) for creating a rich, Web-based user interface to allow for non-technical administration of your Commerce Server Web site. This sample provides you with an Edit page that demonstrates the use of edit page HTCs, a List page that demonstrates the use of the list page HTC, and a response page for handling requests from the Business Desk user interface.

For more information about building Business Desk modules, see Building Business Desk Modules.

BizDesk Installer

The files in this sample constitute the C++ source code for a Component Object Model (COM) object that provides a mechanism for automating the process of adding the configuration information for a new Business Desk module to an existing Business Desk installation. For more information about the interface that this object implements, see Automating Module Installation.

PuP Resource

The files in this sample constitute the Microsoft Visual Basic source code for a COM object that implements the IPuP interface. The implementation is essentially the same as that implemented by the GenericPuP object, and can be used to package a specified set of tables from a single SQL Server database. For more information about the IPuP interface and the GenericPuP object, see Site Packager Interface and Using the GenericPuP Object, respectively.

ResourceConfig

The files in this sample constitute the Microsoft Visual Basic source code that demonstrates how to add the configuration information for a custom resource with one configuration property to the tables of the Administration database. For more information about integrating a custom resource, see Integrating Custom Resources.

Site Status

The files in this sample constitute the C++ source code of a Microsoft Management Console (MMC) extension snap-in that extends the Commerce Server Manager interface and provides the ability to open and close the Commerce Server applications into which it is installed.

When installed as a site resource, this extension snap-in retrieves the name of the site it is installed in, and then retrieves the names of all the applications installed in the site. When you choose to close the site, it queries the Internet Information Services (IIS) Metabase on each Web server hosting the site, and sets the RedirectUrl key in the Metabase to redirect all incoming requests to a page that reports the site as closed.

To install the sample into an existing site, run the InstallSiteStatus.vbs script from the command line, passing in the name of the site. For example:

    C:\>cscript InstallSiteStatus.vbs Retail

Widgets

The files in this sample constitute demonstration pages for the various HTML Components (HTCs) provided with the Business Desk Framework.

You can set an IIS virtual directory to the Widgets folder to see sample pages for all of the HTML Components (HTCs) used in Business Desk.

Marketing Folder

The Marketing folder contains the following samples:

dbscripts

The files in this sample provide SQL scripts that can be used to remove different categories of tables and related objects, as follows:

campaigns-drop.sql: Removes all tables and related objects for the Campaigns resource.

expression-store-drop.sql: Removes all tables and related objects for an Expression Store, which is normally in the same database as the Profile store.

listmanager-drop.sql: Removes all tables and related objects in a List Manager database, which is normally in the same database used by the Campaigns resource.

debug

The files in this sample provide a set of Active Server Pages (ASP) that you can include in your ASP files to dump the contents of a CSF cache and to trace the scoring logic applied for any given content request. The CSF Score Headlines sample demonstrates how to use these debugging utilities.

The ASP files in this directory are: DumpContentList.asp and TraceScores.asp.

Headlines

The files in this sample demonstrate how to extend the Targeting System using custom Content Selection Framework (CSF) Cache Loading and Scoring components. This sample shows how to target headlines to users of your site based on the age of the headline and what headlines have been seen the most. It demonstrates integration with the targeting system using both Microsoft Visual C++ and Microsoft Visual Basic.

Refer to the file Readme.txt for further instructions.

Order Processing Folder

The Order Processing folder contains the following sample:

MinMaxShip

The files in this sample are divided into three sub-folders: ATL, BizDesk, and VB. The ATL and VB folders contain files that constitute parallel implementations of the same pipeline component, known as the MinMaxShip component. The ATL folder contains the source code for an C++ Active Template Library (ATL) implementation, and the VB folder contains the source code for a Microsoft Visual Basic implementation.

The MinMaxShip pipeline component demonstrates how a new pipeline component can be added to the Order Processing pipeline, as well as demonstrating the new shipping architecture in Commerce Server.

The BizDesk folder provides a custom Commerce Server Business Desk module that allows the MinMaxShip sample to be quickly added to an existing Commerce Server Web site for use in the shipping stage of an Order Processing pipeline.

To run either implementation of the MinMaxShip sample, you must first install one of the Solution Sites that can be downloaded from http://www.microsoft.com/commerceserver/solutionsites. After you have installed one of these sites, go to the directory containing the Business Desk files, and do the following:

Copy the file MinMax_edit.asp from the MinMaxShip\BizDesk folder to the relevant Shipping folder. For example, C:\InetPub\wwwroot\RetailBizDesk\Shipping.

Copy the file shipping_methods.xml from the MinMaxShip\BizDesk folder to the Config folder. For example, C:\InetPub\wwwroot\RetailBizDesk\Config.

After the Shipping module in Business Desk is updated, you can use it to configure new shipment methods of type "MinMaxShip".

For more information about the MinMaxShip sample, see MinMaxShip Sample Pipeline Component.

Privacy Folder

The Privacy folder contains the following samples:

DeleteDetailedData.vbs

This sample demonstrates how to use the OLE DB Provider for Commerce Server to delete detailed data about a particular user from the Data Warehouse.

DisconnectDetailedData.vbs

This sample demonstrates how to use the OLE DB Provider for Commerce Server to disassociate detailed data about a particular user without deleting the data itself.

Sitelets Folder

Sitelets are small-scale Web sites that demonstrate the use of a particular Commerce Server feature in isolation from other features of Commerce Server. This allows you to more easily focus on the code required to implement that feature.

The Sitelets folder contains the following sitelets:

Ad

Demonstrates how to use the Profiling System in combination with the Targeting System to display targeted advertisements.

Auction

Demonstrates how to use the Auction object to implement Winning Bid auctions. It includes a custom Business Desk module designed for managing auctions.

Catalog

Demonstrates how to use the Product Catalog System to offer catalog browse and search functionality on your e-commerce site.

Discount

Demonstrates how to offer targeted discounts during order processing on your Web site.

Order

Demonstrates how to use Commerce Server to implement an order capture process on your Web site.

Passport

Demonstrates how to integrate Passport Single Sign-In (SSI) capability with the Profiling System. With this capability, you and your customers can benefit from the Passport SSI authentication service, while still being able to use the Profiling System for targeting users, managing user data, and so on.

Profile

Demonstrates how to use the Profiling System to register and authenticate users on your e-commerce site.

Each of the sitelet folders contains a Commerce Server Site Packager file (.pup extension) that can be unpacked to install the sitelet you want. Each folder also contains a "source" sub-folder containing the Web site files that are in the corresponding Commerce Server Site Packager file.

SolutionSites Folder

The SolutionSites folder contains the following file:

AppConsts.idl

Provides constants used by the Solution Sites.

Tools Folder

The Tools folder contains a number of different tools, divided into the following sub-folders:

  • ATL Pipe Wizard Folder

  • MembershipMigration Folder

  • Migration Folder

  • Registration Tool Folder

  • VB Pipe Wizard Folder

ATL Pipe Wizard Folder

The files in this folder constitute the source files of a tool that allows you to install a new wizard in your Microsoft Visual C++ 6.0 installation. This wizard automates the creation of Commerce Server pipeline components by creating the object definition and implementation files containing function prototypes for the interfaces required to implement a fully functional pipeline component.

In addition, this wizard creates a property page for your pipeline component. You can add controls to this property page through which users can set component properties.

You must build the ATL Pipeline Component Wizard before installing it.

For more information about using the ATL Pipeline Component Wizard, see Creating Pipeline Components Using the Active Template Library (ATL).

MembershipMigration Folder

The files in this folder constitute the source files of a tool that allows you to migrate user profiles from a Site Server 3.0 Membership Directory into a Commerce Server 2000 user Profile store.

For more information about migrating user profiles from Microsoft Site Server 3.0 Commerce Edition Web sites to Commerce Server 2000 Web sites, see Migrating the Membership Directory.

Migration Folder

The executable file in the Ad Server sub-folder is a tool that allows you to migrate campaigns from Site Server 3.0 Ad Server to the Commerce Server 2000 Content Selection Framework.

Run the tool on the command line, passing the following parameters:

1: /cs30:"Connection string to the Site Server 3.0 Commerce Edition AdServer database"
2: /cs2000:"Connection string to the Commerce Server 2000 Campaign database"
3: /exprstore:"Connection string to the Commerce Server 2000 Expression store database"
4: [/silent]   (Note that this parameter is optional)

For example:

adservermigration.exe \
/cs30:"Provider=SQLOLEDB;Data Source=Commerce30servername;Initial Catalog=Commerce30DatabaseName;User ID=SA;Password=SQLpassword" \
/cs2000:"Provider=SQLOLEDB;Data Source=Commerce2000servername;Initial Catalog=MarketingSystemDatabaseName;User ID=SA;Password=SQLpassword" \
/exprstore:"Provider=SQLOLEDB;Data Source=Commerce2000servername;Initial Catalog=ExpressionStoreDatabaseName;User ID=SA;Password=SQLPassword"

Registration Tool Folder

The files in this folder constitute the source files of a tool that helps you register pipeline components for stage affinity. It allows you to register the pipeline component on the computer on which the tool is being run and it allows you to export the data to a registry script (.reg extension) for deployment to other servers.

For more information about the pipeline component registration tool, see Using the Pipeline Component Registration Tool.

VB Pipe Wizard Folder

The files in this folder constitute the source files of a tool that allows you to install a new wizard in your Microsoft Visual Basic 6.0 installation. This wizard automates the creation of Commerce Server pipeline components by creating the object definition and implementation files containing function prototypes for the interfaces required to implement a fully functional pipeline component.

In addition, this wizard creates a property page for your pipeline component. You can add controls to this property page through which users can set component properties.

You must build the Visual Basic Pipeline Component Wizard before installing it.

Once built, register the file PipelineCompWizard.dll. Registering this DLL will cause a new project item to be installed into your Visual Basic installation. Once you have registered the DLL, open Visual Basic and select New | Project. The VB Pipeline Component Wizard will be available in the list of available projects.

For more information about the Visual Basic Pipeline Component Wizard, see Creating Pipeline Components Using Visual Basic.


Programmer's Reference Road Map

Commerce Server 2000 Help includes extensive reference material in the section entitled Programmer's Reference. This reference documentation includes the following sections:

  • Object Reference. Provides reference pages for the Component Object Model (COM) objects supplied with Commerce Server, and for each of their properties and methods.

  • Interface Reference. Provides reference pages for the COM interfaces that you can implement so that your objects can be invoked by components of Commerce Server. These include the pipeline interfaces that you implement to create your own pipeline components, and the Commerce Server Site Packager interface.

  • Pipeline Component Reference. Provides reference pages for the pipeline components supplied with Commerce Server.

  • OLE DB Provider for Commerce Server. Provides reference documentation for the OLE DB Provider for Commerce Server that provides access to the Profile System and the Data Warehouse within Commerce Server.

  • Business Desk Reference. Provides reference pages for Commerce Server Business Desk. Specifically, these reference pages present the details of the events, properties, and methods of the HTML Components (HTCs), as well as details about the constants, global variables and utility routines provided by the Business Desk Framework.

  • XML Reference. Provides reference material regarding the structure of various Extensible Markup Language (XML) documents used throughout Commerce Server.

  • Schema Reference. Provides reference material about the database schema used in certain key areas of Commerce Server where detailed knowledge of the schema is important.

  • Database Table Reference. Provides information about a number of Commerce Server databases and the tables they contain. This information can be useful when establishing SQL replication.

  • Style Sheet Reference. Provides information about the Customizable Style Sheets (CSS) used by Business Desk.


Programming with Commerce Server Objects

The Component Object Model (COM) objects supplied with Microsoft Commerce Server 2000 can be divided into the following functional categories. Each functional category has corresponding conceptual information and code examples. Each COM object has corresponding reference pages for access from Microsoft Visual Basic and from C++.

The following table provides links to the relevant conceptual information for each category and to the reference pages for each COM object.

Functional Category | Description
Backward Compatibility Objects | Includes objects used for Site Server 3.0 Commerce Edition compatibility. Objects (and reference page links): AdminSite (VB/C++), StandardSManager (VB/C++), Page (VB/C++)
Business Process Objects | Includes objects used for standard business processing, such as orders, shipping, and auctions. Objects (and reference page links): Auction (VB/C++), OrderForm (VB/C++), OrderGroup (VB/C++), OrderGroupManager (VB/C++), Shipping (VB/C++), ShippingMethodManager (VB/C++), SimpleFindResultInfo (VB/C++), SimpleFindSearchInfo (VB/C++)
Configuration Objects | Includes objects used to manage the configuration of Commerce Server Web sites. Objects (and reference page links): AdminWebServer (VB/C++), AppConfig (VB/C++), GlobalConfig (VB/C++), SiteConfig (VB/C++), SiteConfigReadOnly (VB/C++)
Content Selection Objects | Includes objects used to select dynamic content for display. Objects (and reference page links): ContentList (VB/C++), ContentListFactory (VB/C++), ContentListSchema (VB/C++), ContentSelector (VB/C++), RowCollection (VB/C++)
Display Objects | Includes objects used to format data for display on Web pages. Objects (and reference page links): AppFrameWork (VB/C++), DataFunctions (VB/C++), EuroDisplay (VB/C++), MessageManager (VB/C++)
Expression Objects | Includes objects used to create, store, and evaluate expressions. Objects (and reference page links): ExpressionEval (VB/C++), ExpressionStore (VB/C++), ExprEvalContext (VB/C++), ExprFltrQueryBldr (VB/C++)
General Purpose Objects | Includes general-purpose objects used widely within Commerce Server Web sites. Objects (and reference page links): AdminEventLog (VB/C++), AdminFiles (VB/C++), CacheManager (VB/C++), DBStorage (VB/C++), Dictionary (VB/C++), DictionaryXMLTransforms (VB/C++), GenID (VB/C++), LRUCache (VB/C++), SimpleList (VB/C++)
List Management Objects | Includes the Commerce Server object related to list management. Object (and reference page links): ListManager (VB/C++)
Pipeline Objects | Includes objects used to run one or more pipeline components within the context of a Commerce Server pipeline. Objects (and reference page links): MicroPipe (VB/C++), MtsPipeline (VB/C++), MtsTxPipeline (VB/C++), OrderPipeline (VB/C++), PooledPipeline (VB/C++), PooledTxPipeline (VB/C++)
Prediction Objects | Includes objects used to make predictions. Objects (and reference page links): PredictorClient (VB/C++), PredictorServiceAdmin (VB/C++), PredictorServiceSiteAdmin (VB/C++), PredModelBuilder (VB/C++)
Product Catalog Objects | Includes objects used to manage product catalogs. Objects (and reference page links): CatalogManager (VB/C++), CatalogSets (VB/C++), CatalogToVendorAssociation (VB/C++), Category (VB/C++), Product (VB/C++), ProductCatalog (VB/C++)
Profile Objects | Includes objects used to manage profiles. Objects (and reference page links): ProfileObject (VB/C++), ProfileService (VB/C++)
Reporting Objects (Refer directly to the reference pages for more details.) | Includes the objects used to create reports. Objects (and reference page links): AsyncRpt (VB/C++), ReportRenderer (VB/C++)
Site Security Objects | Includes objects used to secure Commerce Server Web sites. Objects (and reference page links): BizDeskSecurity (VB/C++), AuthManager (VB/C++)


Backward Compatibility Objects

The backward compatibility objects are used to gain access to site configuration values, to create and retrieve shopper IDs, and to simplify forms processing in Site Server 3.0 Commerce Edition sites.

Important

  • These object are included for backward compatibility with Site Server 3.0 Commerce Edition, and will not be supported in future releases of Commerce Server.

This section contains:

  • Backward Compatibility Programming Concepts. Describes the major issues relating to the use of the backward compatibility objects.

See Also

AdminSite Object

StandardSManager Object

Page Object


Backward Compatibility Programming Concepts

The following topics contain descriptions for the objects that are considered backward compatibility objects.

AdminSite Object

StandardSManager Object

Page Object

AdminSite Object

Use this object to gain centralized access to the Site Server 3.0 Commerce Edition site configuration, so that you can configure and maintain the site.

This object provides read/write access to the configuration properties and has many functions that allow administration of Site Server 3.0 Commerce Edition sites.

Note:

  • You cannot use this object with Commerce Server 2000 sites. It is included only for backwards compatibility with Site Server 3.0 Commerce Edition.

See Also

Configuration Objects

StandardSManager Object

Use this object to facilitate the run-time creation and retrieval of shopper IDs.

Note

  • This object is included only for purposes of backward compatibility with Site Server 3.0 Commerce Edition; it has been replaced by the AuthManager object.

See Also

AuthManager Object

Page Object

Use this object to simplify forms processing in Active Server Pages (ASP).

The Page object methods fall into the following categories:

  • Formatting methods. These methods include Encode, Option, and Check. These methods make it possible for you to easily format HTML page items, and where applicable, to determine HTML item values based on a run-time evaluation of other variables used in your page.

  • Validation methods. These methods begin with Request. They are used to retrieve values from a URL query string, convert the values to given data types based on a locale value, and then validate these values against a specified range.

For more information, see the AuthManager and AppFrameWork objects, which provide similar functionality to many of the methods in this object.


Business Process Objects

Business process objects provide the ability to manage baskets, templates, and submitted orders. Typical management functions include order creation, database order storage, and database order searches.

This section contains:

  • Business Process Programming Concepts. Describes concepts related to programming with the various objects concerned with business processing.

  • Example Code for Business Process Objects. Provides example code for the business process objects.


Business Process Programming Concepts

The following topics describe the business process objects provided in Commerce Server 2000.

OrderGroup, OrderForm, and OrderGroupManager Objects

The OrderGroup object is used in Commerce Server 2000 to store, access, and compute basket and order information for a site. The OrderGroupManager object works in conjunction with the OrderGroup object, providing search and other management operations for orders.

OrderGroup Structure

OrderGroup and Component Objects
OrderForm
Object
LineItem
Dictionary
One to One
One to Many
Addresses
Dictionary
OrderGroup
Object

An OrderGroup object describes order information. It groups order forms, and provides aggregate operations and aggregate totals. The OrderGroup object links to one or more OrderForm objects, and one or more Address dictionaries. The OrderForm object specifies header information for an order such as the shipping total, the tax total, and other data required to process the order. The OrderForm object references one or more Item dictionaries, which describe the specific products to be purchased. The Addresses dictionary specifies billing and shipping address information for purchase orders. Each OrderForm object typically specifies a billing_address_id value, and each line item specifies a shipping_address_id value.

The OrderGroup object often contains just one OrderForm object, but when you want your users to purchase items from different suppliers, the multiple OrderForm object feature of the OrderGroup object enables you to retain distinctions between suppliers while allowing a unified shopping experience to the user.

This following objects commonly occur within the OrderGroup object:

  • Address Dictionaries. These dictionaries specify billing and shipping information for purchase orders.

  • OrderForm Objects. These objects specify the header information for an order form. An OrderForm object contains a SimpleList object called Items that contains the Item dictionaries holding line item information.

  • Items SimpleLists.The Items SimpleLists contain the Item dictionaries.

  • Item Dictionaries. These dictionaries specify the contents of the line items in an order form. An OrderForm object, representing the information used to process the order form, references zero or more Item dictionaries through the Items list.

OrderStatus Codes

The OrderGroup object represents a purchasing unit, and has a specific status. This status is stored in OrderGroup.value("order_status_code"), indicating whether the OrderGroup object represents a Basket (1), a Saved Order or Template(2), a New Order (4), and so on. New custom status codes can be created in Commerce Server Business Desk. They can indicate such OrderGroup object status values as Approved, Cancelled, and so on. The status codes for these values must be set to numbers that are powers of 2 (for example: 8, 16, 32). The following Order Status codes are defined:

  • Basket Status. The Basket status indicates an OrderGroup object that is in the process of being assembled and reviewed before the order is submitted. This status code is 1.

  • Template Status (Saved Order Status). The purpose of the Template status is to facilitate repeat purchases, such as in a grocery store site where the same items are ordered week after week. This status is equivalent to the Saved Order status. This status code is 2.

  • New Order Status. The New Order status indicates an order that has been submitted for further processing (usually by the user clicking the Submit Order button). This status code is 4.

Database Persistence

If the OrderGroup object has an Order Status code of Basket or Template, the entire structure is persisted in the BasketGroup table; persistence in one table enhances performance. If the OrderGroup object has an Order Status code other than Basket or Template, it is persisted in the OrderGroup, OrderFormHeader, OrderFormLineItems, and OrderGroupAddresses tables that are used to store OrderGroups, OrderForms, LineItems and Addresses, respectively. This multiple-table persistence provides the OrderGroupManager object with richer search capabilities.

The OrderGroup object uses the marshaled_data database column to persist key/value pairs that have keys that do not correspond to database column names.

No dictionary entry that has a key name that begins with the value of the SavePrefix property will be saved to the database.

Many pipeline keys are prefixed by the underscore character (_), which, by default, means they will not be persisted to the database. Occasionally, you may want to take snapshots of these keys, and by convention, the prefix "saved_" is used in this situation. By using the "saved_" prefix the pipeline keys can be referred to later and can be searched via SQL statements or the OrderGroupManager object. Copied keys should not necessarily be trusted as being up-to-date. Also, copied keys should not be used by pipeline components directly.


Example Code for Business Process Objects

This section provides examples of how to use business process objects. The code samples in this section are written as Active Server Pages (ASP); they do not show extensive error checking or certain other formalities required for functional code.

This section contains:

  • Code to Create an Order. Describes how to create an order, instantiating and initializing the required objects.

  • Code to Add Address and Line Item Information to an Order. Describes how to create line items in an order and view the contents of the order.

  • Code to Save an Order to the Database. Describes how to save an order with a Template status to the database.

  • Code to Search for Orders and Display Line Item Information. Describes how to search the database for an order using the SimpleFindSearchInfo and SimpleFindResultInfo objects.


Code to Create an Order

The following Active Server Pages (ASP) code creates an OrderForm object, an OrderGroup object, and an OrderGroupManager object. All of these objects are required in order to manipulate orders.

  1. Create the OrderGroupManager, OrderGroup, and OrderForm objects.
    Dim oOrderForm, oOrderGroup, oOGMgr, sUserID
Set oOrderForm = Server.CreateObject("Commerce.OrderForm")
Set oOrderGroup = Server.CreateObject("Commerce.OrderGroup")
Set oOGMgr = Server.CreateObject("Commerce.OrderGroupManager")
  2. Initialize the OrderGroup and OrderGroupManager objects. Note that in the following example, the connection strings have been formatted for better display.
    sUserID = "AAAABB4C-C33E-11D0-B8A0-A0C04FB616C7"

oOrderGroup.Initialize "Provider=SQLOLEDB.1;User ID=sa;Password=;
                              InitialCatalog=""Retail_commerce"";
                                            DataSource=TESTMACH2;
                                       Network Library=dbmssocn",
                                                          sUserID

oOGMgr.Initialize "Provider=SQLOLEDB.1;User ID=sa;Password=;
                         InitialCatalog=""Retail_commerce"";
                                       DataSource=TESTMACH2;
                                   Network Library=dbmssocn"


Code to Add Address and Line Item Information to an Order

The OrderGroup object links to one or more OrderForm objects, and one or more Address dictionaries. The OrderForm object references zero or more Item dictionaries through the Items list.

  1. Create the Addresses dictionary object.
    Set oOrderForm.Addresses = Server.CreateObject("Commerce.Dictionary")
  2. Create two addresses, and add them to the order form.
    Set oOrderForm.Addresses.HomeSweetHome = _
    Server.CreateObject("Commerce.Dictionary")
oOrderForm.Addresses.HomeSweetHome.ship_to_state = "WA"
oOrderForm.Addresses.HomeSweetHome.ship_to_country = "USA"

Set oOrderForm.Addresses.HomeInTheRockies = _
    Server.CreateObject("Commerce.Dictionary")
oOrderForm.Addresses.HomeInTheRockies.ship_to_state = "WY"
oOrderForm.Addresses.HomeInTheRockies.ship_to_country = "USA"
  3. Create the order form Items SimpleList object. Add four line item dictionaries to the SimpleList object, providing line item information for several dictionary elements.
    Set oOrderForm.Items = Server.CreateObject("Commerce.SimpleList")

Call oOrderForm.Items.Add( Server.CreateObject("Commerce.Dictionary"))
oOrderForm.Items(0).shipping_address_id = "test_ship_add_id1"
oOrderForm.Items(0).tax_id = "test_tax_id_string"
oOrderForm.Items(0).Value("_cy_oadjust_adjustedprice") = 100
oOrderForm.Items(0).Value("quantity") = 1

Call oOrderForm.Items.Add( Server.CreateObject("Commerce.Dictionary"))
oOrderForm.Items(1).shipping_address_id = "test_ship_add_id2"
oOrderForm.Items(1).tax_id = "test_tax_id_string2"
oOrderForm.Items(1).Value("_cy_oadjust_adjustedprice") = 200
oOrderForm.Items(1).Value("quantity") = 1

Call oOrderForm.Items.Add( Server.CreateObject("Commerce.Dictionary"))
oOrderForm.Items(2).shipping_address_id = "test_ship_add_id3"
oOrderForm.Items(2).tax_id = "test_tax_id_string3"
oOrderForm.Items(2).Value("_cy_oadjust_adjustedprice") = 100
oOrderForm.Items(2).Value("quantity") = 1

Call oOrderForm.Items.Add( Server.CreateObject("Commerce.Dictionary"))
oOrderForm.Items(3).shipping_address_id = "ship_add_id4"
oOrderForm.Items(3).tax_id = "test_tax_id_string4"
oOrderForm.Items(3).Value("_cy_oadjust_adjustedprice") = 300
oOrderForm.Items(3).Value("quantity") = 1
  4. Add the OrderForm object to the OrderGroup object.
    oOrderGroup.AddOrderform oOrderForm
  5. View the contents of one of the previously created items.
    Dim Item, itemVal
Set Item = oOrderGroup.GetItemInfo(1)
itemVal = Item.Value("_cy_oadjust_adjustedprice")
If Item.Value("_cy_oadjust_adjustedprice") <> 100 Then
    Response.Write "error in _cy_oadjust_adjustedprice"
Else
    Response.Write "correct _cy_oadjust_adjustedprice:" _
                   & itemVal & "<br>"
End If


Code to Save an Order to the Database

An order can be saved with the status of Basket, Order, Template, or a custom status. In this example, the order is saved to the database with a Template (Saved Order) status. The OrderGroup object is set to Nothing, in order to re-use the variable later in other examples.

This example code requires that you have already created the order and added items to it. For more information about creating an order, see Code to Create an Order. For more information about adding items to the order, see Code to Add Address and Line Item Information to an Order.

Dim ReqID
ReqID = oOrderGroup.SaveAsTemplate()
' Set object to Nothing in order to re-use
Set oOrderGroup = Nothing


Code to Search for an Order and Display Line Item Information

After an order has been saved to the database, you can search for it based on a variety of criteria. In this example, the OrderGroupID will serve as the basis for the search.

This example code requires that you have already saved the order to the database as a template as is described in Code to Save an Order to the Database. Note that in the following example, the connection strings have been formatted for better display.

  1. Create and initialize the OrderGroup object.
    Dim oOrderGroup
Set oOrderGroup = Server.CreateObject("Commerce.OrderGroup")
oOrderGroup.Initialize "Provider=SQLOLEDB.1;User ID=sa;Password=;
                             Initial Catalog=""Retail_commerce"";
                                            DataSource=TESTMACH2;
                                       Network Library=dbmssocn",
                                                          sUserID
  2. Create the SimpleFindSearchInfo object and set it to search for a known OrderGroupID.
    Dim oSFSearch, sReqID
Set oSFSearch = Server.CreateObject("Commerce.SimpleFindSearchInfo")
sReqID ="754C40C6-EAA9-454C-A8AB-02789FBE0FB9"
oSFSearch.ordergroup_id = sReqID
  3. Create the SimpleFindResultInfo object and set it to return data from the OrderGroup, OrderFormHeader, and OrderFormLineItems tables. Setting the JoinLineItemInfo property to True will cause the returned result set to include data from the OrderFormLineItems table. Setting the JoinOrderFormInfo property to True will cause the returned result set to include data from the OrderFormHeader table.
    Dim oSFResult
Set osfResult =Server.CreateObject("Commerce.SimpleFindResultInfo")
oSFResult.JoinLineItemInfo = True
oSFResult.JoinOrderFormInfo = True
  4. Create a recordset to hold the search results.
    Dim oRSResults
Set oRSResults=Server.CreateObject("ADODB.Recordset")
  5. Execute the search using the OrderGroupManager.SimpleFind method. The parameters for this method are the SimpleFindSearchInfo and SimpleFindResultInfo objects. Write the success status of the search to the screen.
    Set oRSResults= oOGMgr.SimpleFind(oSFSearch, oSFResult)
If err.number <> 0 Then
    Response.Write "Search error"
Else
    Response.Write "Successful Search" & "<br>"
End If
  6. Iterate through the recordset, writing the OrderGroupID and the quantity ordered for each line item to the screen.
    While Not oRSResults.EOF
    vtDisplay = "OrderGroup ID = " & oRSResults("ordergroup_id") _
                & "<br>"
    Response.Write vtDisplay
    vtDisplay = "Quantity = " & oRSResults("quantity") _
                & "<br>" & "<br>"
    Response.Write vtDisplay
    oRSResults.MoveNext
WEnd


Configuration Objects

The configuration objects perform a variety of functions, such as creating a site, creating resources, importing and exporting resources, manipulating configuration settings on site resources and global resources, and retrieving Web site properties.

This section contains:

  • Configuration Programming Concepts Describes the major issues relating to the use of configuration objects.

  • Example Code for Configuration Objects Provides detailed examples of how to use the configuration objects.

See Also

AppConfig Object

GlobalConfig Object

SiteConfig Object

SiteConfigReadOnly Object

AdminWebServer Object


Configuration Programming Concepts

The following topics describe the configuration objects in Commerce Server and how to use them.

AppConfig Object

GlobalConfig Object

SiteConfig and SiteConfigReadOnly Objects

AdminWebServer Object

AppConfig Object

The most important function of the AppConfig object is to retrieve site configuration properties, such as i_FormLoginTimeOut, i_SitePrivacyOptions, various database connection strings, and so on. The GetOptionsDictionary method of the AppConfig object performs this function; however, before using this method, the AppConfig object must be initialized.

Many of the properties that the GetOptionsDictionary method retrieves can be viewed using Commerce Server Manager in the Microsoft Management Console (MMC). The App Default Config node, in the Site Resources folder of the site, in Commerce Server Manager displays the current setting values.

The following table lists the names of the keys in the dictionary returned by the GetOptionsDictionary method of the AppConfig object that are mapped in the App Default Config node in Commerce Server Manager.

Programmatic Name | Commerce Server Manager App Default Config Mapping
f_AltCurrencyConversionRate | Currency: Alternate currency conversion rate
i_AddItemRedirectOptions | Add item redirect options
i_AddressBookOptions | Address Book Options
i_AltCurrencyLocale | Currency: Alternate currency locale
i_AltCurrencyOptions | Currency: Alternate currency options
i_BaseCurrencyLocale | Currency: Base currency locale
i_BillingOptions | Payment options: Billing options
i_BizTalkOptions | BizTalk Options
i_CookiePathCorrectionOptions | Cookie Path Correction Options
i_CurrencyDisplayOrderOptions | Currency: Currency display order options
i_DelegatedAdminOptions | Delegated admin options
i_FormLoginOptions | Form login options
i_FormLoginTimeOut | AuthManager Auth Ticket Timeout
i_HostNameCorrectionOptions | Host Name Correction Options
i_PaymentOptions | Payment options
i_SiteDefaultLocale | Site default locale
i_SitePrivacyOptions | Site privacy options
i_SiteRegistrationOptions | Site registration options
i_SiteTicketOptions | Site ticket options
s_AltCurrencySymbol | Currency: Alternate currency symbol
s_BaseCurrencySymbol | Currency: Base currency symbol
S_BizTalkCatalogDocType | BizTalk Catalog Doc Type
S_BizTalkOrderDocType | BizTalk PO Doc Type
S_BizTalkSourceQualifierID | BizTalk Source Org Qualifier
s_BizTalkSourceQualifierValue | BizTalk Org Qualifier Value
s_BizTalkSubmittypeQueue | BizTalk Submit type
s_PageEncodingCharset | Page encoding charset
s_SMTPServerName | SMTP server name
s_WeightMeasure | Unit of Measure for Weight
s_BizTalkConnString | BizTalk Interchange Manager Database

The following table lists keys in the dictionary returned by the AppConfig.GetOptionsDictionary method which are not mapped in the App Default Config node in Commerce Server Manager.

Programmatic Name | Value or Description
s_CommerceProviderConnectionString | Biz Data Service: s_CommerceProviderConnectionString
s_ProfileServiceConnectionString | Biz Data Service: s_ProfileServiceConnectionString
s_CatalogConnectionString | Product Catalog: connstr_db_Catalog
s_TransactionConfigConnectionString | Transaction Config: connstr_db_TransactionConfig
s_TransactionsConnectionString | Transactions: connstr_db_Transactions
s_BizDataStoreConnectionString | Biz Data Service: s_BizDataStoreConnectionString
s_CampaignsConnectionString | Campaigns: connstr_db_Campaigns
i_IsFullTextSearchInstalled | Indicates whether SQL Server has full text search enabled
s_SiteName | Name of the site
s_NonSecureHostname | This value is set in the Global.asa file to the non-secure host name of the application.
s_SecureHostname | This value is set in the Global.asa file to the secure host name of the application.

GlobalConfig Object

The GlobalConfig object contains two groups of methods. The first group includes such methods as the MakeArrayFromSimpleList method; their function is obvious from the method name, and will not be discussed here. For more information about these methods, see GlobalConfig Object. The second group of methods is used to create sites and manipulate configuration data at the global level.

SiteConfig and SiteConfigReadOnly Objects

The SiteConfig object contains two groups of methods. The first group includes such methods as the MakeArrayFromString method; their function is obvious from the method name, and will not be discussed here. For more information about these methods, see SiteConfig Object. The second group of methods is used to create site-level resources, manipulate configuration data at the site level, and import and export site-level resources.

The SiteConfigReadOnly object allows access to more configuration data than does the SiteConfig object. With the SiteConfigReadOnly object, group resource values are returned when you access references to resources. In contrast, the SiteConfig object only returns references to the names of the resources.

The following is a list of schema class names which are used by the CreateComponentConfig method of the SiteConfig object in creating resources.

Admin Database Class Name | Resource Name Used to Reference Resource in Code
MSCS_Catalog | Product Catalog
MSCS_AppConfigDefault | App Default Config
MSCS_TransactionConfig | Transaction Config
MSCS_Transactions | Transactions
MSCS_Campaigns | Campaigns
MSCS_AuthManager | Site CS Authentication
MSCS_DirectMailer | Direct Mail
MSCS_Predictor | Predictor
MSCS_Datawarehouse_Group | Global Data Warehouse
MSCS_Datawarehouse_Site | Site Data Warehouse
MSCS_BizDataStore | Profile Service
MSCS_Address | IIS Applications (for example, Retail or RetailBizDesk)
MSCS_UPMDtsTask | Profiling System DTS Task Information

AdminWebServer Object

The AdminWebServer object is used to enumerate the Web sites on a server and display the properties of those sites.

Active Server Page (ASP) scripts that access the Microsoft Internet Information Services (IIS) metabase require administrator privileges on the computer on which IIS is running. When you execute these scripts from a remote computer, you must connect through a secure connection, such as the Microsoft Windows NT Challenge/Response Authentication method. It is suggested that you create a server or directory for your administrative .asp files and set the directory security authentication method to Windows NT Challenge/Response for the server or directory.


Example Code for Configuration Objects

This section provides detailed examples of how to use the configuration objects.

This section contains:

  • Code to Dump Configuration Values. Describes how to use the AppConfig object to retrieve site configuration values.

  • Code to Create a Site. Describes how to create a site.

  • Code to Create and Manipulate a Global Resource. Describes how to create and manipulate a global resource.

  • Code to Create and Manipulate a Site-Level Resource . Describes how to create and manipulate a site-level resource.

  • Code to Export a Resource. Describes how to export a resource.

  • Code to Import a Resource. Describes how to import a resource.

  • Code to Retrieve Web Site Properties. Describes how to read the contents of a server-side file and write those contents to the browser.


Code to Dump Configuration Values

In this example, an instance of the AppConfig object is instantiated, then initialized to the name of the installed site (in this case, "Retail"). The GetOptionsDictionary method is called, and each key/value pair in the dictionary is written to the Web page.

The ASP example code follows.

  1. Create the AppConfig object instance and initialize it to the name of the installed site. In this example, a site named "Retail" already exists.
    Dim MSCSAppConfig
Set MSCSAppConfig = Server.CreateObject("Commerce.AppConfig")
MSCSAppConfig.Initialize("Retail")
  2. Create a dictionary object to hold the return value of the GetOptionsDictionary method, and dump the dictionary contents to the Web page.
    Dim dConfig
set dConfig = MSCSAppConfig.GetOptionsDictionary("")
For Each sKey in dictConfig
    Response.Write sKey & " = " & dConfig.Value(sKey) & "<br>"
Next


Code to Create a Site

In this example, an instance of the GlobalConfig object is instantiated, then initialized. An application named "NewSite" is created and saved.

Create this example using the following Visual Basic code.

  1. Create the GlobalConfig and initialize it.
    Dim oGlobConfig
Set oGlobConfig = CreateObject("Commerce.GlobalConfig")
oGlobConfig.Initialize
  2. Create a new application. The CreateSiteConfig method creates a site named "NewSite" and returns a SiteConfig object that contains the site configuration settings. After the site is created, save the configuration settings.
    Dim oSiteConfig
Set oSiteConfig = oGlobConfig.CreateSiteConfig("NewSite")
oGlobConfig.SaveConfig


Code to Create and Manipulate a Global Resource

In this example, a global resource is created for the site created in Code to Create a Site. Resource settings are retrieved, changed, retrieved again, and written to the screen. Create the example using the following Visual Basic code.

  1. Create the global resource. The schema class name is "MSCS_Predictor", as this example is creating a Predictor resource. After the resource is created, save the configuration settings.
    Dim oPredictor
oGlobConfig.CreateServiceConfig "oPredictor", "MSCS_Predictor"
oGlobConfig.SaveConfig
  2. Retrieve and change a property in the Predictor resource at the global level. This property, on creation, defaults to True. It will be retrieved, displayed, set to False, retrieved, and displayed again.
    Dim x, y
Set x = oGlobConfig.Fields("oPredictor").Value
y = x.Fields("f_UseExternalDB").Value
MsgBox y, , "f_UseExternalDB value before change"

' Assign a new property value
y = False
x.Fields("f_UseExternalDB").Value = y
' Save the settings
oGlobConfig.SaveConfig
Set x = oGlobConfig.Fields("oPredictor").Value
y = x.Fields("f_UseExternalDB").Value
MsgBox y, , "f_UseExternalDB value after change"


Code to Create and Manipulate a Site-Level Resource

In this example, a site-level resource is created for the site created in Code to Create a Site. Resource settings are retrieved, changed, retrieved again, and written to the screen. Create the example using the following Visual Basic code.

  1. Create the site-level resource to the site named "NewSite". The schema class name is "MSCS_Predictor", as this example is creating a Predictor resource. After the resource is created, save the configuration settings.
    Dim oPredictorAtSiteLevel
oSiteConfig.CreateComponentConfig "oPredictorAtSiteLevel", _
    "MSCS_Predictor"
  2. Retrieve and change a property in the Predictor resource at the site level. This property, on creation, defaults to True. It will be retrieved, displayed, set to False, retrieved, and displayed again.
    Dim x, y
Set x = oSiteConfig.Fields("oPredictorAtSiteLevel").Value
y = x.Fields("f_UseExternalDB").Value
MsgBox y, , "f_UseExternalDB value before change"
' Assign a new property value
y = False
x.Fields("f_UseExternalDB").Value = y
' Save the settings
'oSiteConfig.SaveConfig
Set x = oSiteConfig.Fields("oPredictorAtSiteLevel").Value
y = x.Fields("f_UseExternalDB").Value
MsgBox y, , "f_UseExternalDB value after change"


Code to Export a Resource

In this example, the site-level resource that was created in Code to Create and Manipulate a Site-Level Resource is exported to the file C:\temp\ExportedFile.txt. The resource is then deleted, and the deletion operation results are saved.

  1. Export the site-level Predictor resource to the file C:\ExportedFile.txt
    oSiteConfig.ExportResource "oPredictorAtSiteLevel", _
    "c:\ExportedFile.txt"
  2. Delete the site level Predictor resource and save the deletion operation results.
    oSiteConfig.DeleteComponentConfig "oPredictorAtSiteLevel"
oSiteConfig.SaveConfig


Code to Import a Resource

In this example, the site-level Predictor resource that was exported in Code to Export a Resource is now imported. The code tests that it exists by displaying a resource property.

oSiteConfig.ImportResource "c:\ExportedFile.txt"
Set x = oSiteConfig.Fields("oPredictorAtSiteLevel").Value
y = x.Fields("f_UseExternalDB").Value
MsgBox y, , "f_UseExternalDB value after import"


Code to Retrieve Web Site Properties

The following example enumerates all the Web sites on a server, then for each Web site, it obtains the site properties and displays the VrPath property. Create the example using the following Visual Basic code.

  1. Create the required objects.
    Dim oWebServer, WebSites, oDict
Set oWebServer = CreateObject("Commerce.AdminWebServer")
  2. Call the GetWebSites method of the AdminWebServer object instance. The method returns an array of integers representing all server instances.
    WebSites = oWebServer.GetWebSites
  3. Return the WebInstance properties in a dictionary, then display the dictionary values.
    For WebInstance = (LBound(WebSites, 1) + 1) To (UBound(WebSites, 1) + 1)
    Set oDict = oWebServer.GetWebSiteProperties(WebInstance)
    Dim ArrStr(100), i
    i = 1
    For Each property In oDict
    ArrStr(i) = property & " = " & oDict.Value(property)
        str1 = str1 & ArrStr(i) & vbCrLf
        i = i + 1
    Next
    MsgBox str1
    str1 = ""
Next


Content Selection Objects

The content selection objects are used to select custom content for display on Web pages and are part of the Content Selection Framework (CSF). Although the CSF uses many different objects to select content, such as the ContentList object, the ContentListFactory object, and the CacheManager object, this section focuses on the ContentSelector object, which is the main object used to get and display targeted content. The ContentSelector object invokes different CSF pipelines to select different types of content based on the dictionary passed to the GetContent method.

This section contains:

  • Content Selection Programming Concepts. Describes the concepts related to programming with the Content Selection objects.

  • Example Code for the ContentSelector Object. Provides example code for the ContentSelector object.


Content Selection Programming Concepts

The ContentSelector object is used to invoke Content Selection Framework (CSF) pipelines to display dynamic, targeted content on a Web page. The ContentSelector object is a property bag that inherits the properties and methods of the Dictionary object and adds the GetContent method. The dictionary object passed to the GetContent method, the global Context dictionary for the CSF application, is used to pass global objects and other values to the pipeline. These values include the location of the redirector script (Redir.asp), the expression evaluator object, and the Content Selection pipeline that should be run to select the content. These values do not change on a per-request basis.

Certain pipeline components in the CSF pipeline expect certain values, some optional, to be set in the dictionary. For example, the CSF pipeline expects the Size, PageGroups, NumRequested, and UserProfile keys to be set in the dictionary.

Redirecting Users

To capture and record the final click events before users navigate away from your site Commerce Server 2000 includes the redirector script, Redir.asp. For example, if an advertiser on your site supplies you with an ad and requests that when the ad is clicked the browser should navigate to the advertiser's site, then without a mechanism such as the redirector, Commerce Server 2000 will have no way to know that the user clicked on the ad. Being able to track these final click events enables you to analyze the performance and success of targeted content on your Web site.

To implement the Redir.asp script you must create an Event Processing pipeline in the Global.asa file. The following code creates the Event Processing pipeline and can be added to the code in the Code to Support the ContentSelection Object topic.

Dim dCSFAdsContext
Set oPipe = Server.CreateObject ("Commerce.OrderPipeline")
oPipe.LoadPipe (oPipelineMap.RecordEvent)
Set Application ("CampaignsCSFEventPipe") = oPipe

The following code should be included in the Redir.asp script.

Note

  • The Solution Sites and the Advertising Sitelet include versions of the Redir.asp script that you can reuse.
Sub Main()
    Dim oPipe, sUrl, sCacheName, oContentList
    Dim dictCache, dictOrder, dictContext
    Dim Errlvl, oFactory, ciid, sEvt

    ' Get Pipeline object.
    Set oPipe = Application("CampaignsCSFEventPipe")

    ' Get the Content cache that this event is associated with.
    sCacheName = Request.Querystring("CacheName")

    If sCacheName <> "" Then
    ' Get cache object
    Set dictCache = Application("MSCSCacheManager").GetCache(sCacheName)

        ' Get name of event to record (default is CLICK).
        sEvt = Request.Querystring("evt")
        If sEvt = "" Then sEvt = "CLICK"

        ' Set up Order and Context dictionaries and execute the pipeline.
        If ciid > 0 Then
            ' Create dictionaries
            Set dictOrder = Server.CreateObject("Commerce.Dictionary")
            Set dictContext = Server.CreateObject("Commerce.Dictionary")

            ' "_winners" is the item(s) to record the event for.
            ' (may be a simplelist or a scalar)
            dictOrder("_winners") = ciid

            ' "_event" is the name of the event to record. You cannot
            ' record more than one event name per pipeline invocation.
            dictOrder("_event") = sEvt

            ' Create a content list of items from the given cache.
            Set oFactory = dictCache("Factory")
            Set oContentList = oFactory.CreateNewContentList
            Set dictOrder("_content") = oContentList

            ' Get the in-memory dictionary of campaign item performance.
            Set dictOrder("_Performance") = dictCache("_Performance")
            dictContext("SiteName") = sCacheName

            ' Look up page group ID.
            If Request.QueryString("PageGroupId") <> "" Then
                dictContext("PageGroupId") =
                CLng(Request.QueryString("PageGroupId"))
            Else
                dictContext("PageGroupId") = 0
            End If

            ' Execute the pipeline to record the event.
            oPipe.orderExecute 1, dictOrder, dictContext, Errlvl

        End If
    End If

    ' Redirect to the supplied URL.
    sUrl = Request.Querystring("url")
    If sUrl <> "" Then
        Response.Redirect(sUrl)
    Else

        Response.Write(MSCSMessageManager.GetMessage
        ("L_NoRedirectionURLSpecified_ErrorMessage", sLanguage))
    End if
End Sub

Advertising Sitelet

Included with Commerce Server 2000 Software Development Kit (SDK) is the Advertising Sitelet. The Advertising Sitelet is an example of how ContentSelector objects can be implemented to show targeted content based on the profile of the user.

For more information about unpacking the Advertising Sitelet, see Adding a Site. The file to unpack, SDK-AD-SITELET.PUP, is located in the C:\Program Files\Microsoft Commerce Server\SDK\Samples\Sitelets\Ad directory on your local computer.


Example Code for the ContentSelector Object

This section provides detailed examples of how to use the ContentSelector object.

This section contains:

  • Code to Support the ContentSelector Object. Contains code to include in the Global.asa file to support the ContentSelection object.

  • Code to Execute the ContentSelector Object. Contains code to include in the Default.asp file that you use to create the ContentSelection object, code that you use with the GetContent method, and code you use to write ads to the Web page.


Code to Support the ContentSelection Object

The following code shows how to initialize the Content Selection Framework (CSF), set up the CacheManager object and the Expression Evaluator, create an advertising pipeline, and configure the context for CSF ads.

The Global.asa file should include the following code:

<SCRIPT LANGUAGE=VBSCRIPT RUNAT=Server>

option explicit

' Initialize the Content Selection Framework.
Sub Application_OnStart

    ' Modify sConnStr to point to a valid Campaigns database.
    ' The Campaigns database can be created either by unpacking a site,
    ' such as blank.pup, or by running the campaign database creation
    ' scripts in the C:/Program Files/Microsoft Commerce Server/Site
    ' Create diretory.
    const sConnStr = "provider=SQLOLEDB;Data Source=(local);Initial
    Catalog=Retail_commerce;User ID=sa;Password=;"

    Dim oPipe, dCSFAdsContext
    Dim oExpressionEval, oCacheManager, dCacheConfig

    ' Set up CacheManager object.
    Set dCacheConfig = CreateObject("Commerce.Dictionary")
    dCacheConfig.ConnectionString = sConnStr
    Set oCacheManager = CreateObject("Commerce.CacheManager")
    oCacheManager.LoaderProgId("Ads") = "Commerce.CSFLoadAdvertisements"
    Set oCacheManager.LoaderConfig("Ads") = dCacheConfig
    oCacheManager.RefreshInterval("Ads") = 15 * 60 ' 15 minutes

    ' Create the Expression Evaluator and connect it to the database.
    Set oExpressionEval = CreateObject("Commerce.ExpressionEvaluator")
    Call oExpressionEval.Connect(sConnStr)

    ' Create CSF advertising context, a dictionary.
    Set dCSFAdsContext = CreateObject("Commerce.Dictionary")

    ' Create an advertising pipeline and add it to the context.
    Set oPipe = CreateObject("Commerce.OrderPipeline")
    ' Load the pipeline configuration
    oPipe.LoadPipe(Server.MapPath("Advertising.pcf"))
    ' Store a reference to the pipeline object in the Context
    ' dictionary.
    Set dCSFAdsContext("pipeline") = oPipe

    ' Other context configuration for CSF ads.
    dCSFAdsContext("RedirectUrl") = ".\redir.asp"
    ' Add a reference to an expression evaluator to the Context
    Set dCSFAdsContext("Evaluator") = oExpressionEval
    ' InitCacheManager, a routine that would appear elsewhere in the
    ' global.asa, returns a reference to a CacheManager object.
    Set dCSFAdsContext("CacheManager") = oCacheManager
    dCSFAdsContext("CacheName") = "Ads"

    ' Store a reference to the dCSFAdsContext dictionary in the
    ' Application collection.
    Set Application("CSFAdsContext") = dCSFAdsContext
End Sub

</SCRIPT>


Code to Execute the ContentSelection Object

The following code shows how ContentSelector objects are typically created, used to select the content through the GetContent method, and write that content to the Web page.

The Default.asp file should include the following code:

<%
    ' Create a ContentSelector object.
    Set CSO = Server.CreateObject("Commerce.ContentSelector")

    ' Use the GetContent method to get some content. Use the dictionary
    ' previously created in the Global.asa file and referenced through the
    ' Application collection.
    Set Ads = CSO.GetContent(Application("CSFAdsContext"))
    ' Ads is a SimpleList containing the selected content.
    ' Write the content to the page, if any.
    For Each Ad in Ads
        Response.Write(Ad)
    Next
%>

Other, optional properties may be set on the ContentSelector object as well. These properties depend on the components in the selection pipeline and their configuration. The most common optional properties include UserProfile, NumRequested, PageGroup, and Size.


Display Objects

The display objects perform a variety of functions, such as the display of Euro currency and other currency values, data type conversion, value range checking, the display of error messages to users, and the display of locale-specific values.

This section contains:

  • Display Objects Concepts. Describes the major issues relating to the use of display objects.

  • Example Code for Display Objects. Provides detailed examples of how to use the display objects.

See Also

AppFrameWork Object

DataFunctions Object

EuroDisplay Object

MessageManager Object


Display Object Concepts

The following display objects are used in Commerce Server 2000:

AppFrameWork Object

DataFunctions Object

EuroDisplay Object

MessageManager Object

AppFrameWork Object

The AppFrameWork object is new in Commerce Server 2000, and replaces much of the functionality of the Page object, the latter of which will not be supported in future releases. The Page object must be created on every page; in contrast, the AppFrameWork object has better performance because it is created once in the Global.asa file and can be used on any page.

The majority of the methods for the AppFrameWork object have names that begin with Request. These methods apply locale-based data type conversion and data range checking to data retrieved from a browser request. There are two ways to send data from a browser to a server: Data can be appended to the request URL as a query string (for example, http://servername/mysite/default.asp?keyword=books) or it can be posted via forms. Performing these operations on user input ensures that the input data retrieved by an Active Server Pages (ASP) page can be inserted without error into the database storage for the site or passed to the Order Processing pipeline (OPP) in an OrderForm object without generating pipeline or page syntax errors.

Object Dependencies

Because the Request methods of the AppFrameWork and Page object rely on the DataFunctions object for method implementation, you must create the DataFunctions object before you create an AppFrameWork object or a Page object.

The following table shows the values returned by Request methods under different conditions.

Condition | Method returns
The key/value pair is present on request and is valid. | The key value returned from the URL query string or form-post variable.
The value returned is empty or Null (for example, the user did not type a value for a search key), or the value is of the wrong type. | The default value (Null, or the value specified by the Default parameter).
The value returned is out of the specified range. | Null.
The value returned is invalid according to the rules for the locale. | Null.

DataFunctions Object

The DataFunctions object performs locale-based data type handling and value range checking on values that you submit to the database or that you pass in an OrderGroup object to the Order Processing pipeline (OPP).

The DataFunctions object is usually created in the Global.asa file. Use the Active Server Pages (ASP) Server object CreateObject method to create a DataFunctions object, as follows:

Set MSCSDataFunctions = Server.CreateObject("Commerce.DataFunctions")
' Initialize the object after instantiation
MSCSDataFunctions.Locale = dictConfig.i_SiteDefaultLocale

Also, store the new object in the Application object in the Global.asa file, as follows:

Set Application("MSCSDataFunctions") = MSCSDataFunctions

The AppFrameWork and Page objects have a direct dependency on the DataFunctions object; the DataFunctions object must be created before an AppFrameWork object or a Page object is created.

EuroDisplay Object

The EuroDisplay object can be used to convert and format currencies. It was originally designed to handle use of the Euro currency, but it can be used for conversion between any two currencies. This object provides convenient currency conversion functionality.

MessageManager Object

The MessageManager object stores error messages in multiple languages that the Order Processing pipeline (OPP) components use to describe error conditions generated during OrderForm object processing.


Example Code for Display Objects

This section provides detailed examples of how to use the display objects.

This section contains:

  • Code to Apply Data Type Conversion and Range Checking Describes how to perform locale-based data type conversion and range validation.

  • Code to Manipulate and Display Euro Values. Describes how to use the EuroDisplay object to convert currency amounts.

  • Code to Convert Between Numbers and Strings. Describes how to use the conversion functions of the DataFunctions object.

  • Code to Display Locale-Specific Strings. Describes how to use locale-based conversion functions of the DataFunctions object.

  • Code to Manage Common Error Messages to Users. Describes how to add languages and messages to the MessageManager object, and how to write messages to a Web browser.


Code to Apply Data Type Conversion and Range-Checking

This topic describes how to create an Active Server Pages (ASP) page (Form.asp) that contains a form whose contents are checked and converted to a Date Variant. The checking and conversion are performed by the Process.asp file.

The first parameter to the RequestDate method specifies, in the following example, the name of the form field from which the data was submitted. If this text field is empty, the second parameter to the RequestDate method, "1/1/2000", becomes the date that the RequestDate method processes. First, the string expression of the date is converted to a date value based on a specified Locale property (1033, the Locale property for US in this instance), and then the value is checked against the specified date range specified by the third and fourth parameters.

If the Form.asp file is loaded into the browser, it will display the date as processed by the RequestDate method in the Process.asp file.

  1. Create the Form.asp file using the following code:
    <FORM METHOD="POST" ACTION = "Process.asp">
<INPUT TYPE="Text" NAME= "Date">
<INPUT TYPE ="Submit" NAME = "Action" VALUE = "Send Info"
</FORM>
  2. Create the Process.asp file using the following code:
    Dim oAppFrameWork, vDate
Set oAppFrameWork = Server.CreateObject("Commerce.AppFrameWork")
vDate = oAppFrameWork.RequestDate("Date", _
                                     "1/1/2000", _
                                     "1/1/2000",  _
                                     "12/12/2000", _
                                     "1033")
If IsNull(vDate) Then
    Response.Write "Invalid Date"
Else
    Response.Write vDate
End If


Code to Manipulate and Display Euro Values

The purpose of this example is to convert currency information from dollars to French Francs. In this example, you create an Active Server Pages (ASP) page that creates a EuroDisplay object, initializes it to set the Base Currency Symbol to "$", the Base Locale to the locale for the US, the Alternate Currency Symbol to "FF", the Alternate Locale to France, and the conversion rate equal to $ 1.00 = 2 FF. The example then converts 100 units of the Base Currency to Alternate Currency units; $100 will convert to 200 Francs.

  1. Instantiate the EuroDisplay object. Note that this line of code is usually found in the Global.asa file.
    Dim EuroDisplay, Result
Set oEuroDisplay= Server.CreateObject("Commerce.EuroDisplay")
  2. Initialize the EuroDisplay object. Note that this line of code is usually found in the Global.asa file. This code will initialize the object by setting the Base Currency Symbol to "$", the Base Locale to the locale for the US, the Alternate Currency Symbol to "FF", the Alternate Locale to France, and the conversion rate equal to $ 1.00 = 2 FF.
    oEuroDisplay.Initialize("$", 1033, "FF", 1036, 2)
  3. Convert $ 100 to FF 200.
    cyAltCurrency = oEuroDisplay.ConvertMoney(100)
  4. Write the converted value to the page.
    Response.Write "Converted $100 from $ to FF ($1 = 2FF) : " _
               & cyAltCurrency


Code to Convert Between Numbers and Strings

The following two examples illustrate the use of the DataFunctions object in converting between string values and numbers.

Converting a Number to a String

Converting a Monetary Value to a Number

Converting a Number to a String

In this example, you create an Active Server Pages (ASP) page that converts a floating-point number into a variety of outputs. All outputs are based on the US locale; this example explores different rounding and trailing zero variable settings.

Create the example using the following code:

  1. Instantiate the DataFunctions object, and set the object Locale property to US.
    Dim oDataFunctions, iResult, iLocale, iInputFloat
Set oDataFunctions = Server.CreateObject("Commerce.DataFunctions")
iLocale = "1033"
oDataFunctions.Locale = iLocale
  2. Call the Float method to convert the number to the US version with no rounding and with trailing zeros maintained. Write the results to the page.
    iInputFloat = 100.00010
iResult = oDataFunctions.Float(iInputFloat, iLocale, True , False)
Response.Write "USA, No Rounding, With Trailing: " & Result & "<P>"
  3. Call the Float method to convert the number to the US version with no rounding and with trailing zeros removed. Write the results to the page.
    Result = oDataFunctions.Float(iInputFloat, iLocale, True, True)
Response.Write "USA, No Rounding, Trim Trailing: " & Result & "<P>"
  4. Call the Float method to convert the number to the US version with rounding and with trailing zeros maintained. Write the results to the page.
    Result = oDataFunctions.Float(iInputFloat, iLocale, False, False)
Response.Write "USA, Rounding, With Trailing: " & Result & "<P>"
  5. Call the Float method to convert the number to the US version with rounding and with trailing zeros removed. Write the results to the page.
    Result = oDataFunctions.Float(iInputFloat, iLocale, False, True)
Response.Write "USA, Rounding, Trim Trailing: " & Result & "<P>"

Converting a Monetary Value to a Number

In this example, you create an ASP page that converts a monetary value to an integer. The ConvertMoneyStringToNumber method returns the value in the base monetary unit for a given Locale property.

Thus, given a value in US dollars, the ConvertMoneyStringToNumber method returns the number of cents in the US dollar value. Additionally, the ConvertMoneyStringToNumber method does not round values. For example, if you pass to this method the number "123.009" the method returns 12300, not 12301.

Create the example using the following code:

  1. Instantiate the DataFunctions object.
    Dim oDataFunctions, iResult, sAmount, iLocale
sAmount = "12000"
Set oDataFunctions = Server.CreateObject("Commerce.DataFunctions")
  2. Set locale to US.
    iLocale = "1033"
oDataFunctions.Locale = iLocale
  3. Convert the string to an integer.
    Result = oDataFunctions.ConvertMoneyStringToNumber("34.095", iLocale)
  4. Write the results to the page.
    Response.Write "USA: " & Result & "<P>"


Code to Display Locale-Specific Strings

This section describes how to create Active Server Pages (ASP) pages that use the string conversion functions of the DataFunctions object.

Converting a Date Based on Locale

Converting a Number Based on Locale

Converting a Money Amount Based on Locale

Converting a Date Based on Locale

In this example, you create an ASP page that converts a date into two locale-specific displays. The first display is that of the French version of the date; the second is the US version.

Create this example using the following ASP code:

  1. Instantiate the DataFunctions object, set the Locale property to France (1036), convert the date string, and write the converted string to the page.
    Dim Result, Amount
Amount = "12000"
Set oDataFunctions = Server.CreateObject("Commerce.DataFunctions")
iLocale = "1036"
oDataFunctions.Locale = iLocale
Result = oDataFunctions.ConvertDateString("12/1/2000", iLocale)
Response.Write "France: " & Result & "<BR>"
  2. Set the Locale property to US (1033), convert the date string, and write the converted string to the page.
    iLocale = "1033"
oDataFunctions.Locale = iLocale
Result = oDataFunctions.ConvertDateString("12/1/2000", iLocale)
Response.Write "USA: " & Result & "<BR>"

Converting a Number Based on Locale

In this example, you create an ASP page that converts a floating-point number into two locale-specific outputs. The first output is that of the French version of the number; the second is the US version.

The output shows the differing display formats of the French and US versions of the number 10000000 (ten million):

  • France: 10 000 000,00

  • US: 10,000,000.00

Create the ASP page using the following code:

  1. Instantiate the DataFunctions object.
    Dim oDataFunctions, sResult, iLocale
Set oDataFunctions = Server.CreateObject("Commerce.DataFunctions")
  2. , Set the Locale property to France (1036), and write the converted number to the page.
    iLocale = "1036"
oDataFunctions.Locale = iLocale
sResult = oDataFunctions.Number(10000000, iLocale)
Response.Write "France: " & sResult & "<BR>"
  3. Change the Locale property to US (1033), and write the converted number to the page.
    iLocale = "1033"
oDataFunctions.Locale = iLocale
sResult = oDataFunctions.Number(10000000, iLocale)
Response.Write " USA: " & sResult & "<BR>"

Converting a Money Amount Based on Locale

In this example, you create an ASP page that converts a floating-point number that contains a monetary value into two locale-specific displays. The first display is that of the French version of the number; the second is the US version.

Use this method to convert a long that contains a monetary value to an equivalent string representation, based on the default or specified Locale property. The output will display the locale-specific currency symbol:

  • France: 120,00 F

  • US: $120.00

Create this example using the following ASP code:

  1. Instantiate the DataFunctions object.
    Dim oDataFunctions, sResult, lAmount
Amount = "12000"
Set oDataFunctions = Server.CreateObject("Commerce.DataFunctions")
  2. Set the Locale property to France (1036), convert the amount, and write the result to the page.
    iLocale = "1036"
oDataFunctions.Locale = iLocale
sResult = oDataFunctions.Money(lAmount, iLocale)
Response.Write "France: " & sResult & "<BR>"
  3. Set the Locale property to US (1033), convert the amount, and write the result to the page.
    iLocale = "1033"
oDataFunctions.Locale = iLocale
sResult = oDataFunctions.Money(lAmount, iLocale)
Response.Write "USA: " & sResult & "<BR>"


Code to Manage Common Error Messages to Users

The MessageManager object is created in the Global.asa file. For the purposes of this example (although this practice is not recommended), it will be created on an ASP page. In this example, a MessageManager object is created, and two languages (Informal and Formal) are added to it. Following this, a message ("greeting") is added to each language. The message is then written to the page in each language.

  1. Instantiate the MessageManager object.
    Dim oMessMgr, sMessage
Set oMessMgr= Server.CreateObject("Commerce.MessageManager")
  2. Add two new languages to the MessageManager object, specifying the US Locale (1033).
    Call oMessMgr.AddLanguage ("Informal", 1033)
Call oMessMgr.AddLanguage("Formal", 1033)
  3. Add two new messages to the MessageManager object.
    oMessMgr.AddMessage "greeting", "Hi, World!", "Informal"
oMessMgr.AddMessage "greeting", "How do you do, World.", "Formal"
  4. Get the informal message, and write it to the page.
    sMessage = oMessMgr.GetMessage("greeting", "Informal")
Response.Write "Informal Message: "& sMessage & "<BR>"
  5. Get the formal message, and write it to the page.
    sMessage = oMessMgr.GetMessage("greeting", "Formal")
Response.Write "Formal Message: " & sMessage & "<BR>"


Expression Objects

An expression is a statement constructed with Boolean and relational operators that is evaluated against the data in a given set of profiles, also known as the evaluation context of the expression. The profiles may be ProfileObject objects, Dictionary objects, or other objects that support property access through the IDispatch interface. Expressions always evaluate to either True or False.

The Expression Architecture consists of three major components: the Expression Store, the Expression Builder, and the Expression Evaluator Engine (EEE). The Expression Store consists of a set of database tables that store the expressions along with related information such as the expression ID and name. For more information, see Expression Recordset.

The Expression Builder provides a Web-based user interface, which allows the business manager to create, modify, and view expressions. For more information, see Expression Builder.

The EEE is the component of most interest to the developer. The EEE is a Component Object Model (COM) object used for evaluating expressions. It uses the services of the ExpressionStore object to load the expressions before evaluating them. It also creates evaluation contexts that are used to evaluate a set of expressions against the same profiles in the most efficient manner. The EEE is used by the marketing and campaign components of Commerce Server 2000.

This topic contains:

  • Expression Programming Concepts. Describes the EEE and the objects it exposes.

  • Example Code for Expression Objects. Provides detailed examples of how to use the objects exposed by the EEE.

See Also

Expression Recordset

Expression XML Structures

ExpressionEval Object

ExpressionStore Object

Profile Objects


Expression Programming Concepts

The Expression Evaluator Engine (EEE) consists of the evaluation core logic, the ExpressionStore, and ExpressionEval objects, and caches for loaded expressions, object properties, and expression results as shown in the following figure.

Expression Evaluation Engine
Evaluation Contexts
Expression
Result
Cache
Object
Property
Cache
Evaluation
Core
Expression
Cache
Expression
Evaluation Engine
ExpressionEval
Object
Expression Store
Database
ExpressionStore
Object
External Programs
Using the EEE

The EEE consists of the following parts:

  • Evaluation Context

  • Evaluation Core

  • Expression Cache

  • Expression Result Cache

  • ExpressionEval Object

  • ExpressionStore Object

  • Object Property Cache

Evaluation Context

An evaluation context is used to evaluate a set of expressions against the same profiles. Performance is gained when evaluation contexts are used because it allows the EEE to do more intelligent caching. Specifically, it enables caching of profile properties and expression results. This is used by the CSF EvalTargetGroups component, for example, because this component evaluates many expressions against the same profiles and many of those expressions are commonly repeated in multiple target groups.

If an evaluation context is not explicitly created, one will automatically be created each time an expression is evaluated. Such context objects are automatically released once the expression has been evaluated.

Evaluation Core

This is the core logic of the EEE. It handles the actual evaluation of the expression.

Expression Cache

Expressions are loaded from the Expression Store into this cache. When an expression is to be evaluated, the ExpressionEval object firsts looks for the expression in this cache. If the expression is not found, it is loaded. For enhanced performance at run-time, pre-load expressions into the expression cache using the LoadExpr or LoadAll methods of the ExpressionEval object.

Expression Result Cache

The result of an evaluated expression is cached so the result can be returned without re-evaluating the expression a second time for a given evaluation context.

ExpressionEval Object

This object loads and flushes the expression cache, creates the evaluation contexts against which expressions are evaluated, and performs the evaluations on the expressions. For more information, see ExpressionEval Object.

ExpressionStore Object

This object interacts with the Expression Store to create, delete, save, retrieve, query, import, and export expressions. For more information, see ExpressionStore Object.

Object Property Cache

When an expression is initially evaluated, references to the dependent profile objects are stored in this cache. During evaluation, as the object properties are accessed, they are also stored in this cache for reuse.


Example Code for Expression Objects

This section provides detailed examples of how to use the expression objects exposed by the Expression Evaluation Engine. The code samples are written in either Microsoft Visual Basic, Microsoft Visual Basic Scripting Edition (VBScript), or Active Server Pages (ASP). The samples do not show error checking or certain other formalities required for functional code.

This section contains:

  • Code to Connect to the Expression Store. Describes how to connect to, and disconnect from, the Expression Store.

  • Code to Create an Evaluation Context. Describes how to create an evaluation context that contains the data for evaluating an expression against.

  • Code to Evaluate an Expression Stored as an XML Fragment. Describes how to evaluate an expression stored as an XML fragment.

  • Code to Create a New Expression. Describes how to create a new expression.

  • Code to Manipulate Expressions. Describes how to retrieve or delete expressions from the Expression Store, rename an expression, or translate between expression IDs and expression names.

  • Code to Evaluate a Single Expression. Describes how to evaluate a single expression.

  • Code to Evaluate Groups of Expressions. Describes how to create a stored evaluation context and evaluate groups of expressions against this common context.

  • Code to Import and Export Expressions. Describes how to import and export expressions.


Code to Connect to the Expression Store

A connection to the Expression Store can be made either directly through the Connect method of an ExpressionStore object or indirectly through the Connect method of an ExpressionEval object. The determining factor will be which operations need to be performed. Use an ExpressionStore object if expressions are to be created or manipulated. If evaluating existing expressions, use an ExpressionEval object. When connecting through an ExpressionStore object, use the Disconnect method to release the connection to the Expression Store. The ExpressionEval object automatically releases the connection to the Expression Store upon termination.

Connecting Using an ExpressionStore Object

Connecting Using an ExpressionEval Object

Connecting Using an ExpressionStore Object

  1. Retrieve the connection string to the Expression Store using a SiteConfigReadOnly object. Initialize the SiteConfigReadOnly object for the "Retail" site. This step should be performed in the Global.asa file and the resulting connection string cached in the Application collection or in a global dictionary for use in Active Server Pages (ASP) pages.
    Dim sConn
Dim oSiteConfigReadOnly

Set oSiteConfigReadOnly = Server.CreateObject("Commerce.SiteConfigReadOnly")

oSiteConfigReadOnly.Initialize "Retail"

sConn = oSiteConfigReadOnly.Fields("Biz Data Service")_
.Value.Fields("s_BizDataStoreConnectionString").Value

Set oSiteConfigReadOnly = Nothing
  2. Create the ExpressionStore object and store the connection string to the Expression Store.
    Dim oExpressionStore
Set oExpressionStore = Server.CreateObject("Commerce.ExpressionStore")

oExpressionStore.Connect sConn

Connecting Using an ExpressionEval Object

Connection through the use of an ExpressionEval object can made by passing a reference to an existing ExpressionStore object or by passing an explicit connection string, in which case a new ExpressionStore object will be created.

  1. Create the ExpressionEval object. Note that the ProgID, ExpressionEvaluator, is different than the object name.
    Dim oExpressionEval
Set oExpressionEval = Server.CreateObject("Commerce.ExpressionEvaluator")
  2. Connect to the Expression Store.
    • Connect using the previous ExpressionStore object, oExpressionStore.
      oExpressionEval.Connect oExpressionStore

    • Connect using the previously obtained connection string, sConn.

      oExpressionEval.Connect sConn

      •

    3.


Code to Create an Evaluation Context

This section describes how to create an evaluation context (a Dictionary object) that contains the data for evaluating an expression against.

  1. Retrieve the two profiles, oUser1, a UserObject object, and oAddress1, an Address object, created in Code to Create a New Profile. For more information about retrieving the profiles, see Code to Retrieve a Profile.

  2. The properties of these profiles that are evaluated in the following sections are:
    oUser1.GeneralInfo.first_name = "Joe"
oAddress1.GeneralInfo.region_code = "WA"
  3. Create a Dictionary object and insert the two profiles.
    Dim dictProfiles
Set dictProfiles = Server.CreateObject("Commerce.Dictionary")

Set dictProfiles.User = oUser1
Set dictProfiles.Address = oAddress1


Code to Evaluate an Expression Stored as an XML Fragment

This section describes how to parse and evaluate an expression stored as an Extensible Markup Langauge (XML) fragment. An XML fragment is equivalent to the ExprBody field of the expression Recordset object. The XML fragment is first parsed for syntactic correctness. This is only performed at design-time since the EvalXML method also parses the fragment. If the expression parses correctly, it is then evaluated.

  1. Create an XML expression fragment. This expression will return True when evaluated against a context containing a UserObject object and an Address object, where the first_name property of the UserObject object = "Joe" AND the region_code of the Address object = "WA". In this example, the string representing the expression is not formatted properly for scripting with respect to quotation marks and continuation in order to increase readability.
    Dim strXMLExpression

sXMLExpression =
 "<TERM TYPE="and">
    <CLAUSE OPER="equal">
       <PROPERTY ID="UserObject.GeneralInfo.first_name" TYPE="string" />
       <IMMED-VAL TYPE="string">Joe</IMMED-VAL>
    </CLAUSE>
    <CLAUSE OPER="equal">
       <PROPERTY ID="Address.GeneralInfo.region_code" TYPE="string" />
       <IMMED-VAL TYPE="string">WA</IMMED-VAL>
    </CLAUSE>
  </TERM>"

  2. Create an ExpressionEval object and parse the string to determine if it represents a syntactically valid XML expression.
    Dim bResult
Dim oExpressionEval
Set oExpressionEval = CreateObject("Commerce.ExpressionEvaluator")

bResult = oExpressionEval.ParseXML(sXMLExpression)

The result, bResult, equals True since this fragment is syntactically valid.

  3. Evaluate the XML fragment against the data contained in the dictProfiles context created in Code to Create an Evaluation Context. The properties of interest in the dictProfiles context are:
    User.GeneralInfo.first_name = "Joe"
Address.GeneralInfo.region_code = "WA"

Dim vResult
vResult = oExpressionEval.EvalXML(sXMLExpression, dictProfiles)

Set oExpressionEval = Nothing

The result of evaluating the expression, vResult, is True.


Code to Create a New Expression

This section describes how to create a new expression.

  1. Using the ExpressionStore object, oExpressionStore, created in Code to Connect to the Expression Store, create an empty recordset to contain the new expression.
    Dim rsExpr
Set rsExpr = oExpressionStore.NewExpression()
  2. The returned recordset is an ADO hierarchical Recordset object. It contains one parent and two child Recordset objects, one child for profile dependencies and one child for expression dependencies. Populate the fields in the parent recordset. The string, sXMLExpression, used for the ExprBody field, is defined in Code to Evaluate an Expression Stored as an XML Fragment. No error checking is performed on the syntax of this string when the Recordset object is saved. Use the ParseXML method to verify the correct syntax before saving the recordset. If the expression is meant to appear as a target or catalog expression in the Campaign Expressions module in Commerce Server Business Desk, the Category field must be set to "CAMPAIGNS" or "CATALOG", respectively.
    rsExpr.Fields("ExprName").Value = "Expr_WA_Joe"
rsExpr.Fields("ExprBody").Value = sXMLExpression
rsExpr.Fields("Category").Value = "WA Users"
rsExpr.Fields("ExprDesc").Value = "Is the user from WA and named Joe?"
  3. Add and populate a new record in the profile dependencies child recordset for each profile the new expression depends on. At least one profile dependency is required to evaluate the expression against.
    Dim rsDeps
Set rsDeps = rsExpr.Fields("rsProfDeps").Value

rsDeps.AddNew
rsDeps.Fields("ProfDep").Value = "User"
rsDeps.AddNew
rsDeps.Fields("ProfDep").Value = "Address"
  4. Add and populate a new record in the expression dependencies child recordset for each expression the new expression depends on. An expression does not have to depend on other expressions; thus, this step is optional.
    Set rsDeps = rsExpr.Fields("rsExprDeps").Value

rsDeps.AddNew
rsDeps.Fields("ExprDep").Value = 123
  5. Save the expression in the Expression Store and release the Recordset objects.
    oExpressionStore.SaveExpression(rsExpr)

Set rsDeps = Nothing
Set rsExpr = Nothing


Code to Manipulate Expressions

When a new expression is saved to the Expression Store a unique expression ID is created which is used to further access the expression. This section describes how to retrieve the expression ID using the name of the expression. Once the expression ID is retrieved, the expression is renamed, which is the only operation on the expression that is supported through the API. To further manipulate the expression, the corresponding recordset is retrieved and the description of the expression is changed. Finally, the expression is deleted from the Expression Store.

  1. Using the ExpressionStore object, oExpressionStore, created in Code to Connect to the Expression Store, translate the name of the expression, "Expr_WA_Joe", created in Code to Create a New Expression into its expression ID.
    Dim lExpressionID
lExpressionID = oExpressionStore.GetExprID("Expr_WA_Joe")
  2. Rename the expression to "Expr_2001.93".
    oExpressionStore.RenameExpression lExpressionID, "Expr_2001.93"
  3. Retrieve the recordset corresponding to the expression.
    Dim rsExpression
Set rsExpression = oExpressionStore.GetExpression(lExpressionID)
  4. Change the description of the expression.
    rsExpression.Fields("ExprDesc").Value = _
 "Is the user named Joe and from WA?"
  5. When finished using the expression, delete it. If the expression has a non-zero reference count (one or more other expressions depend on this expression), the method will fail and the expression will not be deleted.
    oExpressionStore.DeleteExpression lExpressionID, 0

Set rsExpression = Nothing


Code to Evaluate a Single Expression

A single expression may be evaluated either directly against a Dictionary object containing a set of profiles or indirectly against a stored evaluation context. For information about evaluating the expression against a stored context, see Code to Evaluate Groups of Expressions.

  1. Using the ExpressionEval object, oExpressionEval, created in Code to Connect to the Expression Store, load the expression created in Code to Create a New Expression into the Expression Cache. The expression ID, lExpressionID, for this expression was retrieved in Code to Manipulate Expressions. Loading the expression is optional. If you have not preloaded the expression, the Eval method will load the expression upon execution.
    oExpressionEval.LoadExpr lExpressionID
  2. Evaluate the expression against the data contained in the dictProfiles context created in Code to Create an Evaluation Context.
    Dim vResult
vResult = oExpressionEval.Eval(lExpressionID, dictProfiles)

The result of evaluating the expression, vResult, is True.


Code to Evaluate Groups of Expressions

If a group of expressions is to be evaluated against the same context, it is more efficient to create a stored evaluation context rather than iterating the expressions through the Eval method, which creates and destroys an evaluation context for each expression evaluated.

  1. Using the ExpressionEval object, oExpressionEval, created in Code to Connect to the Expression Store, create a stored evaluation context using the dictProfiles context created in Code to Create an Evaluation Context.
    Dim oEvaluationContext
Set oEvaluationContext = _
 oExpressionEval.CreateEvalContext(dictProfiles)
  2. Load all the expressions in the Expression Store into the Expression Cache, including the expression created in Code to Create a New Expression. This step is optional. Any expressions not preloaded will be loaded by the EvalInContext method when those expressions are evaluated. If you do not want to load all the expressions, you can load individual expressions using the LoadExpr method.
    oExpressionEval.LoadAll
  3. The expression ID, lExpressionID, for the expression created in Code to Create a New Expression was retrieved in Code to Manipulate Expressions. Evaluate this expression against the evaluation context.
    Dim vResult
vResult = oExpressionEval.EvalInContext(lExpressionID, _
 oEvaluationContext)

The result of evaluating the expression, vResult, is True.

  4. Evaluate any other expressions using the same stored context, and then release the context.
    Set oEvaluationContext = Nothing


Code to Import and Export Expressions

This section describes how to import and export groups of expressions. An import file must contain the XML expression recordset schema followed by the XML representation of each expression recordset to be imported. The format of the exported file is the same. For information about expression structures in XML, see Expression XML Structures.

  1. Using the ExpressionStore object, oExpressionStore, created in Code to Connect to the Expression Store, import the expressions from the file Expressions.xml into the Expression Store. If the Expression Store is not empty, the method will fail.
    oExpressionStore.Import "Expressions.xml"
  2. Export the expressions contained in the Expression Store to the file Exported_Expressions.xml.
    oExpressionStore.Export "Exported_Expressions.xml"


General Purpose Objects

The general purpose objects perform a variety of functions including writing error and warning events to the event log, retrieving Web site properties, storing name/value pairs, generating globally unique identifiers (GUIDs), and retrieving the contents of server-side files.

This topic contains:

  • General Purpose Programming Concepts. Describes the major issues relating to the use of the general purpose objects.

  • Example Code for General Purpose Objects. Provides detailed examples of how to use the general purpose objects.

See Also

AdminEventLog Object

AdminFiles Object

CacheManager Object

Dictionary Object

GenID Object

LRUCache Object

SimpleList Object


General Purpose Programming Concepts

The following objects are considered general purpose, and can be used in many contexts within Commerce Server:

  • AdminEventLog Object

  • AdminFiles Object

  • CacheManager Object

  • Dictionary Object

  • GenID Object

  • LRUCache Object

  • SimpleList Object

AdminEventLog Object

The AdminEventLog object is used to write error, informational, and warning messages to the event log, which can be viewed in the Commerce Server Manager Event Viewer snap-in.

For more information, see AdminEventLog Object.

AdminFiles Object

The AdminFiles object is used to return the contents of a file on the server. The file contents can be of any type, such as text, bitmaps, numeric data, and so on.

For more information, see AdminFiles Object.

CacheManager Object

The CacheManager object is normally created in the Application_OnStart event in the Global.asa file for an Active Server Pages (ASP) application. It uses the services of other Component Object Model (COM) objects called Loader and Writer components, whose job it is to populate caches with data and write data that has been collected in the cache, respectively. Each cache is required to have a Loader component configured, but the Writer component is optional. The CacheManager object is configured by setting the LoaderProgId, LoaderConfig, WriterProgId, and WriterConfig properties for each cache being created.

After one or more caches have been configured in an application, any ASP page in the application can use the GetCache method of the CacheManager object to access the cached data. The type of cache object returned, either a Dictionary object or an LRUCache object, depends on the configuration of the LoaderProgId property for the cache.

The CacheManager object can be configured to automatically refresh each cache periodically, based on the RefreshInterval property. Automatic cache refresh can also be disabled by setting the RefreshInterval property to zero (0), which is the default. The CacheManager object also retries failed load operations after a configurable pause, controlled with the RetryInterval property.

When the CacheManager object refreshes the cache, either from an explicit call to the RefreshCache method or based on the refresh interval expiring, it performs several actions. First, if the cache has been configured with a Writer component, the CacheManager object creates, configures, and executes the Writer component to record performance data collected since the last refresh operation. If the Writer component should fail, then the entire refresh operation is aborted. Next, the CacheManager object creates, configures, and executes the specified Loader component to repopulate the cache. A Loader component can be designed such that if it determines that the existing contents of the cache are current, or otherwise sufficient, it can simply return CACHE_E_NOCACHE_UPDATED message. When the CacheManager object recognizes this return code, it does not replace the existing cache with the newly created one that was passed to the Loader component, and any changes that were made to the new cache object are discarded.

For more information, see CacheManager Object.

Dictionary Object

A Commerce Server Dictionary object is a collection object that supports the creation, storage, and retrieval of key/value pairs in memory. Every element in a Dictionary object is a Variant, which means you can create a Dictionary object that consists of almost any kind of values (including other Dictionary objects), and that you can store any combination of Variant types in the same Dictionary object.

The Commerce Server architecture uses the Dictionary object for a number of specialized purposes, including the SiteConfig object. However, because a Dictionary object is designed to be a general purpose collection, you can use it for almost anything that its internal structure supports.

For more information, see Dictionary Object.

GenID Object

This object is used to generate globally unique identifiers (GUIDs).

For more information, see GenID Object.

LRUCache Object

This object is used to support the creation, storage, and retrieval of key/value pairs from a cache. LRUCache objects are similar to Dictionary objects, except that LRUCache objects can only store a limited number of elements. The LRUCache object ranks elements from most-recently-used to least-recently-used. When the LRUCache object is at capacity, it removes the least-recently-used element from the cache and adds the new element. The replacement algorithm used by LRUCache object is an approximate method that allows the cache size to grow to 110 percent of its maximum size setting. Once this limit is reached, the least-recently-used 10 percent of items are removed from the cache.

For more information, see LRUCache Object.

SimpleList Object

A Commerce Server SimpleList object consists of an array of Variants that supports enumeration and access by index. The SimpleList object is used extensively throughout Commerce Server. Use a SimpleList object instead of a Dictionary object in circumstances where accessing the stored content by index is important.

For more information, see SimpleList Object.


Example Code for General Purpose Objects

This section provides detailed code examples of how to use the general purpose objects.

This section contains:

  • Code to Write an Error Event to the Commerce Server Event Log. Describes how to write an error event to the Commerce Server 2000 event log.

  • Code to Read and Display the Contents of a Server-Side File. Describes how to read the contents of a server-side file and write those contents to the browser.

  • Code to Dump Dictionary Values. Describes how to dump the contents of a Dictionary object.

  • Code to Create and Manipulate a SimpleList. Describes how to create and work with the SimpleList object.

  • Code to Implement Custom Cache Components. Describes how to implement custom cache components.

  • Code to Manipulate an LRUCache Object. Describes how to manipulate an LRUCache object.

  • Code to Generate a GUID. Describes how to generate a globally unique identifier (GUID).


Code to Write an Error Event to the Commerce Server Event Log

This section describes how to write an error event to the event log.

The first parameter to the WriteErrorEvent method specifies, in this example, the name of the server in which Commerce Server 2000 is installed. The second parameter specifies the event message string.

Create the example ASP page using the following code:

<HTML>
<HEAD>
</HEAD>
<BODY>
<%
Dim oAdminEventLog
Set oAdminEventLog = Server.CreateObject("Commerce.AdminEventLog")
oAdminEventLog.Initialize("myServerName")
oAdminEventLog.WriteErrorEvent "mySite", "Error Event Message String"
%>
</BODY>
</HTML>


Code to Read and Display the Contents of a Server-Side File

This example uses the ReadFromFile method of the AdminFiles object to read the text file contents; the Internet Information Services (IIS) intrinsic method Response.Write is then used to write those contents to the browser. If you want to read and write file types other than text files, use the ReadFromBinaryFile method of the AdminFiles object in conjunction with the Response.WriteBinary method.

Create the example ASP page using the following code:

<HTML>
<HEAD>
</HEAD>
<BODY>
<%
Dim oAdminFiles, strRet
Set oAdminFiles = Server.CreateObject("Commerce.AdminFiles")
strRet = oAdminFiles.ReadFromFile("c:\temp\Sample.txt")
Response.Write strRet
%>
</BODY>
</HTML>


Code to Dump Dictionary Values

When you need to create a Dictionary object explicitly (that is, when the object is not created for you by some other Commerce Server 2000 object), use the CreateObject method of the Internet Information Services (IIS) intrinsic Server object, as follows:

Dim oMyDictionary
Set oMyDictionary = Server.CreateObject("Commerce.Dictionary")

After creating the object, you can add elements to it, as follows:

oMyDictionary.first_name = "Steve"

In this example, first_name is a Dictionary key, and "Steve" becomes the assigned value of this key.

You can extract values from a Dictionary object in several ways. You can place the object.key identifier on the right side of the assignment statement. Such an assignment returns the value of the referenced key:

my_first_name = oMyDictionary.first_name

Or you can use the Value method to get the value of a given key:

my_first_name = oMyDictionary.value("first_name")

You can also use the For Each statement in Microsoft Visual Basic Scripting Edition (VBScript) to enumerate through either the keys or the values of a Dictionary object as follows (this example assumes that every value in the dictionary contains text):

' Get the key names.
For Each element in oMyDictionary
    Response.Write element
next

' Get the values.
For Each element in oMyDictionary
    Response.Write oMyDictionary.Value(element)
Next

The following example creates a new Dictionary object, loads values into two keys named first_name and last_name, then writes the element names and element values to the browser:

Set oMyDictionary = Server.CreateObject("Commerce.Dictionary")
oMyDictionary.first_name = "Sam"
oMyDictionary.last_name = "Stone"

' Get the key names.
For Each element in oMyDictionary
    Response.Write "Key = " & element
    Response.Write "    Value = " & oMyDictionary.Value(element)
    Response.Write "<br>"
Next


Code to Create and Manipulate a SimpleList

In the following example, several color values are added to a newly created SimpleList object named ColorList. Once the colors are added, the third color value (blue, with an index value of 2) is removed. Following this, the code iterates through the list, using the Count property to determine the number of items in the SimpleList; in turn, each remaining color is written to the browser.

The example ASP code follows:

<HTML>
<HEAD>
</HEAD>
<BODY>
<%
Dim ColorList, Count
Set ColorList = Server.CreateObject("Commerce.SimpleList")
Call ColorList.Add("Red")
Call ColorList.Add("Green")
Call ColorList.Add("Blue")
Call ColorList.Add("Fuschia")
Call ColorList.Delete(2)

' Count will be 3, not 4.
Count = ColorList.Count

' Output will be "Red  Green  Fuschia" on a line by itself.
For i = 0 To (Count - 1)
    Response.Write ColorList(i) & "  "
Next
Response.Write "<br>"
%>
</BODY>
</HTML>


Code to Implement Custom Cache Components

Loader and Writer components are used within the Content Selection Framework (CSF) to load caches and write out campaign results.

Loader and Writer components can be apartment-threaded since they are created, used once, and then destroyed by the same thread. This means that they can be written in Microsoft Visual Basic.

Loader and Writer components are implemented as pipeline components, although they are not intended to be executed in the context of a pipeline. They must implement the Execute method of the IPipelineComponent interface for the CacheManager object to be able to execute them. Further, if they require configuration, they must implement the SetConfigData method of the IPipelineComponentAdmin interface. The following tables provide details regarding this requirement.

Loader Component

Method to Implement Details
IPipelineComponent::

Execute

 Required for the Loader component to execute.

The pDispContext parameter is set to the existing cache instance, if it exists, otherwise it is set to a new, empty cache object. If the cache object (specified by the LoaderProgId setting for the cache) is a Dictionary object, then the following additional entries are set:

  • _CacheName set to the name of the cache being refreshed.

  • _CacheRefreshInterval set to the refresh interval.

  • _CacheFirstRefresh set to one (1) on the first cache refresh, and to zero (0) thereafter (can be used for conditional error logging).

  • _AppUrl set to the value of the AppURL property, if any. This entry is optional and may not be set if the CacheManager object is not running in an ASP application.

The pDispOrder parameter is set to a new cache object based on the setting of the LoaderProgId property, normally a Dictionary object or an LRUCache object, which will become the new cache.

The lFlags parameter is set to zero (0).

The plErrorLevel parameter is ignored on return.
IPipelineComponentAdmin::

SetConfigInfo

 Optional. Required only if the Loader component requires configuration. Will be called if LoaderConfig property has been set.

The pDict parameter is set to point at the Dictionary object specified by the LoaderConfig property.

Writer Component

Method to Implement | Details
IPipelineComponent:: Execute | Required for the Writer component to execute. The pDispOrder parameter is set to the existing cache instance. Normally a Writer component will retrieve data from the cache to be written to disk. The pDispContext parameter set to NULL. The lFlags parameter is set to zero (0). The plErrorLevel parameter is ignored on return.
IPipelineComponentAdmin:: SetConfigInfo | Optional. Required only if the Writer component requires configuration. Will be called if WriterConfig property has been set. The pDict parameter is set to point at the Dictionary object specified by the WriterConfig property.

' Create a Cache manager component and configure it
Set dictConfig = CreateObject("Commerce.Dictionary")
dictConfig("ConnectionString") = "DSN=adsamples;UID=sa;PWD="
Set CacheManager = Server.CreateObject("Commerce.CacheManager")
CacheManager.LoaderProgId("advertising") = "Commerce.LoadAdvertisements"
Set CacheManager.LoaderConfig("advertising") = dictConfig
CacheManager.WriterProgId("advertising") = "Commerce.WriteEvents"
Set CacheManager.WriterConfig("advertising") = dictConfig
CacheManager.RefreshInterval("advertising") = 10 * 60
CacheManager.RetryInterval("advertising") = 60
Set application("CacheManager") = CacheManager

Now any web page in the application can quickly access the named schedule:

Set CacheManager = application("CacheManager")
Set dictSchedule = CacheManager.GetCache("advertising")


Code to Manipulate an LRUCache Object

The following example code shows how to use the LRUCache object.

' Declare variables to be used.
Dim oLRUCache, oDict, oNewDict, NumVal

' Create an instance of an LRU cache.
Set oLRUCache = CreateObject("Commerce.LRUCache")

' Set the max cache size to 100 items.
oLRUCache.SetSize 100

' Create an object to store.
Set oDict = CreateObject("Commerce.Dictionary")
oDict("Test") = "This is a test."

' Store the Dictionary object.
oLRUCache.Insert "DictObject", oDict

' Store the number 10.
oLRUCache.Insert "Number", 10

' Lookup the stored Dictionary object using method LookupObject.
Dim oNewDict
Set oNewDict = oLRUCache.LookupObject "DictObject"

' Lookup the stored number using method Lookup.
Dim NumVal
NumVal = oLRUCache.Lookup "Number"

' Remove all items from the cache.
oLRUCache.FlushAll

' Display the results, which will be:
' This is a test.
' 10
Response.Write "Dictionary data from cache: " & oDict.Test & "<BR>"
Response.Write "Number stored in cache: " & NumVal & "<BR>"


Code to Generate a GUID

The following example code shows how to generate a globally unique identifier (GUID).

Dim oGenID, sGUID
Set oGenID = Server.CreateObject("Commerce.GenID")

sGUID = oGenID.GenGUIDString()
Set oGenID = Nothing


List Management Objects

The ListManager object provides methods to create and manage lists. These lists can be lists of users for the User Profile Management System, lists of e-mail addresses for Direct Mailer, lists of segment members from the Predictor resource, lists generated from Analysis reports, and lists created from files and Structured Query Language (SQL) queries.

This section contains:

  • List Management Programming Concepts. Describes the List Manager service and the object it exposes.

  • Example Code for the ListManager Object. Provides detailed examples of how to use the ListManager object.

See Also

Creating and Managing Direct Mail Lists

Exporting a Report to List Manager

Exporting Segment Data to List Manager

Managing Lists of User Records

ListManager Object


List Management Programming Concepts

List Types

List Manager contains the functionality to manipulate two types of lists, Generic lists and Mailing lists. Each type may also have User and Mailable attributes. Lists are designated as static or dynamic depending on when the data is imported.

You use a Mailing list with Direct Mailer. It contains a list of recipients who have been designated to receive an e-mail ad or a list of recipients that should not receive the mailing. The default flags value indicates a Mailing list; the LISTFLAG_GENERIC flag must be set when the list is created or when the list is imported if the list you are creating is not a Generic list. A Mailing list implies a list with a specific set of column names and types. Direct Mailer uses only Mailing lists, although a Mailing list may be automatically extracted from a Generic list so long as it is a Mailable Generic list.

A Generic list may have any set of column names and types — it essentially maps to a SQL Server database table. When a list is imported into List Manager from the Analysis reporting feature or the Predictor segment viewer, it is imported as a Generic list. Generic lists may be converted to Mailing lists if they meet certain requirements. A Generic list may be imported from an SQL query but cannot be imported from a flat file.

A Mailable list is any list with an rcp_email column. When you import or create a Mailable list, you indicate that it is a Mailable list by setting the LISTFLAG_MAILABLE flag. A Generic list may or may not be Mailable; a Mailing list is always Mailable. After importing a Generic list, ListManager automatically attempts to detect a Mailable list, and sets the appropriate flag. The Mailable list flag exists for integration with Direct Mailer features, so that Direct Mailer can identify which lists to use for e-mail recipients and opt-out lists.

A User list is any list with an rcp_guid column. When you import or create a User list, you indicate that it is a User list by setting the LISTFLAG_USER flag. A Generic list may or may not be a User list; a Mailing list is always a User list. After importing a Generic list, List Manager automatically attempts to detect a User list, and sets the appropriate flag. The User list flag exists for integration with User Profile Management features. For example, it is possible to import a list from the Segment Viewer module in Commerce Server Business Desk and set a property in the user profile of each user in that list to indicate their membership in a particular segment. This information is then available for targeting by the Content Selection Framework for advertising and discounts.

Lists may be created as either static or dynamic. In a static list, records are imported at the time the list is created. A dynamic list imports records on demand when referenced by another operation.

Flag Values

The following table lists the possible flag parameter values used to determine the type of list created. Values may be combined using the logical OR operator to specify more than one flag.

List Type | Value | Description
DEFAULT | 0x0 | A Mailing list.
HIDDEN | 0x1 | The list should not be exposed in the user interface.
DYNAMIC | 0x2 | A dynamic list.
USER | 0x4 | A User list (contains an rcp_guid column).
GENERIC | 0x8 | A Generic list.
MAILABLE | 0x10 | A Mailable list (contains an rcp_email column).

Import/Export

List Manager can import lists from the following sources:

  • An SQL query run against an Open Database Connectivity (ODBC) data source.

  • An Analysis report run from Commerce Server Business Desk.

  • A Predictor resource segment.

  • A text file (comma-separated value (CSV) format).

List Manager can export lists to the following destinations:

  • A SQL Server 2000 table in an external database.

  • A text file (CSV format).

Text Files

If an absolute file path and name is not specified when importing or exporting a list, List Manager looks for the file relative to a root folder named "CommerceLists" on the local computer running the List Manager service. If the folder does not exist, an error is returned.

List Manager recognizes the following input text file format:

<Mail-to Address>,<User ID>,<Format>,<Locale>,<Source URL><cr><lf>

The only required field is Mail-to Address. The optional Format field should be one of the following: 1 - text, 2 - MIME, or 3 - MHTML. Any double quotation marks surrounding a field will be stripped. A trailing comma will produce an error.

List Manager exports text files in the same format as described above with all fields enclosed in double quotation marks.

Asynchronous Mode

List Manager allows time-consuming operations to run in an asynchronous manner. When run asynchronously, the operation returns immediately after the process has started. An application that starts an operation asynchronously has the following additional methods available:

  • The WaitOnOperation method returns when the operation is finished, or a timeout has occurred.

  • The GetOperationInfo method returns all details of the operation including its current status.

  • The CancelOperation method signals the operation to quit. If the operation does not quit in two minutes, the operation is terminated.

Database Tables

List Manager stores information about lists and operations in the lm_master and lm_master_operations database tables, respectively. For information on the format of these tables, see ListManager.GetLists and ListManager.GetOperations.


Example Code for the ListManager Object

This section provides examples of how to use the ListManager object. The code examples are written in Microsoft Visual Basic Scripting Edition (VBScript). Some of the example code uses asynchronous operations and should not be run under Active Server Pages (ASP) without modification. The code examples do not show error checking or certain other formalities required for functional code.

This section contains:

  • Code to Initialize the ListManager Object. Describes how to create and initialize the ListManager object.

  • Code to Create a List. Describes how to create a list from a file.

  • Code to Manipulate Lists. Describes the operations performed on lists such has copy, subtract, union, and export, and the procedure to add and subtract a user from a list.

  • Code to Enumerate Available Lists. Describes how to retrieve and enumerate the available lists and set list properties, such as the list name and description.


Code to Initialize the ListManager Object

  1. Create a ListManager object.
    Dim oListManager
Set oListManager = CreateObject("Commerce.ListManager")
  2. Initialize the object.
    oListManager.Initialize "Provider=sqloledb;" & _
 "Data Source=TequillaServer;Initial Catalog=Margaritas;" & _
 "User ID=userid;Password=******"


Code to Create a List

Lists can be created from a text file, an SQL query, an analysis report, or a Predictor resource segment. This section describes how to create a list named 'Users1' from a file named Users.csv. Once the list is created, the number of unique users imported into the list is retrieved.

  1. Create the Users.csv text file. A representative section of the file follows that contains the e-mail addresses and IDs for a group of users.
    joeuser@roguecellars.com,Newuser_R121
barneyuser@fabrikam.com,Olduser_F3
bettyuser@arborshoes.com,Newuser_A872
jackuser@vigorairlines.com,Olduser_V83
jilluser@microsoft.com,Olduser_M2901
  2. Use the initialized ListManager object, oListManager, created in Code to Initialize the ListManager Object, to create a Mailable User list (userFlags = 20) from the text file.
    Dim vListID1, vOperationID
vListID1 = oListManager.CreateFromFile("Users1", "Just users", _
 20, 0, "D:\Users.csv", 0, True, vOperationID)
  3. Set the maximum time allowed for the list to be created to 10 minutes (600 seconds). If the list is not created in this time, the method will return an error.
    oListManager.WaitOnOperation vOperationID, 600
  4. When the creation operation finishes, retrieve the number of unique e-mail addresses imported.
    Dim rsOperationInfo, vOperationStatus, vUniqueUsers
Set rsOperationInfo = oListManager.GetOperationInfo(vOperationID)
vOperationStatus = rsOperationInfo("op_status")
If vOperationStatus = 0 Then
   vUniqueUsers = oListManager.GetListProperty(vListID1, _
     "list_unique_emails")
   Wscript.Echo "Number of unique users is " & vUniqueUsers & vbCrLf
ElseIf vOperationStatus = 1 Then
   Wscript.Echo "List still being created" & vbCrLf
ElseIf vOperationStatus = -1 Then
   Wscript.Echo "List creation failed" & vbCrLf
Else
   Wscript.Echo "Bad status code" & vbCrLf
End If
  5. Release the objects.
    Set oListManager = Nothing
Set rsOperationInfo = Nothing


Code to Manipulate Lists

  1. Using the initialized ListManager object, oListManager, created in Code to Initialize the ListManager Object, create a new empty list named 'Users2'.
    Dim vListID2
vListID2 = oListManager.CreateEmpty("Users2", "More users", 20, 0)
  2. Copy the list, 'Users1', created in Code to Create a List to the new list.
    oListManager.Copy "Users1", vListID2, False
  3. Delete three members from the 'Users2' list.
    oListManager.RemoveUserFromMailingList "Users2", _
 "barneyuser@fabrikam.com"

oListManager.RemoveUserFromMailingList "Users2", _
 "jackuser@vigorairlines.com"

oListManager.RemoveUserFromMailingList "Users2", _
 "jilluser@microsoft.com"
  4. Add two new users to the 'Users2' list.
    oListManager.AddUserToMailingList "Users2", _
 "janeuser@fabrikam.com", Newuser_F554

oListManager.AddUserToMailingList "Users2", _
 "freduser@vigorairlines.com", Newuser_V919
  5. Perform a union and a subtraction on the 'Users1' and 'Users2' lists. The lists holding the results of the union and subtraction operations must exist prior to running the methods. The results are shown in the following table.
    oListManager.CreateEmpty "Union", "Unique users", 20, 0
oListManager.CreateEmpty "Subtract", "Remaining users", 20, 0
oListManager.Union "Users1", "Users2", "Union", 0, False
oListManager.Subtract "Users1", "Users2", "Subtract", 0, False
    Users1 | Users2 | Union | Substact
    joeuser@roguecellars.com | joeuser@roguecellars.com | joeuser@roguecellars.com | barneyuser@fabrikam.com
    barneyuser@fabrikam.com | bettyuser@arborshoes.com | barneyuser@fabrikam.com | jackuser@vigorairlines.com
    bettyuser@arborshoes.com | janeuser@fabrikam.com | bettyuser@arborshoes.com | jilluser@microsoft.com
    jackuser@vigorairlines.com | freduser@vigorairlines.com | jackuser@vigorairlines.com
    jilluser@microsoft.com | jilluser@arborshoes.com
    janeuser@fabrikam.com
    freduser@vigorairlines.com

  6. Export the Union list to a SQL Server database table named NewUsers, overwriting any previous data. Once the operation is complete, delete the list.
    sConnect = "Provider=sqloledb;Data Source=TequillaServer;" & _
 "Initial Catalog=Margaritas;User ID=userid;Password=******"

oListManager.ExportToSQL "Union", sConnect, "NewUsers", True, 0, False

oListManager.Delete "Union"


Code to Enumerate Available Lists

This section describes how to enumerate the available lists and change the properties of one of the lists, such as the list name and description.

  1. Using the initialized ListManager object, oListManager, created in Code to Initialize the ListManager Object, retrieve the Recordset object containing the lists.
    Dim rsLists
Set rsLists = oListManager.GetLists()
  2. Iterate through the list descriptions searching for the list described as Unique users. When found, change the name to UserFamily, change the description, and add some flags. Note that the recordset returned by the GetLists method is read-only.
    Dim vListID
While Not rsLists.EOF
   If rsLists("list_description") = "Unique users" Then
      vListID = rsLists("list_id")
      oListManager.SetListProperty vListID, "list_name", "UserFamily"
      oListManager.SetListProperty vListID, "list_description", _
       "Members of the User family"
      oListManager.SetListProperty vListID, "list_userflags", 255       Exit While
   rsLists.MoveNext
Wend


Pipeline Objects

Pipeline objects use pipeline configuration files to run a series of pipeline components. This section provides code samples showing how to use pipeline objects and pipeline components.

This section contains:

  • Pipeline Programming Concepts. Describes what a pipeline is, the sequence of events in a pipeline, and how pipelines can be customized.

  • Example Code for Pipeline Objects. Explains how to use code to invoke pipelines and pipeline components.


Pipeline Programming Concepts

A pipeline is an extensible software framework that defines and links together one or more stages of a business process, running them in sequence to complete a specific task. For example, the Order Processing pipeline (OPP) provides the sequence of steps that are used to process purchases from your site. In the first stage in the OPP, you retrieve the product information from the catalog database. In the next stage, you add the address of the user to the order. Each stage in the pipeline represents a category of work. The sequence of the stages determines the sequence in which the work is to be done.

Commerce Server 2000 includes a set of pipelines that perform much of the standard processing required by a Commerce Server site. A site developer can tailor these pipelines to meet the specific needs for the site. For example, a site developer can add new stages to the pipeline, integrate the pipeline components with your existing system, or replace the components with other components supplied by third parties.


Example Code for Pipeline Objects

This section provides detailed examples of how to invoke a pipeline component and a pipeline.

This section contains:

  • Code to Invoke a Single Pipeline Component. Describes how to use the Micropipe object to run a single component.

  • Code to Invoke a Pipeline. Provides sample code to set up the objects and dictionaries necessary to run a pipeline.


Code to Invoke a Single Pipeline Component

The MicroPipe object is generally created and used on a per page basis. The steps to invoke the MicroPipe object are basically the same as for running any other pipeline:

  1. Create instances of the necessary dictionaries, the MicroPipe object, and the pipeline component.

  2. Set up the Order and Context dictionaries, and the Configuration dictionary (if necessary).

  3. Configure the component with either the Configuration dictionary or by setting component properties. The method used depends on the specific component.

  4. Load and run the MicroPipe object.

  5. Clean up objects created on the page.

The following examples show the MicroPipe object used with components configured with a dictionary and with properties.

Example of a component configured with a dictionary

The following example shows how to use the MicroPipe object with the SendSMTP pipeline component, which is configured with a dictionary:

' Create Order, Context, and Configuration dictionaries.
Set dOrder = Server.CreateObject("Commerce.Dictionary")
Set dContext = Server.CreateObject("Commerce.Dictionary")
Set dConfig    = Server.CreateObject("Commerce.Dictionary")

' Set values in the Configuration dictionary.
' Not all required values are shown.
dConfig("SubjectField") = "subject_field"
dConfig("BodyField") = "We will no longer accept bruised papayas" _
                       & " or mushy melons."
dConfig("BodyType") = 1

' Set values in the Order dictionary.
' Not all required values are shown.
dOrder("subject_field") = "To All Suppliers"

' Create an instance of the SendSMTP pipeline component.
Set pSMTP = Server.CreateObject("Commerce.SendSMTP")

' Create an instance of the MicroPipe object.
Set oMicropipe = Server.CreateObject("Commerce.MicroPipe")

' Configure the SendSMTP component with the Configuration dictionary.
pSMTP.SetConfigData dConfig

' Tell the MicroPipe which component to run, and run it.
oMicropipe.SetComponent pSMTP
errVal = oMicropipe.Execute(dOrder,dContext,lFlags)

' Checking for pipeline errors would be done here.

' Clean everything up.
Set dOrder = Nothing
Set dContext = Nothing
Set dConfig = Nothing
Set pSMTP = Nothing
Set oMicropipe = Nothing

Example of a component configured by setting properties

The following example shows how to use the MicroPipe object with a pipeline component, CopyValue3, configured by setting a property. The component is written as a Microsoft Visual Basic ActiveX control. The property, KeytoCopy, has as its value a key in the Order dictionary. The component creates a new key by copying the old key name, prefixing it with copy_, and then assigns the value of the original key to it:

' Create Order and Context dictionaries.
Set dOrder = Server.CreateObject("Commerce.Dictionary")
Set dContext = Server.CreateObject("Commerce.Dictionary")

' Create an instance of the CopyValue3 pipeline component.
Set pCopyValue = Server.CreateObject("My.CopyValue3")

' Set the dictionary key to copy - a property.
pCopyValue.KeytoCopy = "this_key"

' Set up the order dictionary - give the key to copy a value.
dOrder("this_key") = "...on the light fantastic toe"

' Create an instance of the MicroPipe object.
Set oMicropipe = Server.CreateObject("Commerce.MicroPipe")

' Tell the MicroPipe which component to run, and then run it.
oMicropipe.SetComponent pCopyValue
errVal = oMicropipe.Execute(dictOrder,dictContext,lFlags)

' Checking for pipeline errors would be done here.

' Clean everything up.
Set dOrder = Nothing
Set dContext = Nothing
Set pValue = Nothing
Set oMicropipe = Nothing


Code to Invoke a Pipeline

To use a pipeline configuration in a pipeline requires a little more set up than using a single component in the MicroPipe object. Generally, in addition to the steps outlined above, you will need to create a MessageManager object and add messages to it in the Global.asa file. The documentation for each component indicates whether or not it uses the MessageManager object. The following code shows how the Application_OnStart procedure creates a MessageManager object and adds messages to it specifically for the ValidateCCNumber pipeline component:

<SCRIPT LANGUAGE=VBScript RUNAT=Server>
Sub Application_OnStart
    ' Set up the MessageManager and messages.
    Set oMessageManager = _
                      Server.CreateObject("Commerce.MessageManager")
    Call oMessageManager.AddLanguage("usa",&h0409)
    oMessageManager.defaultLanguage = "usa"
    Call oMessageManager.AddMessage("pur_cc_expired", _
                                    "Credit card has expired.")
    Call oMessageManager.AddMessage("pur_badcc", _
                             "The credit-card number is not valid.")
    ' Set up the data functions.
    Set oDataFunctions = Server.CreateObject("Commerce.DataFunctions")
    oDataFunctions.Locale = &H0409
    Application.Lock
        Set Application("MSCSMessageManager") = oMessageManager
        Set Application("MSCSDataFunctions") = oDataFunctions
    Application.UnLock
End Sub
</SCRIPT>

Creating the Context dictionary and running the pipeline itself are so frequently done in a Commerce Server site that it makes sense to encapsulate this code in a one or more utility procedures contained in a separate Active Server Pages (ASP) page (for example, Util.asp):

<%
Function GetPipeContextUtil()
    Set dContext("QueryMap") = MSCSQueryMap
    Set dContext("ConnectionStringMap") = MSCSConnectionStringMap
    Set dContext("SiteName") = MSCSDisplayName
    Set dContext("DefaultConnectionString") = _
                                      MSCSDefaultConnectionString
    dContext("Language") = "usa"
    Set dContext = Server.CreateObject("Commerce.Dictionary")
    Set dContext("MessageManager") = Application("MSCSMessageManager")
    Set dContext("DataFunctions") = Application("MSCSDataFunctions")
    Set UtilGetPipeContext = dContext
End Function
%>
<%
Function ExecPipeUtil(sPcfFile, dOrderForm, dContext)
    Dim sPcfPath
    sPcfPath = Request.ServerVariables("APPL_PHYSICAL_PATH") + _
                                                  "\config\" + _
                                                  sPcfFile)
    Set pPooled = Server.CreateObject("Commerce.PooledPipeline")
    Call pPooled.LoadPipe(sPcfPath)
    iErrLevel = pPooled.Execute(1, dOrderForm, dContext, 0)
    UtilRunPipe = iErrLevel
End Function
%>

The following code shows only the code that runs the pipeline. In a full application, more values would likely be added to the OrderForm object:

<%@ Language=VBScript %>
<!-- #include file="util.asp" -->
<%
    ' Create dictionary object orderform

    Set dOrderForm = Server.CreateObject("Commerce.OrderForm")

    dOrderForm.[cc_type] = sCardType
    dOrderForm.[_cc_number] = sCardNumber
    dOrderForm.[_cc_expmonth] = sExpMonth
    dOrderForm.[_cc_expyear] = sExpYear

    ' Create the pipe context

    Set dPipeContext = GetPipeContextUtil()

    ' Run the pipeline
    iErrLevel = ExecPipeUtil("plan.pcf", dOrderForm, dPipeContext)

%>


Prediction Objects

The Predictor resource provides the ability to build analysis models used for predicting user behavior and unknown user attributes, as well as for classifying users into groups (segments) based upon similar attributes and behavior. Model configurations (contained in a set of database tables) supply information used to build the models. Objects are exposed to control the build process, access the models and model configurations, and perform the predictions.

This section contains:

  • Prediction Programming Concepts. Describes the components of the Predictor resource.

  • Example Code for Predictor Objects. Provides detailed examples of how to use the objects exposed by the Predictor resource.

See Also

Predictor Schema

PredictorClient Object

PredictorServiceAdmin Object

PredictorServiceSiteAdmin Object

PredModelBuilder Object

Running the Predictor Resource


Prediction Programming Concepts

The following topics describe the components of the Predictor resource.

Analysis Models

Two types of models are available. Prediction models are used for predicting user behavior, such as cross-sell patterns, and unknown user attributes. Segment models are used for classifying users into groups (segments) based on attributes and behavior, and for predicting the segment to which a particular user will most likely belong. For more information, see Analysis Models.

Analysis Model Configurations

The model configurations are contained in a set of database tables. These configurations contain information used to build analysis models, such as data sources and properties of the data atttributes. For more information, see Predictor Schema.

Prediction Model Viewer

Available through Commerce Server Manager in the Microsoft Managment Console (MMC), this browser provides a graphical representation of a prediction model. For more information, see Viewing Analysis Models.

PredictorClient Object

This object provides methods to predict user behavior, unknown user attributes, and the segments of a population to which a user belongs. For more information, see PredictorClient Object.

PredictorServiceAdmin Object

This object provides lists of available models and model configurations. For more information, see PredictorServiceAdmin Object.

PredictorServiceSiteAdmin Object

This object provides methods to rename and delete models and model configurations, and to generate a list of members of a segment. For more information, see PredictorServiceSiteAdmin Object.

PredModelBuilder Object

This object provides methods to control the building of models. For more information, see PredModelBuilder Object.

Segment Viewer

Available through Commerce Server Business Desk, this viewer provides a graphical representation of a segment model. Data for the Segment Viewer is provided by List Manager, which calls the GenerateSegmentList method of the PredictorServiceSiteAdmin. For more information, see Analyzing Population Segments.


Example Code for Predictor Objects

This section provides detailed examples of how to use the objects exposed by the Predictor resource. The code samples do not show error checking or certain other formalities required for functional code.

There is no Predictor application programming interface (API) available to create a new model configuration. Tables in the database must be modified directly. For more information and an example, see Predictor Schema.

This section contains:

  • Code to Retrieve the Database Connection String. Describes how to retrieve the database connection string.

  • Code to Build a New Model. Describes how to build a new model.

  • Code to Control a Model Build Describes how to control a model build.

  • Code to Retrieve a List of Available Models and Model Configurations. Describes how to enumerate the available models and model configurations.

  • Code to Rename and Delete a Model and a Model Configuration. Describes how to rename and delete a model and a model configuration.

  • Code to Load a Model and Set Default Properties. Describes how to load a model and set default properties for the model predictions.

  • Code to Predict Products. Describes how to expose "cross-sell" opportunities in user behavior with regard to product purchases.

  • Code to Predict User Attributes. Describes how to determine missing profile attributes about a user.

  • Code to Classify a User. Describes how to classify a user into a behavior or profile-based group.


Code to Retrieve the Database Connection String

  1. Create a SiteConfigReadOnly object and initialize it for the "Retail" site.
    Dim oSiteConfigReadOnly

Set oSiteConfigReadOnly = _
 Server.CreateObject("Commerce.SiteConfigReadOnly")

oSiteConfigReadOnly.Initialize "Retail"
  2. Retrieve the connection string to the Data Warehouse.
    Dim sDWConnect As String
sDWConnect = oSiteConfigReadOnly.Fields("Global Data Warehouse") _
 .Value.Fields("connstr_db_dw").Value

Set oSiteConfigReadOnly = Nothing


Code to Build a New Model

The following example shows how to build a new prediction model.

  1. Create a dictionary to contain the build parameters.
    Dim dBuildParams As Commerce.Dictionary
Set dBuildParams = Server.CreateObject("Commerce.Dictionary")
  2. Insert the build parameters into the dictionary. All of these parameters have default values and do not need to be specified. The default model type is "prediction". To specify a segment model, set the ModelType to 1.
    dBuildParams("ModelType") = 0
dBuildParams("ComplexityPenalty") = 75
dBuildParams("InputAttributeFraction") = 0.5
dBuildParams("MeasuredAccuracyMaxPredictions") = 10
dBuildParams("MeasuredAccuracySampleFraction") = 0.2
dBuildParams("MinimumCasesToSplit") = 10
dBuildParams("OutputAttributeFraction") = .5
dBuildParams("SampleSize") = 15,000
  3. Create an object to convert the dictionary into an Extensible Markup Language (XML) string containing the build parameters. The IPersistXML interface is not available through Microsoft Visual Basic Scripting Edition (VBScript).
    Dim oPersistXML As IPersistXML
Set oPersistXML = dBuildParams

Dim sXMLBuildParams As String
sXMLBuildParams = oPersistXML.SaveXML(0)

Set oPersistXML = Nothing
Set dBuildParams = Nothing
  4. Create the PredModelBuilder object.
    Dim oPredModelBuilder As Commerce.PredictorModelBuilder
Set oPredModelBuilder = _
 Server.CreateObject("Commerce.PredictorModelBuilder")
  5. Using the connection string, sDWConnect, retrieved in Code to Retrieve the Database Connection String, and the name of the model configuration, PurchaseCfg1, created in Predictor Schema Example, start the build for a new model named Purchase1. The value, lBuildID, returned by the Start method is used to access the build thread while it is running or paused.
    Dim lBuildID
lBuildID = oPredModelBuilder.Start(sDWConnect, "", _
 "PurchaseCfg1", "Purchase1", sXMLBuildParams, True)
  6. Release the objects.
    Set oPersistXML = Nothing
Set dBuildParams = Nothing
Set oPredModelBuilder = Nothing


Code to Control a Model Build

This section shows how to retrieve the status of a build, and how to pause, resume, and stop the build. Additionally, the priority of the build is retrieved and then increased.

  1. Using the PredModelBuilder object, oPredModelBuilder, check the status of the build thread, lBuildID, started in Code to Build a New Model. For information on the enumerated build states, see PredModelBuilder.Status.
    Response.Write "Build " & lBuildID & " is "
Select Case oPredModelBuilder.Status(lBuildID)
Case PredBldRunning
Response.Write "Running <P>"
Case PredBldPaused
Response.Write "Paused <P>"
Case PredBldShuttingDown
Response.Write "ShuttingDown <P>"
Case Else
Response.Write "No status <P>"
End Select
  2. Assume the build is running. Pause the build.
    If oPredModelBuilder.Status(lBuildID) = PredBldRunning Then
oPredModelBuilder.Pause(lBuildID)
End If
  3. Resume the paused build.
    If oPredModelBuilder.Status(lBuildID) = PredBldPaused Then
oPredModelBuilder.Resume(lBuildID)
End If
  4. Check the priority of the build. For information about the enumerated build priorities, see PredModelBuilder.Priority .
    Dim ePriority
ePriority = oPredModelBuilder.Priority(lBuildID)

Response.Write "Build " & lBuildID & " has a priority of "
Select Case ePriority
Case PriLowest
Response.Write "PriLowest <P>"
Case PriBelowNormal
Response.Write "PriBelowNormal <P>"
Case PriNormal
Response.Write "PriNormal <P>"
Case PriAboveNormal
Response.Write "PriAboveNormal <P>"
Case PriHighest
Response.Write "PriHighest <P>"
Case Else
Response.Write "Bad Priority <P>"
End Select
  5. Increase the priority of the build.
    If ePriority <> PriHighest Then
ePriority = ePriority + 1
End If
  6. Stop the build.
    If oPredModelBuilder.Status(lBuildID) = PredBldRunning Or _
      oPredModelBuilder.Status(lBuildID) = PredBldPaused Then
oPredModelBuilder.Stop(lBuildID)
End If
  7. Stop all the builds.
    oPredModelBuilder.StopAllBuilds


Code to Retrieve a List of Available Models and Model Configurations

  1. Create the PredictorServiceAdmin object.
    Dim oPredictorServiceAdmin
Set oPredictorServiceAdmin = _
 Server.CreateObject("Commerce.PredictorServiceAdmin")

Response.Write "The date the Predictor Service was last started = " _
 & oPredictorServiceAdmin.dateLastStarted & "<P>"
  2. Retrieve and enumerate the list of available model configurations.
    Response.Write "The number of model configurations = " & _
 oPredictorServiceAdmin.slModelConfigs.Count & "<BR>"

Dim oDict
For Each oDict In oPredictorServiceAdmin.slModelConfigs
Response.Write oDict("ModelCfgName") & "<BR>"
Next
  3. Retrieve and enumerate the list of available models.
    Response.Write "The number of models = " & _
 oPredictorServiceAdmin.slModels.Count & "<BR>"

For Each oDict In oPredictorServiceAdmin.slModels
Response.Write oDict("ModelName") & "<BR>"
Next
  4. Release the object.
    Set oPredictorServiceSiteAdmin = Nothing


Code to Rename and Delete a Model and a Model Configuration

  1. Create the PredictorServiceSiteAdmin object. Note that the name of the object and the ProgID are different.
    Dim oPredictorServiceSiteAdmin
Set oPredictorServiceSiteAdmin = _
 Server.CreateObject("Commerce.PredictorSiteAdmin")
  2. Using the connection string, sDWConnect, retrieved in Code to Retrieve the Database Connection String, initialize the object to the "Retail" site.
    oPredictorServiceSiteAdmin.Init "", sDWConnect
  3. Rename the model configuration, PurchaseCfg1, created in Predictor Schema Example, to PurchaseConfig1.
    oPredictorServiceSiteAdmin.RenameModelConfig "PurchaseCfg1", _
 "PurchaseConfig1"
  4. Rename the model, Purchase1, created in Code to Build a New Model, to OddPurchases.
    oPredictorServiceSiteAdmin.RenameModel "Purchase1", "OddPurchases"
  5. Delete the PurchaseConfig1 model configuration.
    oPredictorServiceSiteAdmin.DeleteModelConfig "PurchaseConfig1"
  6. Delete the OddPurchases model.
    oPredictorServiceSiteAdmin.DeleteModel "OddPurchases"


Code to Load a Model and Set Default Properties

This code is placed in the Global.asa file. The properties are set here to avoid explicitly setting the values for every Predict method call.

  1. Create a PredictorClient object.
    Dim oPredictorClient
Set oPredictorClient = Server.CreateObject("Commerce.PredictorClient")
  2. Using the connection string, sDWConnect, retrieved in Code to Retrieve the Database Connection String, load the Purchase1 model created in Code to Build a New Model.
    oPredictorClient.LoadModelFromDB "Purchase1", sDWConnect
  3. Set the properties. The bFailOnUnknownInputAttributes property is set to True while debugging the application. This forces the Predict method to fail when information passed to the method is not recognized by the currently loaded model.
    oPredictorClient.bFailOnUnknownInputAttributes = True
oPredictorClient.fpDefaultConfidence = 95
oPredictorClient.fpPopularityPenalty = 0.2
  4. Associate the PredictorClient object with the site to allow performance monitoring to be aggregated over the site.
    oPredictorClient.sSiteName = "Retail"
  5. Release the object.
    Set oPredictorClient = Nothing


Code to Predict Products

  1. Create a Dictionary object and populate it with information on the current user.
    Dim dCurrentCase
Set dCurrentCase = Server.CreateObject("Commerce.Dictionary")

dCurrentCase("UserID") = "someone@microsoft.com"
dCurrentCase("Age") = ""
dCurrentCase("Gender") = "F"
dCurrentCase("ZipCode") = "98052"
dCurrentCase("Education") = ""
  2. Assume a data table represents the products in the shopping basket of the user. The PivotColumn in this table is named "SKU", the AggregateColumn is named "QTY", and the user has two bottles of a product with an SKU equal to "wine_fine_us_zin_202" in his or her basket. Set this information into the current case for the user. The following naming convention is used for sparse properties only (they appear in Type 1 tables). For more information about the properties and tables, see Predictor Schema.
    dCurrentCase("QTY(wine_fine_us_zin_202)") = 2
  3. Assume a different table represents the advertisements the user has clicked on. The PivotColumn in this table is named "URL", the AggregateColumn is named "HitCount", and the user clicked on the indicated URL once. Set this information into the current case for the user.
    dCurrentCase("HitCount(www.roguecellars.com/ad_md)") = 1
  4. Create a SimpleList object and populate it with the properties to predict.
    Dim slPropertiesToPredict
Set slPropertiesToPredict = Server.CreateObject("Commerce.SimpleList")

slPropertiesToPredict.Add("SKU")
  5. Create Variant Safearrays to store the predicted properties and values.
    Dim vsavPredictedProps
Dim vsavPredictedValues
  6. Using the PredictorClient object, oPredictorClient, created in Code to Load a Model and Set Default Properties, and the Purchase1 model loaded in the same section, make a maximum of five predictions.
    oPredictorClient.Predict dCurrentCase, slPropertiesToPredict _
 vsavPredictedProps, vsavPredictedValues, 5
  7. Iterate through the returned predictions.
    Dim i
For i = LBound(vsavPredictedProps) To UBound(vsavPredictedProps)
Response.Write vsavPredictedProps(i) & " = " _
 & vsavPredictedValues(i) & "<BR>"
Next
  8. Release the objects.
    Set dCurrentCase = Nothing
Set slPropertiesToPredict = Nothing


Code to Predict User Attributes

  1. Create a SimpleList object and populate it with the properties to predict.
    Dim slPropertiesToPredict
Set slPropertiesToPredict = Server.CreateObject("Commerce.SimpleList")

slPropertiesToPredict.Add("Age")
slPropertiesToPredict.Add("Education")
  2. Create Variant Safearrays to store the predicted properties and values.
    Dim vsavPredictedProps
Dim vsavPredictedValues
  3. Make the predictions, using the dictionary, dCurrentCase, created and populated with information on the current user in Code to Predict Products, the PredictorClient object, oPredictorClient, created in Code to Load a Model and Set Default Properties, and the Purchase1 model loaded in the same section.
    oPredictorClient.Predict dCurrentCase, slPropertiesToPredict _
 vsavPredictedProps, vsavPredictedValues
  4. Iterate through the returned predictions.
    Dim i
For i = LBound(vsavPredictedProps) To UBound(vsavPredictedProps)
Response.Write vsavPredictedProps(i) & " = " _
 & vsavPredictedValues(i) & "<BR>"
Next
  5. Release the objects.
    Set dCurrentCase = Nothing
Set slPropertiesToPredict = Nothing


Code to Classify a User

This code sample will first determine the most likely segment to which the current user belongs, and then iterate the probabilities associated with the membership of the user in each segment.

  1. Using the PredictorClient object, oPredictorClient, created in Code to Load a Model and Set Default Properties, and the connection string, sDWConnect, retrieved in Code to Retrieve the Database Connection String, load the Demog1 model created in Predictor Schema Example.
    oPredictorClient.LoadModelFromDB "Demog1", sDWConnect
  2. Using the dictionary, dCurrentCase created in Code to Predict User Attributes, predict the most likely segment.
    Dim sMostLikelySegment
Dim vProbability

sMostLikelySegment = oPredictorClient.PredictMostLikelySegment _
 dCurrentCase, vProbability

Response.Write "Most likely segment is " & sMostLikelySegment & "<BR>"
Response.Write "The probability of membership in this segment is " _
 & vProbability & "<P>"
  3. Create Variant Safearrays to store the segment names and associated membership probabilities.
    Dim vsavSegmentNames
Dim vsavProbabilities
  4. Make the predictions.
    oPredictorClient.PredictAllSegments dCurrentCase, vsavSegmentNames _
 vsavProbabilities
  5. Iterate through the returned predictions.
    Dim i
For i = LBound(vsavSegmentNames) To UBound(vsavSegmentNames)
Response.Write vsavSegmentNames(i) & " - " _
 & vsavProbabilities(i) & "<BR>"
Next


Product Catalog Objects

The product catalog objects provide methods to create and manage catalogs, products, and categories in the Commerce Server 2000 Product Catalog System. These objects provide an interface for catalog data stored in a SQL Server database. Use data caching to improve the performance of the Product Catalog System by holding catalog data in memory and minimizing calls to the underlying database.

This section contains:

  • Product Catalog Programming Concepts Describes the concepts related to programming with product catalog objects.

  • Example Code for Product Catalog Objects Provides example code for product catalog objects.

See Also

CatalogManager Object

CacheManager Object


Product Catalog Programming Concepts

The Commerce Server product catalog objects are described in the following topics.

Catalog System Object Model

CatalogManager Object

ProductCatalog Object

Product Object

Category Object

CatalogSets Object

CatalogToVendorAssociation Object

Catalog System Object Model

The CatalogManager object is the foundation of the catalog system object model. You use the CatalogManager object to create and manage the ProductCatalog, Category, and Product objects in the system. The CatalogSets and CatalogToVendorAssociation objects are managed outside of the object model.

The CatalogManager object manages one or more catalogs, represented by ProductCatalog objects. A catalog may consist of a flat list of products or it may have a hierarchy of categories in which to organize the products. Each Category object represents a node in this hierarchy and contains products or other categories.

The CatalogManager object also manages a collection of properties. These properties are used to define the attributes of the objects in the Product Catalog System. Appropriate properties must be created before the CatalogManager object can create any other objects.

CatalogManager Object

The CatalogManager object is the first object you create to use the Commerce Server 2000 Product Catalog System. Typically, a single CatalogManager object is created in the global.asa file and used throughout an application. This object sets and retrieves properties that apply to all the catalogs in the Product Catalog System. Use the CatalogManager object to create and manage catalogs. You also use the CatalogManager object to create properties, define their attributes, and to create product and category definitions using those properties. The CatalogManager object also provides methods for queries and free text searches across single or multiple catalogs.

The CatalogManager.CreateCatalog and CatalogManager.GetCatalog methods return a ProductCatalog object representing a specific catalog. The CatalogManager.Catalogs property is a recordset of all the catalogs in the Product Catalog System.

ProductCatalog Object

The ProductCatalog object represents a single catalog in the Product Catalog System. All of the methods of the ProductCatalog object are executed from the context of a specific catalog. You use the ProductCatalog object to add new products and categories to a catalog, to create a custom catalog, or to perform a specification search.

The ProductCatalog.RootCategories method returns a recordset of categories that is the starting point for traversing the category hierarchy. Similarly the ProductCatalog.RootProducts method returns a recordset of products that are not in a category hierarchy.

Product Object

The Product object represents a single product or product family in the catalog. A product definition is created using the CatalogManager object and can be used across the Product Catalog System, but a product is always in the context of a single catalog. Use the Product object to perform operations on a product, such as modifying properties, creating product variants, or managing relationships.

Category Object

The Category object represents a single category in the catalog. Categories provide a method for organizing products within a catalog. Use this object to perform various operations on a category, such as adding products or other categories, or managing relationships.

The Category.ChildCategories property is a recordset containing the names of categories that exist below this category in the hierarchy. The Category.Products property is a recordset containing all the products that exist directly in this category.

CatalogSets Object

The CatalogSets object stores and manages catalog sets, which are arbitrary collections of catalogs. Catalog sets allow you to present different collections of catalogs to different users and organizations.

CatalogToVendorAssociation Object

The CatalogToVendorAssociation object stores and manages associations between catalogs and vendors (suppliers).

See Also

Product Catalog Objects

Example Code for Product Catalog Objects

CatalogManager Object

ProductCatalog Object

Category Object

Product Object

CatalogSets Object

CatalogToVendorAssociation Object

Copyright © 1996–2000 Microsoft Corporation.
All rights reserved.


Example Code for Product Catalog Objects

This section provides detailed examples of how to use the objects exposed by the Commerce Server 2000 Product Catalog System. The code examples do not show error checking or certain other formalities required for functional code.

This section contains:

  • Code to Activate or Deactivate a Product

  • Code to Browse a Catalog

  • Code to Change How a Category is Displayed

  • Code to Find the Available Catalogs

  • Code to Hide Searchable Categories

  • Code to Perform a Free-Text Search of a Catalog

  • Code to Perform a Specification Search of a Catalog

  • Code to Stage Products and Catalogs by Time

  • Code to Use Caching with a Catalog


Code to Activate or Deactivate a Product

Normally, catalog data is visible to users as soon as it is placed in the Product Catalog System. It is possible to activate or deactivate a product in a catalog, that is make it visible or hide it from users, by adding an additional property to that product, and then filtering on that property.

The following provides steps on how to implement this scenario:

  1. Define a new property of type number and call it "IsActive" and set the AssignToAll attribute to True and the DisplayOnSite attribute to False. Set the default value to either 0 (not available) or 1 (available).

  2. When creating or editing products, a value can be specified for this property, either 0 (not available) or 1 (available).

  3. Filter any recordsets of products, such as those returned from the Category.Products, CatalogManager.Query, CatalogManager.FreeTextSearch, ProductCatalog.GuaranteedSpecificationSearch, ProductCatalog.PerformSpecificationSearch methods by specifying an ActiveX Data Object (ADO) filter on the recordset as "IsActive=1".

For example, wherever you have code similar to the following:

rsProducts = oCatalog.GetCategory(strCategoryName).Products

You need to follow it with:

rsProducts.filter = "IsActive=1"

Note

  • Caching of HTML may prevent products from appearing on the Web site until the cache is flushed.


Code to Browse a Catalog

This section contains code examples for some of the functions needed to implement browsing. These functions are to find categories in a catalog, to find products in a category, to find product properties, and to display the results. Parameter validation and error handling are not considered in these examples. A more extensive example can be found in the Browse.asp file in the Catalog sitelet, which is in the Commerce Server 2000 Software Development Kit (SDK). The Browse.asp file and its included files demonstrate parameter validation, error handling, and generation of links from recordsets.

  1. Get the CatalogManager Object and the catalog.

    The CatalogManager object should already be created and initialized in the Global.asa file. Get a local reference to the CatalogManager object and the catalog.

    Dim oCatMgr
Dim oCatalog
Set oCatMgr = Application("MSCSCatalogManager")
Set oCatalog = oCatMgr.GetCatalog("ChildrensClothing")
  2. Get the categories.

    The categories in a catalog are in a hierarchy. The root categories may or may not have child categories, but they are at the base of the hierarchy. The following example creates a recordset of the root categories.

    Dim rsCategories
Dim rsCategories
Set rsCategories = oCatalog.RootCategories

    The following example shows how the category hierarchy can be traversed. Given a recordset of categories at some level in the hierarchy, the CategoryName field is used to retrieve a recordset of the child categories of the active row in the given recordset:

    Dim strName
' Return the name of the category in the active row of
' the recordset (this would usually be inside a loop).
strName = rsCategories("CategoryName")
Set rsChildCategories = oCatalog.GetCategory(strName).ChildCategories

If you have the category object in hand obtaining the child categories is straightforward:
'oCategory is an existing Category object.
Set rsChildCategories = oCategory.ChildCategories
  3. Get the products.

    The following example assumes that all products are in categories. Root products, that is products that are not in any category can exist; however, the usual design calls for all products to belong to a category. Having all products within categories simplifies code and product management. The following code retrieves the products in the "shoe" category:

    Dim rsProducts
Set rsProducts = oCatalog.GetCategory("Shoes").Products
  4. Get product detail.

    When displaying a product, you will typically want to display some details about that product. The following example creates a recordset of the properties of a specified product.

    'vProductID is the unique identifier for a product. The Catalog sitelet uses the ISBN as the product ID.
Dim rsProductDetail
Set rsProductDetail = _
    oCatalog.GetProduct(0-7356-0513-0).GetProductProperties
  5. Display the results.

    The following code example demonstrates how to display a set of products contained in a recordset called rsProducts. For an example of generating links from a recordset, see the Browse.asp file in the Catalog Sitelet in the Commerce Server 2000 SDK.

    <br>
<%
' Loop through the recordset of products and.
' write out the properties of the products.
' The constants are field names.
Do While Not rsProducts.EOF

    Response.Write "ISBN Number: " & _
                   rsProducts("isbn") & "<BR>"
    Response.Write "Title: " & _
                   rsProducts("name") & "<BR>"
    Response.Write "Author: " & _
                   rsProducts("author") & "<BR>"
    Response.Write "Published in: " & _
                   rsProducts("Publication Year") & "<BR>"

    rsProducts.MoveNext()
Loop
%>


Code to Change How a Category is Displayed

Categories must be unique across the Product Catalog System. This prevents using the same category name in multiple catalogs. For example, if you have a catalog for men and a catalog for women, you cannot have a category in both catalogs named Shoes. You can work around this limitation by displaying a different property instead of the category name.

The following steps outline how to change how a category is displayed in your catalog:

  1. Define a property of type text and call it "DisplayName".

  2. Set the AssignToAll attribute to False.

  3. Add this property to any category definitions used, for example the Department category definition.

  4. When creating categories, the category name must still be unique, but a non-unique name can be specified for the DisplayName field.

  5. Modify the shopping site code to display the DisplayName field of a category as its name, rather than the CategoryName field.

The following example demonstrates the modifications needed. It is taken from the Browse.asp file in the Catalog sitelet in the Commerce Server 2000 SDK. The original code only needed the addition of a constant for the name of the new field and a change in one script variable: needs a simple change

' CATALOG_PROP_NAME is defined in an include file as "CategoryName".
' Create a new constant for display name field.
CATALOG_DISP_NAME = "DisplayName"
' Substitute CATALOG_DISP_NAME where appropriate.
' This loop writes out the list of available categories
' from a recordset as links to another page in the application:
<%
'...
Do While Not g_rsCategories.EOF
    ' The anchor tags produced below pass the category name to the
    ' file "browse.asp", but have been modified to show the display
    ' name as the hot text (change shown in bold text).
    %>
    <a href="browse.asp?category=
       <%= Server.URLEncode(g_rsCategories(CATALOG_PROP_NAME)) %>">
       <%= g_rsCategories(CATALOG_DISP_NAME) %>
    </a>
    <br>
    <%
    g_rsCategories.MoveNext()
Loop


Code to Find the Available Catalogs

The names and attributes of the catalogs in the Product Catalog System are available in a recordset returned by the Catalog property of the CatalogManager object. The following example creates a recordset of the available catalogs and prints out a list of catalog names.

Dim oCatMgr
Dim rsCatalogs
' Get a local reference to the CatalogManager
' object created in the global.asa file.
Set oCatMgr = Application("MSCSCatalogManager")
Set rsCatalogs = oCatMgr.Catalogs
'Write out the catalog names from the recordset.
If (rsCatalogs.RecordCount > 0) Then
    rsCatalogs.MoveFirst()
    Do While Not rsCatalogs.EOF
        Response.Write rsCatalogs.Fields("CatalogName").Value
        Response.Write "<BR>"
        rsCatalogs.MoveNext()
    Loop
End If


Code to Hide Searchable Categories

Some sites will define searchable categories, which reflect product types that are valid across various departments. These categories are intended to facilitate searching, and are different from the hierarchy of categories that are meant to be shown to the users. Displaying searchable categories on the site could confuse the users.

Whenever displaying categories on the site, your code should first check to see whether the category has the IsSearchable attribute set to True. If so, that category should not be shown. The following example filters the "Shoes" category to remove any searchable child categories. Similar filters would be needed in your code wherever categories are going to be displayed.

' oCatalog is an existing ProductCatalog object.
Dim rsCategories
Set rsCategories = oCatalog.GetCategory("Shoes").ChildCategories

' Remove searchable categories from the recordset.
rsCategories.filter "IsSearchable = FALSE"

Now the rsCategories recordset contains only shoe categories that are appropriate for display.


Code to Perform a Free-Text Search of a Catalog

The following code example shows a wrapper function that performs a free text search. It uses typical values for return properties and sorting properties, and simplifies performing a free text search by building the parameters for a call to the CatalogManager.FreeTextSearch method.

The constants used to build the values of the sPropertiesToReturn and sPropertiesToSortOn variables will need to be defined according to your catalog schema.

' Function: rsFreeTextSearch
'
' Description:
'    Performs a Free-Text Search using typical values.
'    Returns the results as a recordset.
'    iRecordCount gets set to the number of records retrieved.
'
' Parameters:
'    sPhrase             - the freetext string to find
'    iStartingRecord     - return results starting from this record#
'    iRecordsToRetrieve  - return max. this many records
'    iRecordCount        - return the actually retrieved number
'                          of records in this parameter
'
' Returns:
'   Recordset with search results
' -----------------------------------------------------------------------
Function rsFreeTextSearch(ByVal sPhrase, _
                          ByVal iStartingRecord, _
                          ByVal iRecordsToRetrieve, _
                          ByRef iRecordCount)

    ' Declare variables:
    Dim sPropertiesToReturn
    Dim sPropertiesToSortOn
    Dim rsResult
    Dim iClassType
    Dim sCatalogsToSearch

    ' Build the parameter strings to select
    ' properties to return and to control sorting:
    ' "name" and "description" are required product
    ' properties and cannot have null values.
    sPropertiesToReturn = PRODUCT_NAME_PROPERTY_NAME & "," & _
                          PRODUCT_DESCRIPTION_PROPERTY_NAME & "," & _
                          CATALOG_NAME_PROPERTY_NAME & "," & _
                          CATEGORY_NAME_PROPERTY_NAME & "," & _
                          CATALOG_PRODUCTID_PROPERTY_NAME & "," & _
                          CATALOG_VARIANTID_PROPERTY_NAME & "," & _
                          DEFINITION_TYPE_PROPERTY_NAME

    ' "name" is a required product property and cannot have a null value.
    sPropertiesToSortOn = CATEGORY_NAME_PROPERTY_NAME & "," & _
                         PRODUCT_NAME_PROPERTY_NAME

    ' Determine what catalogs to search.
    ' This example assumes that you will always search two catalogs:
    ' CatalogA and CatalogB. You could get this parameter by having
    ' the user select which catalogs to search, or from a function
    ' that selected catalogs based on a user profile.
    sCatalogsToSearch = "CatalogA, CatalogB"

    ' Determine the type of data wanted. This example will return
    ' categories, products, and product families.
    iClassType = cscProductFamilyForVariantsClass Or _
                 cscProductClass Or _
                 cscCategoryClass

    ' Call the FreeTextSearch method and return the recordset.
    Set rsFreeTextSearch = _
          MSCSCatalogManager.FreeTextSearch( _
             sPhrase, _
             sCatalogsToSearch, _
             iClassType, _
             sPropertiesToReturn, _
             sPropertiesToSortOn, _
             True, _
             iStartingRecord, _
             iRecordsToRetrieve, _
             iRecordCount _
             )

End Function


Code to Perform a Specification Search of a Catalog

Performing a specification search is an iterative process. The ProductCatalog.PerformSpecificationSearch method can return more than the recordset of matching data. This additional information can be useful for controlling program flow.

The ProductCatalog.PerformSpecificationSearch method indicates the total number of matching records. You may need to force the user to refine the search if there are too many hits. For performance reasons, you should limit the size of the returned recordset to what can be displayed on a single page. The PerformSpecificationSearch method can provide a recordset of searchable properties and existing values for those properties in an optional parameter. Display these properties and values to the user so that the search can be refined.

The following steps demonstrate the use of the PerformSpecificationSearch method.

  1. A specification search is always in the context of a single catalog. Call the BeginSpecificationSearch method to create the search handle:
    ' oCatalog is catalog object to search.
' sCategoryName is a string containing the name of the
' category to search.
Dim bNoResults      ' Test flag
Dim sSearchHandle   ' String to hold the accumulated search clauses
Dim rsFields        ' Recordset to hold the searchable fields
                    ' in the category
Dim iMatchesFound   ' Holds the number of hits

' Call BeginSpecificationSearch to create the search handle.
sSearchHandle = oCatalog.BeginSpecificationSearch(sCategoryName, _
                                                  rsFields, _
                                                  iMatchesFound)
' Test if the category is specification searchable.
bNoResults = (rsFields Is Nothing)
If bNoResults Then
    ' Display a message to the user that the
    ' category is not specification searchable.
Else
    ' Process the rsFields recordset to find
    ' searchable Fields (see step 2).
    ' Perform the search (see step 3).
End If
  2. The rsFields recordset contains one field for each property in the category. Each field in the recordset contains a SafeArray of all the available values for that property. Display this information to the user as series of drop-down lists. After the user has made their selection and posted the form, you add specification clauses for each selected value:
    Dim arr1, arr2
Dim bQuote
Dim sValue
Dim objField, iFieldType
Dim sSearchClause, sPropertyName
Dim iConstraintFieldsCount
Dim iNonConstraintFieldsCount

' Initialize variables.
iConstraintFieldsCount = 0
iNonConstraintFieldsCount = 0

' Separate Fields into searchable and non-searchable arrays.
' GetRequestString() is a wrapper function that strips
' illegal characters from a call to AppFrameWork.RequestString.
ReDim arr1(rsFields.Fields.Count)
ReDim arr2(rsFields.Fields.Count)
For Each objField In rsFields.Fields
    sValue = GetRequestString(objField.Name, _
                  mscsMessageManager.GetMessage( _
                       "L_STEPSEARCH_NO_PREFERENCE_TEXT", _
                       sLanguage) )

    ' sValue will contain the selected value where the user has
    ' made a selection. Where the user did not make a selection
    ' sValue will contain L_STEPSEARCH_NO_PREFERENCE_TEXT
    If sValue = mscsMessageManager.GetMessage( _
                  "L_STEPSEARCH_NO_PREFERENCE_TEXT", sLanguage) Then
        ' Field is not a search constraint.
        arr1(iNonConstraintFieldsCount) = objField.Name
        iNonConstraintFieldsCount = iNonConstraintFieldsCount + 1
    Else
        ' Field is a Search Constraint.
        sPropertyName = objField.Name
        arr2(iConstraintFieldsCount) = sPropertyName
        ' Some data types must be enclosed in quotes.
        ' Lookup the DataType attribute for the property
        ' from the property attributes cache.
        iFieldType = _
            MSCSCatalogAttribs.Value(sPropertyName).Value("DataType")

        If (iFieldType = cscString) Or _
           (iFieldType = cscDateTime) Or _
           (iFieldType = cscFilePath) Or _
           (iFieldType = cscEnumeration) Then
            ' If Text OR DateTime OR FilePath OR Multiple Choice.
            bQuote = True
        Else
            bQuote = False
        End If
        ' Build the search clause for one property.
        sSearchClause = ""
        For Each sValue In Request.QueryString(sPropertyName)
            If bQuote Then sValue = """" & sValue & """"
            sSearchClause = sSearchClause & ", " & sValue
        Next
        ' Add the Specification Search Clause that you just built.
        sSearchClause = "[" & sPropertyName & "]" & _
                        " IN (" & _
                        Right(sSearchClause, _
                              Len(sSearchClause) - 2) & _
                        ")"
        Call oCatalog.AddSpecificationSearchClause(sSearchClause, _
                                                   sSearchHandle)

        iConstraintFieldsCount = iConstraintFieldsCount + 1
    End If

' Process the next Field.
Next

ReDim Preserve arr1(iNonConstraintFieldsCount)
ReDim Preserve arr2(iConstraintFieldsCount)
  3. After all the parameters have been built, perform the specification search:
    Set rsResults = _
       oCatalog.PerformSpecificationSearch(sSearchHandle, _
                                           iSearchType, _
                                           , _
                                           iMatchesFound, _
                                           rsFields, _
                                           sColList)
  4. Display the results so that the user can refine the search.


Code to Stage Products and Catalogs by Time

Normally, catalog data is visible to your users as soon as it is placed in the Product Catalog System. It is possible to automatically activate products in a catalog at a pre-determined time or date by adding an additional property and then filtering on that property. A similar technique can be used to deactivate products.

The following steps show how to stage products and catalogs by time.

  1. Define a new property of type Date and call it "AvailableFrom." Set the AssignToAll attribute to True and the DisplayOnSite attribute to False.

  2. When creating or editing products, you can specify a value for the AvailableFrom property, which indicates the date and time that the product should become visible on your Web site.

  3. Filter any recordsets of products, such as those returned from the Category.Products, CatalogManager.Query, CatalogManager.FreeTextSearch, ProductCatalog.GuaranteedSpecificationSearch, ProductCatalog.PerformSpecificationSearch methods by specifying an ActiveX Data Object (ADO) filter on the recordset as "AvailableFrom<=NOW". (Where NOW must be replaced by the current date and time, appropriately formatted.)

For example, where you have code like:

rsProducts = oCatalog.GetCategory(strCategoryName).Products

You need to follow it with:

rsProducts.filter = "AvailableFrom <= " & format(Date, General Date)

This prevents products from being visible on your Web site until the date and time specified.

Note

  • Caching of HTML may prevent products from appearing on your Web site until the cache is flushed.


Code to Use Caching with a Catalog

The following code demonstrates both the CacheManager object setup code required in the Application_OnStart event of the Global.asa file, and the CacheManager object access code required within Active Server Pages (ASP) using the CacheManager object. The cache can be either a Dictionary or LRUCache object. The following steps demonstrate the use of an LRUCache object and stores recordsets. You can use a similar cache to store HTML.

  1. Create the CacheManager object in the global.asa file.
    Dim oCacheManager

Set oCacheManager = Server.CreateObject("Commerce.Cachemanager")
oCacheManager.AppUrl = MY_APPLICATION_URL
Set Application("MSCSCacheManager") = oCacheManager

' Create a configuration dictionary for the cache.
dim dictProductCategoryCacheConfig
set dictProductCategoryCacheConfig = GetDictionary()
dictProductCategoryCacheConfig("ConnectionString") = _
                 TRANSACTION_CONFIG_CONNECTION_STRING
dictProductCategoryCacheConfig("CacheSize") = 10000
dictProductCategoryCacheConfig("TableName") = _
                 "CatalogCache_Virtual_Directory"
dictProductCategoryCacheConfig("Cachename") = PRODUCT_CATEGORY_CACHE
dictProductCategoryCacheConfig("AppURL") = MY_APPLICATION_URL

' Create and initialize the cache to use LRUCache objects.
oCacheManager.RefreshInterval(PRODUCT_CATEGORY_CACHE) = 0
oCacheManager.RetryInterval(PRODUCT_CATEGORY_CACHE) = 5 * 60
oCachemanager.CacheObjectProgId(PRODUCT_CATEGORY_CACHE) = _
                                "Commerce.LRUCache"
oCacheManager.LoaderProgID(PRODUCT_CATEGORY_CACHE) = _
                           "Commerce.LRUCacheFlush"
Set oCacheManager.LoaderConfig(PRODUCT_CATEGORY_CACHE) = _
                                      dictProductCategoryCacheConfig
' LRUCacheFlush is a cache loader component supplied
' to work specifically with LRUCaches.
  2. Get the cache in the ASP page. The CacheManager object will return a cache by name. If the requested cache does not exist, the CacheManager object will automatically create an empty one.
    ' Get a local reference to the CacheManager object on the ASP page:
Dim oCache
Dim g_MSCSCacheManager
Set g_MSCSCacheManager = Application("MSCSCacheManager")
' Get the cache from the CacheManager object:
Set oCache = g_MSCSCacheManager.getCache(PRODUCT_CATEGORY_CACHE)
  3. Perform a lookup. This example is part of a function named GetCategoriesRS that returns the child categories if given the name of the parent category. The name of the parent category, contained in the variable parentCategory, serves as the cache key.
    Dim rsChildCategories
' First, try to retrieve the child
' categories recordset from the cache.
Set rsChildCategories = oCache.Lookup(parentCategory)

' Test whether the cache returned the requested recordset.
If Not IsNull(rsChildCategories) Then
    ' It did, so return the recordset.
    Set GetCategoriesRS = rsChildCategories

Else
    ' It did not, so get it from the catalog.
    Set rsChildCategories = _
            oCatalog.GetCategory(parentCategory).ChildCategories

   ' Put the recordset in the cache for future use.
    Set oCache.Insert(parentCategory, rsChildCategories)

   ' Return the child categories recordset.
    Set GetCategoriesRS = rsChildCategories
End If


Profile Objects

Profiles represent business entities such as customers, companies, products, purchase orders, and accounts. A profile contains properties of the business entity. For example, "Joe User" is a specific customer, and the data concerning "Joe User" is stored as an instance of a customer profile. The structure of the profile is determined by its schema.

This section contains:

  • Profile Programming Concepts. Describes the Profiles resource and the objects it exposes.

  • Example Code for Profile Objects. Provides detailed examples of how to use the profile objects exposed by the Profile resource.

See Also

Business Desk Users

Profile Schema

Profile XML Structures

ProfileObject Object

Profiles

ProfileService Object

Running the Profiles Resource


Profile Programming Concepts

The following topics describe the components of the Profiles resource.

Profile Store

This is a group of tables in a Microsoft SQL Server database that stores profile definitions, site terms, and named expressions.

OLE DB Provider for Commerce Server

This is used to aggregate ProfileObject object data from multiple underlying data stores and expose the data as a single OLE DB Row object. For more information, see the OLE DB 2.5 specification in MSDN and OLE DB Provider for Commerce Server.

Profile Designer

Available through Commerce Server Business Desk, the Profile Designer provides a user interface to extend and delete current profile schemas. For more information, see Adding Properties to a Profile Definition.

ProfileObject Object

This object, also referred to simply as a profile, is used to access and modify ProfileObject object properties. For more information, see ProfileObject Object.

Profiles resource

Available through Commerce Server Manager in the Microsoft Management Console (MMC), the Profiles resource provides a user interface to create new profile schemas. For more information, see Running the Profiles Resource.

ProfileService Object

This object is used to create, retrieve, and delete ProfileObject objects. For more information, see ProfileService Object.


Example Code for Profile Objects

This section provides detailed examples of how to use the profile definitions exposed by the Profiles resource. These samples are written in Microsoft Visual Basic, Visual Basic Scripting Edition (VBScript), or Active Server Pages (ASP), and do not show error checking or certain other formalities required for functional code.

This section contains:

  • Code to Connect to the Profiles Store. Describes how to connect to the Profiles store.

  • Code to Enumerate Errors. Describes how to enumerate all errors generated by the last Profiles resource operation.

  • Code to Setup Bind Credentials to Directory Stores. Describes how to bind profiles to specific users.

  • Code to Create a New Profile. Describes how to create a new profile.

  • Code to Retrieve a Profile. Describes how to retrieve a profile.

  • Code to Modify a Profile. Describes how to modify the data stored in a profile.

  • Code to Delete a Profile. Describes how to delete a profile.

  • Code to Retrieve XML Data and Schema. Describes how to retrieve the Extensible Markup Language (XML) representations of profile data and schemas.

  • Code to Perform Bulk Operations using ADO and SQL. Describes how ActiveX Data Object (ADO) and SQL are used to perform bulk operations on profile data.


Code to Connect to the Profile Store

This section shows how to connect to the Profile Store. A SiteConfigReadOnly object provides access to the connection string. For more information about the connection string, see ProfileService.Initialize.

  1. Create a SiteConfigReadOnly object and initialize it for the "Retail" site.
    Dim oSiteConfigReadOnly
Set oSiteConfigReadOnly = Server.CreateObject _
 ("Commerce.SiteConfigReadOnly")
oSiteConfigReadOnly.Initialize "Retail"
  2. Retrieve the connection string to the Profile Store and release the SiteConfigReadOnly object.
    Dim sBDSConnect
sBDSConnect = oSiteConfigReadOnly.Fields("Biz Data Service") _
 .Value.Fields("s_ProfileServiceConnectionString").Value

Set oSiteConfigReadOnly = Nothing
  3. Create the ProfileService object and connect to the Profile Store. The Profile Definitions parameter is the catalog used for the profile schema definitions.
    Dim oProfileService
Set oProfileService = Server.CreateObject("Commerce.ProfileService")
oProfileService.Initialize sBDSConnect, "Profile Definitions"


Code to Enumerate Errors

This section shows how to enumerate any errors generated by the last Profiles resource operation, which includes any errors produced by the underlying technology. For more information, see ProfileService.Errors.

  1. If not already connected, create a ProfileService object, oProfileService, and establish a connection to the Profile Store. For information about connecting to the Profile Store, see Code to Connect to the Profile Store.

  2. Retrieve the Errors collection.
    Dim oError, oErrors
Set oErrors = oProfileService.Errors
  3. Enumerate any errors that are present.
    If oErrors.Count <> 0 Then
   For Each oError In oErrors
      Response.Write "<BR> Error number = " & oError.Number & "</BR>"
      Response.Write "<P>" & oError.Description & "</P>"
   Next
EndIf

Set oErrors = Nothing


Code to Setup Bind Credentials to Directory Stores

This section shows how to bind profiles to a specific user.

  1. If not already connected, create a ProfileService object, oProfileService, and establish a connection to the Profile Store. For information about connecting to the Profile Store, see Code to Connect to the Profile Store.

  2. Bind to a user using the full User Principal Name (UPN). Any profiles created after this binding will only be accessible by the user with the credentials user name = "someone@microsoft.com" and password = "mypassword".
    oProfileService.BindAs "someone@microsoft.com", "mypassword"
  3. Bind to a user using a SAM Account Name.
    oProfileService.BindAs "microsoft\someone", "mypassword"
  4. Bind to a user using the fully specified distinguished name of the security principal.
    oProfileService.BindAs "CN=someone,CN=Users,DC=microsoft,DC=com", _
 "mypassword"
  5. Clear the binding to access profiles not bound to a specific user.
    oProfileService.Unbind


Code to Create a New Profile

This section shows how to create a new profile. Two new profiles will be created, oUser1, a UserObject profile, and oAddress1, an Address profile.

Note

  • If the CreateProfile method fails on an aggregated profile (one that has multiple data sources), the DeleteProfile method must be called to clean up any entries in the data stores. In this case, the DeleteProfile method will produce an error that should be ignored.
  1. If not already connected, create a ProfileService object, oProfileService, and establish a connection to the Profile Store. For information about connecting to the Profile Store, see Code to Connect to the Profile Store.

  2. Create two new empty profiles (ProfileObject objects) using the ProfileService object, oProfileService, created in Step 1. For information about the valid profile schema types (specified as the second parameter of the CreateProfile method) and their associated properties, see Profile Schema. The primary key for the Address profile is a globally unique identifier (GUID), obtained through a GenID object.
    Dim oUser1, oAddress1

Set oUser1 = oProfileService.CreateProfile("JoeUser@microsoft.com", _
 "UserObject")
If err.number <> 0 Then
   oProfileService.DeleteProfile "JoeUser@microsoft.com", "UserObject"
EndIf

Dim oGenID, sGUID
Set oGenID = Server.CreateObject("Commerce.GenID")
sGUID = oGenID.GenGUIDString

Set oAddress1 = oProfileService.CreateProfile(sGUID, "Address")
  3. Populate the desired properties of the profiles. The logon_name property of the oUser1 profile is already specified (as the first parameter of the CreateProfile method). Note that ProfileObject objects support extended dot notation and smart navigation. For more information, see ProfileObject.
    oUser1.GeneralInfo.first_name = "Joe"
oUser1.GeneralInfo.last_name = "User"

oAddress1.GeneralInfo.region_code = "WA"
oAddress1.GeneralInfo.country_code = "US"
  4. Save the profiles to the underlying Profile Store.
    oUser1.Update
oAddress1.Update
  5. Release the objects.
    Set oUser1 = Nothing
Set oAddress1 = Nothing


Code to Retrieve a Profile

This section shows how to retrieve a profile.

  1. If not already connected, create a ProfileService object, oProfileService, and establish a connection to the Profile Store. For information about connecting to the Profile Store, see Code to Connect to the Profile Store.

  2. The profile object can be retrieved by specifying the schema name of the ProfileObject object, and either the primary key value or a key name/value pair. The UserObject schema type has a primary key of logon_name and a join key of user_id, which is a globally unique identifier (GUID). For information about the valid profile schema types, see Profile Schema. Retrieve the oUser1 profile created in Code to Create a New Profile.
    • Retrieve by specifying the primary key value and the schema name.
      Dim oUser1
Set oUser1 = oProfileService.GetProfile("JoeUser@microsoft.com", _
 "UserObject")
    • Retrieve by specifying a key name/value pair and the schema name.
      Set oUser1 = oProfileService.GetProfileByKey("user_id", _
 "{74A38551-FFFF-FFFF-FFFF-0A20C90DC8D1}", "UserObject")


Code to Modify a Profile

This section shows how to modify the data stored in a profile. To modify the schema of a profile (the data structure), use the Profile Designer in Commerce Server Business Desk. For more information, see Adding Properties to a Profile Definition.

  1. If not already connected, create a ProfileService object, oProfileService, and establish a connection to the Profile Store. See Code to Connect to the Profile Store.

  2. Retrieve the oUser1 profile. For more information, see Code to Retrieve a Profile.

  3. Modify the first_name and tel_number of the oUser1 profile. This example uses smart navigation instead of the Fields collection to access the profile properties. For information on the available properties for the profiles shipped with Commerce Server, see Profile Schema. Note the two different syntaxes available for accessing the properties. Both are equivalent.
    oUser1.first_name = "Joseph"
oUser1.tel_number = "(123) 456-7890"

oUser1.GeneralInfo.first_name = "Joseph"
oUser1.GeneralInfo.tel_number = "(123) 456-7890"
  4. Save the change to the Profile Store.
    oUser1.Update


Code to Delete a Profile

This section shows how to delete a profile. Care must be taken when deleting a profile due to possible expression dependencies on the deleted profile.

  1. If not already connected, create a ProfileService object, oProfileService, and establish a connection to the Profile Store. For information about connecting to the Profile Store, see Code to Connect to the Profile Store.

  2. The profile object can be deleted by specifying the schema name, and either the primary key value or a key name/value pair of the ProfileObject object. The UserObject schema type has a primary key of logon_name and a join key of user_id which is a globally unique identifier (GUID). For information on the valid profile schema types, see Profile Schema. Delete the oUser1 profile created in Code to Create a New Profile.
    • Delete by specifying the primary key value and the schema name.
      oProfileService.DeleteProfile "JoeUser@microsoft.com", "UserObject"
    • Delete by specifying a key name/value pair and the schema name.
      oProfileService.DeleteProfileByKey "user_id", _
 "{74A38551-FFFF-FFF6-FFFF-0A20C90DC8D1}", "UserObject"


Code to Retrieve XML Data and Schema

This section shows how to retrieve a list of all defined profile schema names, and how to retrieve the schema corresponding to one of these schema names. Then, the Extensible Markup Language (XML) data and schema representation of a ProfileObject object is obtained.

  1. If not already connected, create a ProfileService object, oProfileService, and establish a connection to the Profile Store. For information about connecting to the Profile Store, see Code to Connect to the Profile Store.

  2. Create an empty XML Document Object Model (DOM) document.
    Dim xmlDoc
Set xmlDoc = CreateObject("Microsoft.XMLDOM")
  3. Retrieve the XML string containing the list of all defined profile schema names and load it into the empty XML DOM document.
    xmlDoc.loadXML( oProfileService.GetProfileDefXML("", True) )
  4. Retrieve the collection of "ElementType" nodes that contain the names of the profile schemas.
    Dim xmlNodes
Set xmlNodes = xmlDoc.getElementsByTagName("ElementType")
  5. Retrieve the first profile schema name.
    Dim sSchemaName
sSchemaName = _
 xmlNodes.item(0).attributes.getNamedItem("name").nodeValue
  6. Retrieve the XML string for the schema corresponding to the first profile schema name.
    Dim sXMLSchema
sXMLSchema = oProfileService.GetProfileDefXML(sSchemaName, False)
  7. Retrieve the schema and data representation for the profile, oUser1, created in Code to Create a New Profile.
    Dim sXMLSchemaAndData
sXMLSchemaAndData = _
 oUser1.GetProfileXML(psRetrieveSchemaAndData, False)


Code to Perform Bulk Operations using ADO and SQL

This topic shows how to perform bulk operations on profile data using ActiveX Data Objects (ADO) and SQL. New profiles are added to the UserObject profile, one of the properties is then updated, and finally, all inactive accounts are deleted. For more information about the UserObject profile, see UserObject Profile Schema.

  1. Create a SiteConfigReadOnly object and initialize it for the "Retail" site.
    Dim oSiteConfigReadOnly
Set oSiteConfigReadOnly = Server.CreateObject _
 ("Commerce.SiteConfigReadOnly")
oSiteConfigReadOnly.Initialize "Retail"
  2. Retrieve the connection string to the Profile Store and release the SiteConfigReadOnly object.
    Dim sCSConnect
sCSConnect = oSiteConfigReadOnly.Fields("Biz Data Service") _
 .Value.Fields("s_CommerceProviderConnectionString").Value

Set oSiteConfigReadOnly = Nothing
  3. Create an ADO Connection object and an ADO Command object and open a connection to the Profile Store.
    Dim oConnection As New ADODB.Connection
Dim oCommand As New ADODB.Command
Set oCommand.ActiveConnection = oConnection
  4. Create and execute a query to add new profiles to the UserObject profile. Assume the data is stored in an array with the following format (not all fields are shown).
    Dim sQuery
Dim arNewCustomers()
arNewCustomers(0, 0) = "logon_name"         ' Unicode string
arNewCustomers(0, 1) = "user_type"          ' Integer
arNewCustomers(0, 2) = "date_registered"    ' {d 'YYYY-MM-DD'}
arNewCustomers(0, 3) = "org_id"             ' GUID

For i = 1 To UBound(arNewCustomers)
   sQuery = "INSERT INTO Customers (u_logon_name, " & _
                                   "i_user_type, " & _
                                   "d_date_registered, " & _
                                   "g_org_id) " & _
                       "VALUES " & (arNewCustomers(i, 0) & ", " & _
                                    arNewCustomers(i, 1) & ", " & _
                                    arNewCustomers(i, 2) & ", " & _
                                    arNewCustomers(i, 3) & ")"
   oCommand.CommandText = sQuery
   oCommand.Execute()
Next
  5. Check the procedure. If an INSERT method only partially succeeds against aggregated stores, the DeleteProfile method of the ProfileService object must be called to clean up the partially inserted data.
    Dim rsProfiles As ADODB.Recordset

sQuery = "SELECT (u_logon_name, i_user_type, d_date_registered, " & _
                  g_org_id) FROM Customers " & _
         "WHERE date_created = @today " & _
         "ORDER BY d_date_registered"

oCommand.CommandText = sQuery
Set rsProfiles = oCommand.Execute()
  6. Change the organization ID for the new customers.
    sQuery = "UPDATE Customers " & _
         "SET g_org_id = '{2B544800-4169-4C49-8713-1B794078B4C9}'" & _
         "WHERE date_created = @today"

oCommand.CommandText = sQuery
oCommand.Execute()
  7. Delete all inactive accounts.
    sQuery = "DELETE FROM Customers " &
         "WHERE i_account_status = 0"

oCommand.CommandText = sQuery
oCommand.Execute()
  8. Close the connection and release the objects.
    oConnection.Close
Set rsProfiles = Nothing
Set oConnection = Nothing
Set oCommand = Nothing


Site Security Objects

Microsoft Commerce Server 2000 provides two Component Object Model (COM) objects used for site security. The AuthManager object is used for user authentication and identification. The BizDeskSecurity object is used to determine which Commerce Server Business Desk modules to display for the current user.

The section contains:

  • Security Objects Programming Concepts. Describes concepts related to the security objects provided with Microsoft Commerce Server 2000.

  • Example Code for Site Security Objects. Provides example code that demonstrates how to use the objects related to Web site security.

See Also

Managing the CS Authentication Resource

Working with Site Security and Filters

AuthManager Object

BizDeskSecurity Object


Security Objects Programming Concepts

This section describes the BizDeskSecurity object and the AuthManager object provided by Microsoft Commerce Server 2000 for site security.

BizDeskSecurity Object

The Commerce Server Business Desk security infrastructure allows individual Business Desk modules to be displayed or hidden, depending on the credentials of the user. The CanUserAccess method of the BizDeskSecurity object returns True if the current user has read access rights for a specified Business Desk module. This method retrieves the access rights for the user from the access control list (ACL) for the file. For more information, see BizDeskSecurity Object.

The Active Server Pages (ASP) file corresponding to a Business Desk module is found in the id attribute of the module element of the XML file for the module. The XML file for each module is found in the Config folder located under the Business Desk application folder. For more information about the XML format, see Module Configuration Files.

AuthManager Object

The AuthManager object identifies users and gathers information used for user authentication. The methods and properties of this object control and access the contents of cookies and encoded URL strings. For more information, see AuthManager Object.

Authentication uses tickets, a string of property/value pairs, to provide information about the user. Two types of tickets are supported, an MSCSAuth ticket and an MSCSProfile ticket. Their differences are summarized in the following table.

Characteristics | MSCSAuth | MSCSProfile
Storage | Session cookie/encoded URL string | Persistent cookie/encoded URL string
User Type | Registered | Anonymous
Contents | Unique user ID, last login time, time window | Unique user ID

In this context, registered refers to a user who has successfully completed a registration process for the relevant site.

The AuthManager object provides methods to place the ticket into a cookie, if cookies are enabled on the client, or, if cookies are not enabled, into an encoded URL string. When used with the AuthFilter ISAPI filter, cookies must be enabled.

For an MSCSAuth ticket, the AuthManager object can check the validity of the ticket using the IsAuthenticated method. This method checks whether the request from the user contains an MSCSAuth ticket. If it does, the method checks the current time against the last login time set on the ticket to see if it is within the time window specified in the ticket. If it is, the method returns True, indicating a valid MSCSAuth ticket. If the current time is within five minutes of the last login time plus the time window, the last login time on the ticket is changed to the current time so the active user can remain browsing.

A user may have both types of tickets. In this case, the MSCSAuth ticket takes precedence.

If the user does not allow cookies, the ticket is placed in an encoded URL string. The URL string may be used to pass user information between pages and Web sites, provided all the URLs and query strings are generated by the AuthManager object.

The AuthManager object provides a transparent interface to the tickets, whether they are stored in cookies or in URL query strings, and handles encryption and decryption of the tickets to ensure security.

The AuthManager object must be used with ASP since it depends on ASP intrinsic objects. Do not create the AuthManager object in application scope as it has dependencies on individual user sessions. The AuthManager object should be created and destroyed on each ASP page.


Example Code for Site Security Objects

This section provides detailed examples of how to use the objects supplied by Commerce Server 2000 for site security. These samples are written in Microsoft Visual Basic Scripting Edition (VBScript) for Active Server Pages (ASP), and do not show error checking or certain other formalities required for functional code.

This section contains:

  • Code to Control Display of a Business Desk Module. Describes how to control whether a specified Business Desk module is displayed to the current user.

  • Code to Create and Initialize AuthManager. Describes how to instantiate and initialize the AuthManager object.

  • Code to Manipulate Site Configuration Properties. Describes how to change CS Authentication resource properties.

  • Code to Retrieve Login Credentials. Describes how to retrieve the user ID and password submitted on an HTML form using either the Get method or the Post method.

  • Code to Set a New MSCSProfile Ticket. Describes how to create an MSCSProfile ticket.

  • Code to Retrieve a Profile and Set an MSCSAuth Ticket. Describes how to retrieve a profile using the Commerce Server Profiles resource, and set an MSCSAuth ticket.

  • Code to Retrieve Login Credentials Using the Post Method and Set an MSCSAuth Ticket. Describes how to retrieve the user ID and password submitted on a HTML form using the Post method, get the profile corresponding to the user ID using the Commerce Server Profiles resource, set the user ID in an MSCSAuth ticket, and redirect the user to the originally requested URL.

  • Code to Set a Custom Property on a Ticket. Describes how to create a globally unique identifier (GUID) string and place it on an MSCSAuth ticket as a guid property.

  • Code to Generate an Encoded URL String. Describes how to generate an encoded URL string from a file name.


Code to Control Display of a Business Desk Module

This example shows how to control whether the Catalog Editor module in Commerce Server Business Desk is displayed to the current user.

  1. Open the XML file corresponding to the Catalog Editor module. When the Retail Solution Site is unpackaged to the default installation directory, this file, named Catalogs_editor.xml, will be located in the folder \Inetpub\wwwroot\retailbizdesk\config.

  2. The name of the ASP file associated with the Catalog Editor module is found in the id attribute of the module element of this file. For more information about the XML format, see Module Configuration Files.
    <module id="catalogs/editor/list_Catalogs.asp">
   <name>Catalog Editor</name>
   <tooltip>Manage Catalog Data</tooltip>
</module>
  3. Create the BizDeskSecurity object.
    Dim oBizDeskSecurity
Set oBizDeskSecurity = Server.CreateObject("Commerce.BizDeskSecurity")
  4. Pass the ASP file to the BizDeskSecurity object.
    If oBizDeskSecurity.CanUserAccess("list_Catalogs.asp") Then
   ' Display the module
End If


Code to Create and Initialize AuthManager

The AuthManager object uses site configuration resource properties. When the AuthManager object is first initialized, it creates a site cache and populates the cache with these properties. If initialized again, it checks the cache for these properties and, if they are not found, they are loaded again. An instance of the AuthManager object is created and initialized in the Global.asa file for the site (for performance reasons) and on every page that uses the AuthManager object.

  1. Create the AuthManager object. Note that the ProgID for the object is different than the object name.
    Dim oAuthManager
Set oAuthManager = Server.CreateObject("Commerce.AuthManager")
  2. Initialize the object to the Retail site.
    oAuthManager.Initialize "Retail"


Code to Manipulate Site Configuration Properties

Whenever a site configuration property used by the AuthManager object is changed, the cache storing these properties must be refreshed. For information on the SiteConfig object, see SiteConfig Object.

  1. Create a SiteConfig object and initialize it to the Retail site.
    Dim oSiteConfig
Set oSiteConfig = Server.CreateObject("Commerce.SiteConfig")
oSiteConfig.Initialize "Retail"
  2. Change the default time window to 90 seconds.
    oSiteConfig.Fields("Site CS Authentication").Value _
 .Fields("u_cookie_time_window").Value = 90

oSiteConfig.SaveConfig
  3. Create and initialize an AuthManager object.
    Dim oAuthManager
Set oAuthManager = Server.CreateObject("Commerce.AuthManager")
oAuthManager.Initialize "Retail"
  4. Refresh the site cache.
    oAuthManager.Refresh "Retail"
  5. Release the objects.
    Set oSiteConfig = Nothing
Set oAuthManager = Nothing


Code to Retrieve Login Credentials

This example shows how to retrieve the user ID and password submitted on an HTML form using either the Get method or the Post method.

  • Retrieve the credentials using the Get method.
    Dim sUserID, sPassword
If Request.QueryString("realSubmit") = "fromButton" Then
    sUserID = Request.QueryString("txtUserName")
    sPassword = Request.QueryString("txtPassword")
End If
  • Retrieve the credentials using the Post method.
    Dim sUserID, sPassword
If Request.Form("realSubmit") = "fromButton" Then
    sUserID = Request.Form("txtUserName")
    sPassword = Request.Form("txtPassword")
End If


Code to Set a New MSCSProfile Ticket

This example shows the creation of a globally unique identifier (GUID), used to identify a user, and the creation of an MSCSProfile ticket, which places the GUID on a persistent cookie for the user.

  1. Create the GenID object.
    Dim oGenID
Set oGenID = Server.CreateObject("Commerce.GenID")
  2. Create the GUID string.
    Dim sGUID
sGUID = oGenID.GenGUIDString()
  3. Using the AuthManager object, oAuthManager, created and initialized in Code to Create and Initialize AuthManager, create the MSCSProfile ticket.
    oAuthManager.SetProfileTicket sGUID, True
  4. Release the objects.
    Set oGenID = Nothing
Set oAuthManager = Nothing


Code to Retrieve a Profile and Set an MSCSAuth Ticket

This example shows how to retrieve a profile corresponding to a known user ID using the Commerce Server Profiles resource, and set the userID in an MSCSAuth ticket. For more information about using the Profiles resource, see Example Code for Profile Objects.

  1. Create and initialize the ProfileService object. The sBDSConnect parameter is the connection string to the Profile store where the profile definitions are saved.
    Dim oProfileService
Set oProfileService = Server.CreateObject("Commerce.ProfileService")
oProfileService.Initialize sBDSConnect, "Profile Definitions"
  2. Retrieve the profile associated with the user ID. If the profile does not exist, redirect the user to a login page.
    Dim oProfileObject
Set oProfileObject = oProfileService.GetProfile(sUserID, "UserObject")
If (oProfileObject Is Nothing) Then
    Response.Redirect "Login.asp"
End If
  3. Retrieve the password associated with the profile.
    Dim sProfilePassword
sProfilePassword = oProfileObject.user_security_password
  4. If the submitted password matches the profile password, set the authentication ticket using the AuthManager object, oAuthManager, created and initialized in Code to Create and Initialize AuthManager. If the passwords do not match, redirect the user to the login page.
    If sPassword = sProfilePassword Then
    oAuthManager.SetAuthTicket sUserID, True, 45
Else
    Response.Redirect "Login.asp"
End If
  5. Release the objects.
    Set oProfileService = Nothing
Set oProfileObject = Nothing
Set oAuthManager = Nothing


Code to Retrieve Login Credentials Using the Post Method and Set an MSCSAuth Ticket

This example shows how to retrieve the user ID and password submitted on a HTML form using the Post method, retrieve the profile corresponding to the user ID by using the Commerce Server Profiles resource, set the user ID in an MSCSAuth ticket, and redirect the user to the originally requested URL. Assume the user entered a user ID and password and clicked the Submit button on an HTML form. For more information about using the Profiles resource, see Example Code for Profile Objects.

  1. Make sure the request is a form submission, then retrieve the user ID and password.
    Dim sUserID, sPassword
If Request.Form("realSubmit") = "fromButton" Then
    sUserID = Request.Form("txtUserName")
    sPassword = Request.Form("txtPassword")
End If
  2. Create and initialize the ProfileService object. The sBDSConnect parameter is the connection string to the Profile store where the profile definitions are saved.
    Dim oProfileService
Set oProfileService = Server.CreateObject("Commerce.ProfileService")
oProfileService.Initialize sBDSConnect, "Profile Definitions"
  3. Retrieve the profile associated with the submitted user ID. If the profile does not exist, redirect the user to the login page.
    Dim oProfileObject
Set oProfileObject = oProfileService.GetProfile(sUserID, "UserObject")
If (oProfileObject Is Nothing) Then
    Response.Redirect "Login.asp"
End If
  4. Retrieve the password associated with the profile.
    Dim sProfilePassword
sProfilePassword = oProfileObject.user_security_password
  5. If the submitted password matches the profile password, set the authentication ticket use the AuthManager object, oAuthManager, created and initialized in Code to Create and Initialize AuthManager. If the passwords do not match, redirect the user to the login page.
    If sPassword = sProfilePassword Then
    oAuthManager.SetAuthTicket sUserID, True, 45
Else
    Response.Redirect "Login.asp"
End If
  6. Append the user ID and password to the URL string as custom properties. This step is provided for sites using the AuthFilter ISAPI filter in Windows Authentication mode and, in general, is not required. For more information about this mode and specific to this step, see Post Method.
    Dim sReturn
sReturn = Request.Cookies("MSCSFirstRequestedURL")
sReturn = sReturn & "&proxyuser=" & sUserID & "&proxypwd=" & sPassword
  7. Redirect the user to the original requested URL.
    Response.Redirect sReturn
  8. Release the objects.
    Set oProfileService = Nothing
Set oProfileObject = Nothing
Set oAuthManager = Nothing


Code to Set a Custom Property on a Ticket

This example shows how to set a custom property named guid, which holds a globally unique identifier (GUID) string on an MSCSAuth ticket. The technique is also valid for an MSCSProfile ticket and other custom properties. Setting this property is used to thwart a distributed denial of service (DDOS) attack when using the AuthFilter ISAPI filter in Windows Authentication mode. For more information about DDOS, see Distributed Denial of Service Attacks.

  1. Create the GenID object.
    Dim oGenID
Set oGenID = Server.CreateObject("Commerce.GenID")
  2. Create the GUID string.
    Dim sGUID
sGUID = oGenID.GenGUIDString()
  3. Using the AuthManager object, oAuthManager, created and initialized in Code to Create and Initialize AuthManager, place the guid property on the previously set MSCSAuth ticket. To place the property on an MSCSProfile ticket, replace the enumMSCS_AuthTicketType parameter with enumMSCS_ProfileTicketType.
    oAuthManager.SetProperty enumMSCS_AuthTicketType, "guid", sGUID
  4. Append the guid property to the URL string as a custom property and redirect the user to the originally requested URL. This step is not required for custom properties in general and is provided for completeness in the DDOS example.
    Dim sReturn
sReturn = Request.Cookies("MSCSFirstRequestedURL") & "guid=" & sGUID
Response.Redirect sReturn
  5. Release the objects.
    Set oGenID = Nothing
Set oAuthManager = Nothing


Code to Generate an Encoded URL String

This example shows how created an encoded URL string containing custom properties.

  1. Create two SafeArrays to hold the custom property/value pairs.
    Dim savProperties, savValues
  2. Populate the SafeArrays.
    savProperties(0) = "SKU"
savValues(0) = "F13B69881E"
savProperties(1) = "Quantity"
savValues(1) = 3
  3. Using the AuthManager object, oAuthManager, created and initialized in Code to Create and Initialize AuthManager, create a URL to reference the file Weeklysales.asp. The second parameter indicates cookies are disabled and causes the AuthManager object to append the user ID from the MCSCAuth ticket to the string. The third parameter indicates the URL is secure.
    Dim sURL
sURL = oAuthManager.GetURL("Weeklysales.asp", False, True, _
                           savProperties, savValues)
  4. The resulting URL string follows.
    ' sURL = https://host_name/virtual_directory/weeklysales.asp?SKU=
'        F13B69881E&Quantity=3&MSCSAuth=Q0H4SE915ASH2KC000Q79QB1E


Working with Site Security and Filters

Microsoft Commerce Server 2000 provides user authentication and identification to Web sites using an Internet Server Application Programming Interface (ISAPI) filter called the AuthFilter and a Component Object Model (COM) object called the AuthManager. The AuthFilter supports three distinct modes and two mixed modes of operation. The AuthManager object may be used with or without the AuthFilter, and can set an encrypted user ID into a cookie or encoded URL string, and validate the user against it. The AuthFilter requires cookies, however, the AuthManager object supports shopping both with and without cookies.

The authentication mode is set in Commerce Server Manager after the site is unpacked. Whenever the authentication mode or other CS Authentication resource site configuration properties are changed, Internet Information Services (IIS) must be restarted so that the AuthFilter begins using the new values. For more information, see Managing the CS Authentication Resource.

This section contains:

  • AuthFilter. Describes the ISAPI filter provided by Microsoft Commerce Server to support user authentication and identification.

  • Windows Authentication Mode. Describes the Windows Authentication mode of the AuthFilter.

  • Custom Authentication Mode. Describes the Custom Authentication mode of the AuthFilter.

  • Autocookie Mode. Describes the Autocookie mode of the AuthFilter.

  • Windows Authentication with Autocookie Mode. Describes the mixed authentication mode of Windows Authentication with Autocookie.

  • Custom Authentication with Autocookie Mode. Describes the mixed authentication mode of Custom Authentication with Autocookie.

See Also

Managing the CS Authentication Resource

AuthManager Object

Site Security Objects


AuthFilter

This section discusses the AuthFilter, the ISAPI filter provided with Commerce Server 2000. An ISAPI filter is a DLL loaded into the Internet Information Services (IIS) process when the Web service is started. The AuthFilter alters the default behavior of IIS and affects how HTTP requests and responses are handled. By default, when the filter is used, it is installed at the IIS site level with low priority. The following sections discuss the base services provided by the AuthFilter, the modes of operation it supports, and the IIS events it registers for.

This section contains:

  • Base Services

  • Modes of Operation

  • Filter Initialization

  • IIS Event Notifications

  • Single Sign On Support


Base Services

When the AuthFilter is notified of an incoming request, it automatically provides the following services regardless of the mode of operation:

  • URL correctness. Detects whether the requested URL is correct, automatically correcting for the case sensitivity of the Internet Information Services (IIS) virtual directory roots.

  • Cookie support. Checks for cookie support and, if unavailable, redirects the user to a no cookie page. Cookie support is required when using the AuthFilter.

  • Ticket validation. Checks that the user has a valid ticket. A ticket is a set of property/value pairs set in the cookie of the user and used to identify or authenticate the user.

Additional services are provided, depending on the mode of operation of the filter.


Modes of Operation

The AuthFilter supports the following modes of operation:

  • Windows Authentication mode. In this mode, the AuthFilter uses Windows Authentication — through access control lists (ACLs) — to control access to the site. Anonymous and registered users can access the site depending on the ACLs. Registered users are tracked; anonymous users are not tracked. For more information about this mode, see Windows Authentication Mode.

  • Custom Authentication mode. In this mode, the AuthFilter allows the site designer to provide a custom authentication process to control access to the site while still using the base services of the AuthFilter. For more information about this mode, see Custom Authentication Mode.

  • Autocookie mode. In this mode, the AuthFilter allows an anonymous user access to the site while storing a persistent cookie to allow tracking of the user. For more information about this mode, see Autocookie Mode.

  • Windows Authentication with Autocookie mode. This mixed mode allows both registered and anonymous users access to the site, and allows tracking of the anonymous users through persistent cookies. For more information about this mode, see Windows Authentication with Autocookie Mode.

  • Custom Authentication with Autocookie mode. This mixed mode allows both registered and anonymous users access to the site, and allows tracking of the anonymous users through persistent cookies. Instead of controlling access through Windows ACLs, the site developer can supply a custom authentication process. For more information about this mode, see Custom Authentication with Autocookie Mode.


Filter Initialization

When the first request is made to a Web site, the following steps are taken by the AuthFilter:

  1. The site name and application name are retrieved (using the physical path and the csapp.ini file).

  2. A global cache for storing site configuration authentication properties is created. There is one entry for each site, with each entry being a collection of the authentication properties for that site.

  3. The site cache is populated with the CS Authentication resource properties read from the Administration database using a SiteConfig object.


IIS Event Notifications

The AuthFilter monitors both incoming and outgoing streams of data and registers with Internet Information Services (IIS) for notification of the following events:

  • SF_NOTIFY_ORDER_LOW. Load the AuthFilter low so that authentication occurs at the end of a list of filters.

  • SF_NOTIFY_SECURE_PORT | SF_NOTIFY_NONSECURE_PORT. Support secure/non-secure requests.

  • SF_NOTIFY_PREPROC_HEADERS. A single SF_PREPROC_HEADERS event occurs for each page request signaling that the server has finished preprocessing the header and is about to begin processing the information inside the header. This is where cookie checking, and so on are performed by the AuthFilter.

  • SF_NOTIFY_URL_MAP. For mapping the URL to a physical path, correcting the URL, if required, for case sensitive virtual directory roots. Used to retrieve CS Authentication resource properties.

  • SF_NOTIFY_AUTHENTICATION. This notification is sent just before IIS attempts to authenticate the user. This is where the AuthFilter retrieves/sets the user ID and password.

  • SF_NOTIFY_ACCESS_DENIED. Access Denied. The AuthFilter redirects to a login page or error page as required

  • SF_NOTIFY_SEND_RESPONSE. Used to read proxy account information from the redirect (302) query string and store in cache. Also used to format a custom redirect header and body containing the first requested URL.

  • SF_NOTIFY_SEND_RAW_DATA. Used to filter out the original redirect request while performing a custom redirect.

  • SF_NOTIFY_END_OF_REQUEST. End of a particular request. The AuthFilter writes the custom redirect message back to the client.

  • SF_NOTIFY_END_OF_NET_SESSION. End of session; cleanup resources.


Single Sign On Support

Single Sign On (SSO) support allows a user who successfully logs on to one site or server, access to other sites and servers without having to log on again. The AuthFilter in Windows Authentication mode provides support for the following, using cookies:

  • SSO between domains. For more information, see Cookie Sharing.

  • SSO in a Web farm scenario. For more information, see Web Farms. SSO support in a Web farm is also supported in Custom Authentication mode using cookie sharing.


Windows Authentication Mode

In Windows Authentication mode, a user is validated by setting a session cookie that contains an MSCSAuth ticket. No expiration date is specified for the cookie, and the cookie is deleted after the session expires. An MSCSAuth ticket contains a user ID, the last login time, and a time window specifying how long the ticket is valid after the last login time. A validated user does not automatically have access to a requested URL. The credentials of the user, once validated, are checked against the access rights of the URL which are maintained through access control lists (ACLs).

Notes

  • When Windows Authentication mode is enabled, the security of the site is automatically set to Internet Information Services (IIS) Basic authentication. This must not be changed, as it allows the AuthFilter to be notified of events by IIS.

  • After unpacking a Solution Site for use with Commerce Server 2000, the files contained in the <SiteName>\AuthFiles folder have anonymous access enabled. If these files are not used, they should be deleted. For more information about Solution Sites, see Commerce Server Solution Sites.

This section contains:

  • URL Request Outcomes. Describes the possible outcomes when a user requests a URL: the user is sent the requested URL, is sent to a login page, or is redirected to a support page announcing cookies must be enabled. All this is transparent to the site developer.

  • Login Page. Describes the contents of the login page that must be supplied by the site developer.

  • Variations. Describes the various scenarios beyond that depicted in URL Request Outcomes, including proxy accounts, Web farms, cookie sharing, and distributed denial of service (DDOS) attacks.


URL Request Outcomes

This section and the subsequent sections describe the possible outcomes when a user requests a URL. Internet Information Services (IIS) detects the request sent by the browser and notifies the AuthFilter of the SF_NOTIFY_PREPROC_HEADERS event. At this time, the AuthFilter takes control of processing the request and performs the following actions:

  1. Checks for site configuration properties in the local site configuration cache and, if not found, reads the site configuration properties from the Administration database using a SiteConfig object and stores them in the local site configuration cache.

  2. Checks whether the URL is correct, automatically correcting for the case sensitivity of the IIS virtual directory roots.

  3. Checks for session-cookie support on the browser.

At this point, three actions are possible. The user is redirected to either a support page or a login page, or the user is sent the requested URL.

This section contains:

  • Case 1: Redirect to a Support Page. Describes the actions of the AuthFilter when session-cookie support is disabled.

  • Case 2: Send the Requested URL. Describes the actions of the AuthFilter when cookies are enabled and the requested URL has anonymous access rights, or the user has access rights to the requested URL and the returned cookie contains a valid MSCSAuth ticket.

  • Case 3: Redirect to a Login Page. Describes the actions of AuthFilter that lead to the user being redirected to a login page.


Case 1: Redirect to a Support Page

In this case, cookies are disabled. When AuthFilter discovers that session-cookies are disabled, it redirects the user to a support page that notifies the user that cookies are required and that the user should resubmit the request once cookies are enabled.

To accomplish this, the AuthFilter performs the following steps in the background after being notified by IIS that an SF_NOTIFY_PREPROC_HEADERS event has occurred:

  1. Checks for site configuration properties in the local site cache and, if not found, reads the site configuration properties from the Administration database using a SiteConfig object.

  2. Checks for session-cookie support on the browser. If session-cookies are not supported, the user is redirected to the Active Server Pages (ASP) page specified in the s_NoCookie_Form ("No-Cookie form" in the Commerce Server Manager user interface) property of the CS Authentication resource. Usually this page notifies the user that cookies are required and that the user should resubmit the request once cookies are enabled. By default, an ASP page, named nocookie.asp, is supplied for this purpose. This file is located in the AuthFiles folder in the Commerce Server installation directory.

See Also

URL Request Outcomes

Case 2: Send the Requested URL

Case 3: Redirect to a Login Page


Case 2: Send the Requested URL

In this case, cookies are enabled. The requested URL is returned to the user in either of these scenarios:

  • The returned cookie contains a valid MSCSAuth ticket and the user has access rights to the requested URL, or

  • The returned cookie does not contain an MSCSAuth ticket but the requested URL has anonymous access rights.

To accomplish this, the AuthFilter performs the following steps in the background after being notified by IIS that an SF_NOTIFY_PREPROC_HEADERS event has occurred:

  1. Checks for site configuration properties in the local site cache and, if not found, reads the site configuration properties from the Administration database using a SiteConfig object.

  2. Sends a cookie with an MSCSFirstRequestedURL property set to the originally requested URL.

  3. If the returned cookie does not contain an MSCSAuth ticket, processing is returned to IIS.

  4. If the requested URL has anonymous access rights, the URL is returned.

  5. If the cookie contains an MSCSAuth ticket, the AuthFilter checks the local password cache for an entry matching the user ID contained in the cookie.

  6. On finding a matching entry, the AuthFilter checks the current time against the last login time set on the ticket to see if it is within the time window specified in the ticket. If the current time is within five minutes of the last login time plus the time window, the last login time on the ticket is changed to the current time so an active user can remain browsing.

  7. Since the current time is within the time window, the ticket is considered valid, and the user ID and password are submitted to IIS for access to the requested URL.

  8. Since the user has access rights to the requested URL, IIS returns the page.

See Also

URL Request Outcomes

Case 1: Redirect to a Support Page

Case 3: Redirect to a Login Page


Case 3: Redirect to a Login Page

In this case, cookies are enabled. The AuthFilter redirects the user to a login form for any of these scenarios:

  • The returned cookie does not contain an MSCSAuth ticket and the requested URL does not have anonymous access rights.

  • The returned cookie contains an invalid MSCSAuth ticket.

  • The returned cookie contains a valid MSCSAuth ticket but the user does not have access rights to the requested URL. The Active Server Pages (ASP) page to which the user should be redirected is specified in the s_Logon_Form ("Login Form" in the Commerce Server Manager user interface) property of the CS Authentication resource.

To accomplish this, the AuthFilter performs the following steps in the background after being notified by IIS that an SF_NOTIFY_PREPROC_HEADERS event has occurred:.

  1. Checks for site configuration properties in the local site cache and, if not found, reads the site configuration properties from the Administration database using a SiteConfig object.

  2. Sends a cookie with an MSCSFirstRequestedURL property set to the originally requested URL.

  3. If the returned cookie does not contain an MSCSAuth ticket, processing is returned to IIS.

  4. The requested URL does not have anonymous access rights, IIS signals the AuthFilter of the SF_NOTIFY_ACCESS_DENIED event, and the user is redirected to either a login page or an error page, as required.

  5. If the cookie does contain an MSCSAuth ticket, the AuthFilter checks the password cache for an entry matching the user ID contained in the cookie.

  6. If a matching entry is not found, the user is redirected to the login page.

  7. If a matching entry is found, the AuthFilter checks the current time against the login time to see if it is within the time window specified in the ticket.

  8. If the current time is past the time window specified in the ticket, the user is redirected to the login page.

  9. If the current time is within the time window, the ticket is considered valid, and the user ID and password are submitted to IIS for access to the requested URL.

  10. The user does not have access rights to the requested URL, IIS issues a SF_NOTIFY_ACCESS_DENIED notification, and the AuthFilter redirects the user to a login page.

For information about the events on the login page, see Login Page.

See Also

URL Request Outcomes

Case 1: Redirect to a Support Page

Case 2: Send the Requested URL


Login Page

All the steps in URL Request Outcomes, are transparent to the site developer. The following actions take place in the login page, which must be supplied by the site developer. The login page is specified in the s_Logon_Form ("Login Form" in the Commerce Server Manager user interface) property of the CS Authentication resource. A default page, Login.asp, showing much of this functionality is supplied with the installed product and located under the \Microsoft Commerce Server\AuthFiles folder.

When the user requests the login page and the request is not a form submission, the page is sent to the user. The login page must have anonymous access rights because, at this point, the user is unauthenticated. The login page has a link to a registration page for new users. The user submits the login form containing the user ID and password. If either of these credentials is missing, the user is redirected back to the login page. The AuthFilter performs different actions depending on whether the submission was through the Get method or the Post method.

Note

  • For performance reasons, do not set any persistent cookies on the login page.

This section contains:

  • Get Method

  • Post Method


Get Method

When the Get method is used, the submitted user ID and password are placed in the HTTP header and are available to the AuthFilter when it receives the SF_NOTIFY_PREPROC_HEADERS event. This occurs before the login page processes the request.

The following steps are taken:

  1. The AuthFilter retrieves the submitted user ID and password from the QueryString collection properties, txtUserName and txtPassword.

  2. The AuthFilter checks the local password cache for an entry matching the user ID.

  3. If an entry is found, the password is updated with the submitted password.

  4. If an entry is not found, a new entry is made using the submitted user ID and password.

  5. The AuthFilter returns processing to the login page.

  6. In the login page, the submitted user ID and password are retrieved from the txtUserName and txtPassword properties of the QueryString collection of the Request object.

  7. Using the submitted user ID, the profile of the user is retrieved from the Commerce Server Profiles resource or another profile system.

  8. If the user does not have a profile, the user is redirected to the registration page.

  9. If the user has a profile, but the password associated with the profile does not match the submitted password, the login page is resent to the user.

  10. If the passwords do match, the AuthManager object is used to set the MSCSAuth ticket into a session cookie for the user.

  11. The user is redirected to the original URL, which was previously stored by the AuthFilter in the MSCSFirstRequestedURL property of a separate session cookie.

  12. When the browser resubmits the request, the AuthFilter determines the ticket is valid and returns processing to IIS.

  13. If the user has access rights to the URL, it is returned.


Post Method

When the Post method is used, the submitted user ID and password are placed in the HTTP body and are not available to the AuthFilter until after the login page processes the request. This requires an additional step beyond those used when processing a request that uses the Get method. This step entails appending the user ID and password to the URL query string. For a code example showing these steps, see Code to Retrieve Login Credentials Using the Post Method and Set an MSCSAuth Ticket.

The following steps are taken:

  1. Initially, the submitted user ID and password are unavailable to the AuthFilter and processing is immediately returned to the login page.

  2. In the login page, the submitted user ID and password are retrieved from the txtUserName and txtPassword properties of the Form collection of the Request object.

  3. Using the submitted user ID, the profile of the user is retrieved from the Commerce Server Profiles resource or another profile system.

  4. If the user does not have a profile, the user is redirected to the registration page.

  5. If the user does have a profile, but the password associated with the profile does not match the submitted password, the login page is resent to the user.

  6. If the passwords do match, the AuthManager object is used to set the MSCSAuth ticket into a session cookie for the user.

  7. The user ID and password are appended to the original URL query string, which was previously stored by the AuthFilter in the MSCSFirstRequestedURL property of a separate session cookie, using two properties, proxyuser and proxypwd. The query string resembles the following:
       "<MSCSFirstRequestedURL>&proxyuser=UserID&proxypwd=Password"
  8. The user is redirected to the original URL.

  9. IIS notifies the AuthFilter that it is sending the redirect response by signaling the SF_NOTIFY_SEND_RESPONSE event.

  10. The AuthFilter removes the user ID and password from the URL query string. The credentials are not sent to the browser.

  11. The AuthFilter checks for the user ID in the password cache and, if found, updates the password.

  12. If the user ID is not found, a new entry is made using the user ID and password.

  13. When the browser resubmits the request, the AuthFilter determines the ticket is valid and returns processing to IIS.

  14. If the user has access rights to the requested URL, it is returned.


Variations

A number of variations on the basic scenario depicted in URL Request Outcomes are supported and described in the following sections.

This section contains:

  • Clear Text Password in Active Directory

  • Cookie Sharing

  • Distributed Denial of Service Attacks

  • Proxy Accounts

  • Web Farms


Clear Text Password in Active Directory

The password of a user in Active Directory is stored encrypted. To have access to this password in clear text, two options are available when the password is initially retrieved in the login page:

  1. Extend the profile schema by adding a new property to store the clear text password. Extending the schema must be performed through the Profile Designer in Commerce Server Business Desk. For information about this procedure, see Adding Properties to a Profile Definition.

  2. Create a custom cache to store the clear text password.


Cookie Sharing

Users can be tracked across multiple domains and applications by sharing cookies. Cookie sharing is accomplished by setting two properties on the cookie, domain and path. This resembles the following:

      ";domain=DomainName;path=Path"

The domain property is used to specify the domains for which the cookie is valid. The path property is used to specify the subset of URLs in the domain for which the cookie is valid.

Before sending a request, the client browser checks to see if a cookie is available containing a domain property that matches the tail of the fully qualified domain name of the host specified in the requested URL. If such a cookie exists, the path property of the cookie is compared to the path name component of the requested URL. If they match, the cookie is sent with the request.

On the server side, while setting the property, if the value of the domain property is not specified, it defaults to the host name of the server that generated the cookie. Only hosts within the specified domain can set the domain property on the cookie. The most general path property is '/'. If the path property is not specified, it defaults to the path of the virtual root of the IIS application that generated the cookie. For more information about cookie sharing, see http://www.cis.ohio-state.edu/htbin/rfc/RFC2109.html.

In Commerce Server 2000, each site has its own cookies by default, however, the AuthFilter allows these cookies to be shared.

To share cookies between sites in the same domain, set the b_CookiePath_ApplicationScope property (uncheck the "Set cookie path to application" check box in the Commerce Server Manager user interface) to False. This causes the host to set the path property to '/'. If the b_CookiePath_ApplicationScope property is True, the path property is set to the current application path.

To share cookies between domains, set the u_CookieDomain_Scope property ("Number of shared domain levels" in the Commerce Server Manager user interface) to the required number. For more information, see RFC2109.


Distributed Denial of Service Attacks

A distributed denial of service (DDOS) attack is an attempt to shut down a server by repeatedly logging on with a known valid user ID and incorrect password. By default, the AuthFilter does not associate each password cache entry with one, and only one, client session. When a user logs on with a valid user ID, the password cache is updated with the submitted password. A malicious user can use this technique to disrupt service. The malicious user does not gain entry to the site, but forces a registered user that is active when the password is changed, to login again.

To avoid the attack, the AuthFilter can store an additional property in the cache besides the user ID and password. This property is generally a globally unique identifier (GUID) and is used to distinguish between different client sessions using the same user ID and possibly different passwords.

On the login page, the GUID is placed on the ticket of the user as a custom property, guid, by the SetProperty method of the AuthManager object. Additionally, the property is appended to the query string for the redirected URL.

Once set, the AuthFilter uses the guid property to access the password cache instead of the user ID. When a user logs on with the same user ID but with a different password, the AuthFilter identifies this as a different user and a new entry is made in the password cache instead of overwriting the original password. The AuthFilter then follows the same steps as for a new user. For a code example showing this process, see Code to Set a Custom Property on a Ticket.


Proxy Accounts

When accessing a site using a proxy account, the steps in the login page happen the same as with the Post method. However, the user ID is used to retrieve a proxy account ID and password, and these credentials are set into the URL query string and stored in the password cache instead of the user ID and password. On subsequent visits to the site, the proxy account ID, instead of the user ID, is used to access the password cache.

The proxy account credentials can be stored in an extended property of the default profile schema or by some other means. Extending the profile schema must be performed through the Profile Designer in Commerce Server Business Desk. For information about this procedure, see Adding Properties to a Profile Definition.

To track individual users when using proxy accounts, add the custom guid property to the ticket using the AuthManager object. Once set, the AuthFilter uses the guid property to access the password cache instead of the proxy account ID. For more information about this technique, see Distributed Denial of Service Attacks.


Web Farms

On a Web farm, the AuthFilter allows an authenticated user on one server access to a site on another server without the user having to resubmit login information. However, if the request is sent with the Post method using non-sticky load balancing, any information contained in the header body is lost during the required redirection. Only use the Post method with sticky load balancing. If using non-sticky load balancing, always use the Get method (and HTTPS if concerned about security).

When using the AuthFilter, follow these deployment scenarios:

  • Have all sites in the same directory, for example, www.microsoft.com/bookstore and www.microsoft.com/msdn. Do not have one site in the subdirectory of another site, for example, www.microsoft.com and www.microsoft.com/bookstore.

  • Use dissimilar names for sites in the same directory. A site name should not be a subset of another site name, for example, www.microsoft.com/retail and www.microsoft.com/retail2.

These requirements are due to the dependence of the AuthFilter on cookies. If the AuthFilter is not used and the ticket is placed in a URL query string, a site can be in a subdirectory of another site.

When the authenticated user arrives at a new server for the first time, the following steps are performed:

  1. The AuthFilter checks for the correct URL (auto-corrects for case sensitivity).

  2. The AuthFilter checks for session-cookie support.

  3. The AuthFilter checks for the MSCSAuth ticket.

  4. The AuthFilter checks that the MSCSAuth ticket is valid (by comparing the current time to the last login time plus the time window specified on the ticket).

  5. Since the password cache is not shared between hosts, and this is the first time the user visited this site, there is no entry in the cache corresponding to the user ID in the ticket. Detecting this, the AuthFilter resets the MSCSFirstRequestedURL cookie property to the current requested URL.

  6. Processing is passed to the login page.

  7. On the login page, once it is verified that this is not a Submit action and the user has a valid MSCSAuth ticket, the user ID is retrieved from the ticket and used to retrieve the profile of the user.

  8. The password of the user is retrieved from the profile and appended to the requested URL query string along with the user ID. The password must be available in clear text. For more information about using a clear text password, see Clear Text Password in Active Directory.

  9. The user is redirected to the requested URL and, when notified of the event by IIS, the AuthFilter removes the user ID and password from the query string and places them into the cache.

  10. When the browser resubmits the request, the AuthFilter checks the cache, finds the corresponding entry, and checks if the current time is within the time window.

  11. If the current time is within the time window, the AuthFilter passes processing to IIS.

  12. If the user has access rights to the requested URL, it is processed and returned by IIS.

Web Farms Using Proxy Accounts

Consider a user, with a valid ticket which contains a proxy account ID, who visits a new site on a Web farm. The AuthFilter uses the proxy account ID to retrieve the profile of the user. Since the proxy account ID does not have a profile associated with it, the ticket is considered invalid. The user is denied access and is redirected to the login page. For more information, see Proxy Accounts.

To circumvent this, add the custom guid property to the ticket using the AuthManager object. Once set, the AuthFilter uses the guid property to access the password cache instead of the proxy account ID. When the GUID is not found in the password cache, the AuthFilter uses the user ID from the MSCSAuth ticket, instead of the proxy account ID, to look up the profile. In this case, the profile should exist, and the user is redirected to the originally requested URL. For more information about this technique, see Distributed Denial of Service Attacks.


Custom Authentication Mode

This operating mode of the AuthFilter ISAPI filter allows the site developer to provide custom authentication services while still using the base services of the AuthFilter.

In this mode, the AuthFilter performs the following steps after being notified that an SF_NOTIFY_PREPROC_HEADERS event has occurred:

  1. Checks for site configuration properties in the local site cache and, if not found, reads the site configuration properties from the Administration database using a SiteConfig object and stores them in the site cache.

  2. Detects whether the requested URL is correct, and automatically corrects for case sensitivity in the URL.

  3. Checks for session-cookie support, and, if unavailable, redirects the user to the Active Server Pages (ASP) page specified in the s_NoCookie_Form ("No-Cookie form" in the Commerce Server Manager user interface) property of the CS Authentication resource. Usually this page notifies the user that cookies are required and that the user should resubmit the request once cookies are enabled.

  4. Checks whether the cookie contains an MSCSAuth ticket, and if not redirects the user to a login page.

  5. If the cookie contains an MSCSAuth ticket, checks the current time against the last login time on the ticket to see if it is within the time window specified in the ticket.

  6. If the current time is past the time window specified in the ticket, the user is redirected to the login page as an non-validated user.

  7. If the current time is within the time window, the ticket is considered valid, and the user is redirected to the login page as a validated user. If the current time is within five minutes of the last login time plus the time window, the last login time on the ticket is changed to the current time so an active user can remain browsing.


Autocookie Mode

Autocookie mode allows anonymous users to be tracked between pages and across sessions. A unique ID is generated to identify the user and, if required, a profile is created to store information about the user. For a code example showing these steps, see Code to Set a New MSCSProfile Ticket.

When a user sends a request to access a site, the AuthFilter ISAPI filter performs the following steps after being notified by Internet Information Services (IIS) that an SF_NOTIFY_PREPROC_HEADERS event has occurred:

  1. Checks for site configuration properties in the local site cache and, if not found, reads the site configuration properties from the Administration database using a SiteConfig object and store them in the site cache.

  2. Checks whether the URL is correct, automatically correcting for case sensitivities.

  3. Checks for cookie support on the browser.

  4. If cookies are not supported, the user is redirected to the Active Server Pages (ASP) page specified in the s_NoCookie_Form ("No-Cookie form" in the Commerce Server Manager user interface) property of the CS Authentication resource. Usually this page notifies the user that cookies are required and that the user should resubmit the request once cookies are enabled. By default, an ASP page, named nocookie.asp, is supplied for this purpose. This file is located in the AuthFiles folder in the Commerce Server installation directory.

  5. If a cookie is returned, the AuthFilter checks whether it contains an MSCSProfile ticket.

  6. If the MSCSProfile ticket exists, the AuthFilter uses a valid Windows user account to impersonate the user in IIS.

  7. If the requested URL has anonymous access rights, the URL is returned.

  8. If the ticket does not exist, the user is redirected to the ASP page specified in the s_AutoCookie_Form ("AutoCookie Form" in the Commerce Server Manager user interface) property of the CS Authentication resource.

AutoCookie Page

All the preceding steps are transparent to the site developer. The following actions take place in the autocookie page, which must be supplied by the site developer:

  1. Persistent cookie support is checked, and if unavailable, the user is redirected to the no-cookie page.

  2. If persistent cookie support is enabled, a globally unique identifier (GUID) or another unique ID is created to identify the user.

  3. The unique ID is set into an MSCSProfile ticket for the user.

  4. At this point a profile can be created to store information about the anonymous user.

  5. The user is redirected to the requested URL.

A default page, autocookie.asp, showing much of this functionality is supplied with the installed product and located in the \Microsoft Commerce Server\AuthFiles folder.


Windows Authentication with Autocookie Mode

This topic describes the mixed authentication mode of Windows Authentication with Autocookie. This mode accepts both anonymous and registered users and allows tracking of both types. This mode is useful for sites where part of the content is available to everyone and the rest is available only to registered users.

The primary differences between this mixed mode and Windows Authentication mode are as follows:

  • The mixed mode allows tracking of anonymous users.

  • In mixed mode, an anonymous user must have a valid MSCSProfile ticket to access any URLs regardless of the access control list (ACL) settings. In Windows Authentication mode, an anonymous user does not need a ticket and can access any URL with anonymous access rights.

For more information about Window Authentication mode, see Window Authentication Mode. For more information about Autocookie mode, see Autocookie Mode.

Anonymous Users Who Register

A user who visits a site anonymously receives an MSCSProfile ticket. If the user decides to register, they receive an MSCSAuth ticket. The user now has two cookies in the HTTP header containing different tickets. The order of the tickets is unknown and can vary between requests. The AuthFilter is aware of this and automatically searches all cookies for an MSCSAuth ticket before searching for an MSCSProfile ticket.

Both cookies get logged in the Web log file in the order they appear in the HTTP request header. The Web server log import DTS task imports the first cookie it finds. The one user can appear to be two users to the DTS task if it finds hits in the log file with the cookies in different orders. This compromises the ability to track the user and may produce erroneous visit and user calculations.

The solution is to map the user IDs from both the MSCSAuth ticket and the MSCSProfile ticket to the same user ID. Then set the MSCSProfile ticket to an empty string, which causes the MSCSProfile ticket to be deleted.


Custom Authentication with Autocookie Mode

This section describes the mixed authentication mode of Custom Authentication with Autocookie. This mixed mode allows both registered and anonymous users access to the site, and allows tracking of the anonymous users through persistent cookies. Instead of controlling access through Windows access control lists (ACLs), the site developer can supply a custom authentication process.

Anonymous access is enabled by performing the following steps:

  1. Set the CS Authentication resource property, b_CookiePath_ApplicationScope (uncheck the "Set cookie path to application" check box in the Commerce Server Manager user interface), to False.

  2. On the login page, provide a link to a separate virtual directory root that is not under the current virtual directory root. Keep all of the anonymous access content under this separate virtual directory root.


Working with Pipelines

A Commerce Server 2000 pipeline is a software infrastructure that links one or more components and runs them in sequence. Commerce Server 2000 uses this infrastructure to implement three pipeline models: the Order Processing pipeline (OPP), the Direct Mailer pipeline, and the Content Selection pipeline.

This section contains:

  • Pipeline Basics. Describes the basic features of Commerce Server 2000 pipelines.

  • Pipeline Editor. Explains how to use the Pipeline Editor to create pipelines from templates, modify existing pipelines by changing properties, and how to create custom pipelines.

  • Order Processing Pipeline. Describes the various types of Commerce Server 2000 Order Processing pipelines and enhancements to those pipelines, and provides a reference to the stages and components in Order Processing pipelines.

  • Direct Mailer Pipeline. Describes the stages and components used in the Direct Mailer pipeline.

  • Content Selection Pipelines. Describes the stages and components used in the Content Selection pipeline that are used for selecting ads, determining discounts, and adding personalization to pages.

  • Pooled Pipelines. Explains how to use pooled pipelines.

See Also

Pipeline Objects

Types of Pipelines


Pipeline Basics

A pipeline is a software infrastructure that defines and links one or more stages of a business process, running them in sequence to complete a specific task. Pipelines divide processing into stages, abstractions that describe a category of work. They also determine the sequence in which each category of work is performed.

Each stage of a pipeline contains one or more pipeline components (COM objects) that can be configured to work with the unique requirements of the site. For example, a typical Order Processing pipeline may include a Shopper Information stage, a Payment stage, and a Shipping stage.

Pipeline configuration files (.pcf) define pipelines. The pipeline specified by the file is created and run by a pipeline object. Commerce Server 2000 provides six objects to execute pipelines: MtsPipeline, MtsTxPipeline, PooledPipeline, PooledTxPipeline, OrderGroup, and OrderPipeline. The MtsPipeline and PooledPipeline objects do not support transactions. The MtsTxPipeline and PooledTxPipeline objects do support transactions.

Note

  • In Commerce Server 2000, pipelines are often called indirectly through the RunPipe method of the OrderGroup object.

Pipeline configuration files (.pcf files) are usually marked in one of three ways:

  • Any pipeline. May be loaded into any pipeline.

  • Requires transacted pipeline. Must be loaded into an MtsTxPipeline or PooledTxPipeline pipeline.

  • Requires a non-transacted pipeline. Must be loaded into an MtsPipeline, PooledPipeline, or OrderPipeline pipeline.

The pooled pipelines take advantage of COM+ object pooling to speed up pipeline loading and execution. For more information, see Pooled Pipelines.

Notes

  • Microsoft Application Center 2000 Component Load Balancing (CLB) can be used with Commerce Server pooled pipelines. Setup registers the Commerce Server pipeline as a COM+ package. In order to use it with CLB, you must go into the Component Services Microsoft Management Console (MMC) and change the Activation type of the package from "Library application" to "Server application." The pipeline object itself will be pooled by CLB, but pipeline components are not load balanced. This means that you cannot register any component that runs inside of a pooled pipeline as a COM+ application.

  • Setup also registers the Commerce Predictor Build Watcher component and the Commerce Event Logging component in COM+ packages. However, neither package should be used with CLB. These packages are created so that they can be used for administrative alert monitoring with distributed COM (DCOM), but there is no benefit to using them with CLB.

Designing Pipelines for Your Site

As the designer of the pipelines for your site, you take measures to ensure that the pipelines function correctly. First, you should ensure that no pipeline component is configured to overwrite the work done by another component.

Second, you define the circumstances under which the pipeline is to stop processing. As each component in the pipeline executes, it returns a status that indicates success, a warning, or failure. If you configure a stage to tolerate warnings, the pipeline continues to operate despite a warning generated by that component. If you configure a stage to tolerate only success, and the component returns a warning, the pipeline stops processing, and returns an error.


Pipeline Editor

The Pipeline Editor is an application used for editing Commerce Server pipelines. You can use it to edit a pipeline on your local computer or on a computer connected to a local area network (LAN).

Pipelines are described in pipeline configuration (.pcf) files. You create and configure .pcf files with the Pipeline Editor.

The Pipeline Editor displays a pipeline as a pipe, showing the stages of the pipeline as pipe segments. The components used in a stage appear as valves.

This screenshot depicts the Pipeline Editor with callouts that label stages and components

Click the illustration to enlarge or reduce.

Certain components have an affinity with certain stages. This means that the component can function within that stage. Commerce Server does not enforce this stage and component association. You may include any component in any stage.

Note

  • If you use the Pipeline Editor to display the components having an affinity with a given stage, you will see the Money Converter and Scriptor components. These components have an affinity with all stages.

This section contains:

  • Starting the Pipeline Editor. Describes how to start the Pipeline Editor and load an existing pipeline configuration file.

  • Creating a New Pipeline. Describes how to use the pipeline configuration templates (.pct) to create a new pipeline.

  • Adding a Component to a Pipeline. Describes how to add a component to a stage of a pipeline configuration.

  • Changing the Order of Components in a Pipeline Stage. Describes how to move components up or down within a pipeline stage.

  • Creating a List of Values Read and Written. Describes how to create a list of values the pipeline reads from and writes to the various dictionaries.

  • Using the Pipeline Editor Property Pages. Describes how to modify the properties — such as names and currency settings — of the various elements of a pipeline.

  • Creating a Custom Pipeline. Describes the process of creating a pipeline that does not use one of the standard templates.


Starting the Pipeline Editor

The following procedure describes how to start the Pipeline Editor.

To start the Pipeline Editor

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2000, and then click Pipeline Editor.

  2. On the File menu, click Open.

  3. Select the .pcf file for the pipeline you want to edit, and then click Open.

  4. The Pipeline Editor opens containing the .pcf file you selected to edit.

See Also

Creating a New Pipeline

Creating a Custom Pipeline


Creating a New Pipeline

Commerce Server 2000 provides the following standard templates on which you can base a new pipeline. The template files for creating new pipelines have the .pct file extension (pipeline configuration template). When you save the new template, it is saved with the standard pipeline configuration file (.pcf) extension.

Template name | Description
ContentSelection.pct | Seven-stage pipeline used to select content for advertising, promotions, and personalization. Contains the following stages: Load Context, Filter, Initial Score, Scoring, Select, Record, Format.
Empty.pct | Empty pipeline.
EventProcessing.pct | Three-stage event recording pipeline used to track ads, promotions, and sales for schedule updating. Contains the following stages: Load Context, Record, and Format.
Plan.pct | Fourteen-stage Order Processing pipeline (OPP) used to calculate the amount of an order in a retail scenario. Contains the following stages: Product Info, Merchant Information, Shopper Information, Order Initialization, Order Check, Item Price, Item Adjust Price, Order Adjust Price, Order Subtotal, Shipping, Handling, Tax, Order Total, and Inventory.
Product.pct | Five-stage OPP used to check factors affecting the price of a product. Contains the following stages: Product Info, Shopper Information, Item Price, Item Adjust Price, and Inventory.
Purchase.pct | Three-stage OPP. Accepts the final purchase information. Contains the following stages: Purchase Check, Payment, and Accept.
Test.pct | One-stage pipeline. Contains the Test stage.

The template provides a pre-configured pipeline. You can change the names of stages, and delete or add stages.

You can add or delete any component in any stage.

To create a new pipeline

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2000, and then click Pipeline Editor.

  2. On the File menu, click New.

  3. In the Choose a Pipeline Template dialog box, select a template, and then click OK.

  4. Modify the pipeline as necessary.

  5. On the File menu, click Save As, enter the name of the file in the File name box, and then click Save.

See Also

Adding a Component to a Pipeline

Changing the Order of Components in a Pipeline Stage

Creating a List of Values Read and Written

Using the Pipeline Editor Property Pages

Creating a Custom Pipeline


Adding a Component to a Pipeline

Using the Pipeline Editor, you can add a component to any stage in a pipeline. However, the values a particular component needs must exist in the order form before the component can successfully complete its function. You need to ensure that the components in the preceding stages have written the necessary values to the order form before the stage where you insert a component needing those values.

To add a component to a pipeline using the Pipeline Editor

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2000, and then click Pipeline Editor.

  2. On the File menu, click Open, and then select the pipeline you want to modify.

  3. Do one of the following:
    • Right-click the name of the stage where you want to insert the component, and then click Insert Component. The Choose a component dialog box appears.

      Or

    • Right-click the name of an existing component within that stage, point to Insert Component, and then click either Before or After. The Choose a component dialog box appears.
  4. In the Choose a component dialog box, do the following:
    Use this | To do this
    Stages | Select a stage option.
    Components Select a component.

    Note

    • The stage option you choose determines which components are displayed in the Components area. The default value is the name of the stage where you are inserting the component; selecting this option displays only those components that are used in that stage. Selecting All displays all components, regardless of the stage in which they are normally used.

  5. In the Components list, select the name of the component you want to insert, and then click OK.

  6. To configure the new component, right-click the component, and then click Properties.

    The Stage Properties dialog box appears.

  7. In the Stage Properties dialog box, do the following:
    Use this | To do this
    Label | Type a name for the stage.
    Description | Type a description for the stage.
    GUID | Type a globally unique identifier for the stage.
    Mode Specify the mode for the stage for compatibility with Site Server 3.0 Commerce Edition.

    Note

    • The Mode field is provided for compatibility with Site Server 3.0 Commerce Edition pipelines, in which a number identifies which stages of a pipeline are to be run by the RunProduct, RunPlan, and RunPurchase methods of the Page object. Use 1 for RunProduct, 2 for RunPlan, and 4 for RunPurchase. A value of zero (0) prevents the stage from running.
    Error level Specify the error level for the stage.

    For more information about error level values, see Error Levels.

    Note

    • When any component in the stage generates an error at or above the level specified in the Error level box, the stage stops running and generates an error.

  8. Click Apply, and then click OK.

  9. On the File menu, click Save.

See Also

Changing the Order of Components in a Pipeline Stage

Creating a List of Values Read and Written

Using the Pipeline Editor Property Pages


Changing the Order of Components in a Pipeline Stage

You can move a component up or down within its stage by using the up and down arrow buttons in the Pipeline Editor.

To move a component in the Pipeline Editor

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2000, and then click Pipeline Editor.

  2. On the File menu, click Open, and then select the pipeline you want to modify.

  3. Right-click the name of the component, and then click either Move Down or Move Up.

  4. On the File menu, click Save.

See Also

Adding a Component to a Pipeline


Creating a List of Values Read and Written

Each component in a pipeline reads values from the order form, performs its function, and then writes values to the order form. Components that execute later in the pipeline often read values that previous components have written to the order form. When you are modifying a pipeline or creating a new one, it can be helpful to see a list of the values that each component reads and writes so that you can ensure that the necessary values are present at each point.

With the Pipeline Editor, you can create a text file that lists each component of a pipeline in the order in which it is executed. The text file lists all of the components executed by the pipeline, including the required components. (The required component always executes last in a stage.) For each component, the file lists the following information:

  • Input values (values read)

  • Output values (values written)

  • Context values (values read from the PipeContext Dictionary object, which is passed as a parameter to the pipeline object's Execute method)

To create a list of all values read and written

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2000, and then click Pipeline Editor.

  2. On the File menu, click Open, and then select the pipeline you want to modify.

  3. On the File menu, click Save Values Read & Written.

  4. In the Save as dialog box, specify a location and a file name for the text file, and then click Save.

The Pipeline Editor saves the file and opens it in Microsoft Notepad.

See Also

Adding a Component to a Pipeline

Using the Pipeline Editor Property Pages


Using the Pipeline Editor Property Pages

The Pipeline Editor provide an easy interface for viewing and modifying the properties for pipelines, stages, and components.

You use the following dialog boxes to edit the properties for pipelines, stages, and components.

Element | Dialog Box | Description
Pipeline | Pipe Properties | Pipeline name, the type of pipeline the .pcf file can be used with, currency and LCID settings, and comments.
Stage | Stage Properties | Stage name, description, GUID, mode and error level settings, and comments.
Component | Component Properties, Values Read and Written, component-specific pages | Component name, Class ID, ProgID, description, values read from and written to the order form, and values read from the Context dictionary object. A component that has configurable properties may have an additional property page whose options are specific to that component.

To view properties in the Pipeline Editor

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2000, and then click Pipeline Editor.

  2. In the Pipeline Editor, right-click the name of the pipeline, stage, or component whose properties you want to view, and then click Properties.

The properties for the pipeline, stage, or component you want to view appear in the Pipeline Editor.

This section contains:

  • Pipeline Properties. Describes how to change properties of the pipeline as a whole, and how to change specific properties in the Pipeline Properties dialog box.

  • Stage Properties. Describes how to change the properties of a stage.

  • Component Properties. Describes how to change the properties of an individual component.

  • Values Read and Written Properties. Describes how to view the values read and written properties for an individual component.

  • Creation Error Properties. Describes the error dialog box that appears when a pipeline component cannot be loaded.


Pipeline Properties

Use the Pipeline Properties dialog box to change the name of the pipeline, specify its transaction compatability, currency mode, or save notes about the pipeline.

The following properties are available in the Pipeline Properties dialog box:

  • Label. Specifies the name that the Pipeline Editor displays for this pipeline. You can change the name by typing a new name.

  • Transaction Compatibility. Specifies what pipeline object this configuration file can be used with. The options are:
    • Any pipeline. Indicates that this configuration file can be used with an OrderPipeline object, with non-transacted pipeline objects (PooledPipeline, MtsPipeline), or with transacted pipeline objects (PooledTxPipeline, MtsTxPipeline).

    • Requires a transacted pipeline (MtsTxPipeline). Indicates that this configuration file can be used only with a transacted pipeline object (PooledTxPipeline, MtsTxPipeline). Transacted pipeline objects are registered with Microsoft Transaction Server (MTS) as transactions required, and hold a transaction that spans all components in the pipeline.

    • Requires a non-transacted pipeline (MtsPipeline). Indicates that this configuration file can be used only with a non-transacted pipeline object (PooledPipeline, MtsPipeline, and OrderPipeline). Non-transacted pipeline objects are registered with MTS as transactions not supported.
  • Currency Mode. Determines how the pipeline handles currency values. The options are:
    • Currency and Integer (compatibility). Allows Site Server 3.0 and Commerce Server 2000 components using currency values to be mixed in the pipeline. The Required components at the end of each stage maintain and update two sets of currency values — one set for Site Server 3.0 Commerce Edition components and one set for Commerce Server 2000. Mixing Site Server 3.0 Commerce Edition components and Commerce Server 2000 in the same stage requires using the MoneyConverter pipeline component.

    • Currency (high-precision). Uses the higher-precision currency type for all components in the pipeline. Requires that all components using monetary values be able to use the high precision currency values. In general, the names of these components end with the suffix "Cy."
  • Supply a currency LCID. Specifies a locale ID (LCID) for currency handling. The default value is zero, which uses the default locale ID of the server.

  • Supply the number of decimal places used for currency rounding. Determines how many digits of precision are held by a currency (for example, two digits are held for United States pennies). This value is used for default rounding processing, and to determine the scaling factor used in legacy currency keys. Active only if Currency (high precision) is specified for Currency Mode.

  • Description. An area for you to enter comments about this pipeline.


Stage Properties

Use the Stage Properties dialog box to change the following properties of a pipeline stage:

  • Label. Specifies the name that the Pipeline Editor displays for this stage. You can change the name by typing a new name.

  • Description. An area for you to type a description for this stage.

  • GUID. A globally unique identifier that identifies this stage.

  • Mode. The Mode field is provided for compatibility with Site Server 2.0 pipelines, in which a number identifies which stages of a pipeline are to be run by the RunProduct, RunPlan, and RunPurchase methods of the Page object. Use 1 for RunProduct, 2 for RunPlan, and 4 for RunPurchase. A value of zero (0) prevents the stage from running.

  • Error level. When any component in the stage generates an error at or above the level specified in the Error level box, the stage stops running and generates an error.


Component Properties

Use the Component Properties dialog box to change the name of the component, to view the Class ID or ProgID of the component, and to save notes about the component.

The following properties are available in the Component Properties dialog box:

  • Label. Specifies the name that the Pipeline Editor displays for this component. You can change the name by typing a new name.

  • Class ID. Specifies the globally unique identifier (GUID) that identifies this component on any computer. This ID never changes.

  • ProgID. Specifies the easily recognizable ID for the component. This ID never changes.

  • Description. An area for you to enter comments about this component.


Values Read and Written Properties

Use the Values Read and Written dialog box to view the values that this component reads from and writes to the order form and the values it reads from the Context dictionary object.

Note

  • The Pipeline Editor is unable to display values read and written for components that do not support the IPipelineComponentDescription interface (such as Site Server 3.0 Commerce Edition components).

The following properties are available in the Values Read and Written dialog box:

  • Values Read. Specifies the values that this component reads from the order form before it performs its function.

  • Values Written. Specifies the values that this component writes to the order form or other dictionaries after it has completed its function.

  • Context Values Read. Specifies the values that this component reads from the Context dictionary object. The Context dictionary object is passed as a parameter to the Execute method of the pipeline.

See Also

Creating a List of Values Read and Written


Creation Error Properties

This dialog box displays an error to help you determine the reason that a pipeline component could not be loaded.

Try the following solutions:

  • Delete the component from the pipeline and then reinsert it.

  • Make sure that the DLL associated with the component is properly registered.

  • If neither of the above solutions corrects the problem, try reinstalling Commerce Server.


Creating a Custom Pipeline

With the Pipeline Editor you can create a custom pipeline without basing it on one of the preconfigured pipeline template files (.pct).

To create a custom pipeline

  1. Click Start, point to Commerce Server 2000, and then click Pipeline Editor.

  2. In the Pipeline Editor, on the File menu, click New.

  3. In the Choose a Pipeline Template box, select Empty.pct., and then click OK.

    An empty pipeline file appears.

  4. Right-click Empty Pipeline Template, and then click Properties.

    The Pipeline Properties dialog box appears.

  5. In the Pipeline Properties dialog box, do the following:
    Use this | To do this
    Label | Type a new name for the pipeline.
    Transaction Compatibility Select a transaction compatibility option from the drop-down list. The options are:
    • Any pipeline. May be loaded into any pipeline.

    • Requires transacted pipeline. Must be loaded into an MtsTxPipeline or PooledTxPipeline pipeline.

    • Requires a non-transacted pipeline. Must be loaded into an MtsPipeline or PooledPipeline pipeline.
    Supply a currency LCID | Specify a locale ID (LCID) for currency handling. The default value is zero, which uses the default locale ID of the server.
    Supply the number of decimal places used for currency rounding Type the number for digits of precision to be held by the currency (for example, two digits are held for United States pennies). This value is used for default rounding processing, and to determine the scaling factor used in legacy currency keys.

    Note

    • This option is active only if Currency (high precision) is specified for Currency Mode.
    Description | Type a description for the pipeline.

  6. Click Apply, and then click OK.

  7. In the Pipeline Editor, right-click the name of the new pipeline and then click Insert Stage.

    A New Stage placeholder appears in the pipeline.

  8. Right-click New Stage, and then click Properties.

    The Stage Properties dialog box appears.

  9. In the Stage Properties dialog box, do the following:
    Use this | To do this
    Label | Type a name for the stage.
    Description | Type a description for the stage.
    GUID | Type a globally unique identifier for the stage.
    Mode Specify the mode for the stage for compatibility with Site Server 2.0.

    Note

    • The Mode field is provided for compatibility with Site Server 2.0 pipelines, in which a number identifies which stages of a pipeline are to be run by the RunProduct, RunPlan, and RunPurchase methods of the Page object. Use 1 for RunProduct, 2 for RunPlan, and 4 for RunPurchase. A value of zero (0) prevents the stage from running.
    Error level Specify the error level for the stage.

    Note

    • When any component in the stage generates an error at or above the level specified in the Error level box, the stage stops running and generates an error.

  10. Click Apply, and then click OK.

  11. Right-click the name of the new stage, and then click Insert Component.

    The Choose a component dialog box appears.

  12. In the Choose a component dialog box, do the following:
    Use this | To do this
    Stages | Select a stage option.
    Components | Select the name of the component you want to insert.

  13. Click OK.

  14. To configure the new component, right-click the component, and then click Properties. Modify the properties of the component as necessary, and then click OK.

  15. On the File menu, click Save As, and then type a name for the pipeline configuration file in the File name box.

The file is saved with the .pcf file extension.

See Also

Starting the Pipeline Editor

Creating a New Pipeline

Adding a Component to a Pipeline

Changing the Order of Components in a Pipeline Stage

Using the Pipeline Editor Property Pages


Order Processing Pipelines

The Order Processing pipelines (OPP) are software infrastructures that links several components and runs them in sequence on an OrderForm or Dictionary object. Commerce Server 2000 includes three basic types of order processing pipelines, which implement aspects of business-to-consumer and business-to-business sites.

This section contains:

  • About Order Processing Pipelines. Describes how the Order Processing pipelines work.

  • Default and Required Components. Explains the role of the Default and Required components in Order Processing pipelines. These components help to ensure data integrity during processing.

  • Currency Enhancements. Describes the high-precision currency data type and how pipeline components handle it.

  • Discount Objects. Explains the basic parts of a discount and how discounts are applied using discount components.

  • Inventory Objects. Explains how to check and reduce inventory using inventory components.

  • Shipping Objects. Describes the multiple-shipment shipping architecture and how to use Site Server 3.0 shipping components in Commerce Server 2000 pipelines.

  • Tax Objects. Explains how to use tax components with the multiple-shipment shipping architecture in Commerce Server 2000.

  • Business-to-Consumer Pipelines. Describes the business-to-consumer pipelines: the Product, Plan, and Purchase pipelines. These pipelines are used in Commerce Server sites designed for retail shopping by the public.

  • Using Order Processing Pipelines. Explains how to use Order Processing pipeline components in Commerce Server sites.

  • Order Processing Component Reference. Lists the components used in Order Processing pipelines.


About Order Processing Pipelines

Imagine a company department charged with processing a large volume of daily orders. To deal with the volume, the department might divide order processing into a series of steps, assigning one person to calculate shipping, another with ensuring the items ordered are in inventory, and another with checking prices.

For such an assembly-line approach to work, some level of coordination is essential among the people charged with order-related tasks. Thus, while dividing order processing into stages to make large-volume processing possible, this hypothetical processing department must also define the rules that coordinate the various tasks.

The Order Processing pipelines (OPP) work in much the same way as this hypothetical department. The Order Processing pipelines divide order processing into stages that describe a category of work. Thus, a typical OPP may include a Shopper Information stage, a Payment stage, and a Shipping stage.

Each stage in a pipeline consists of zero or more components. The components are run in sequence. A component is a Component Object Model (COM) object designed to perform some operation on an OrderForm object or other Dictionary object. In many cases, this operation is small. For example, the DefaultShipping component, which runs in the Shipping stage, ensures that another component has not already calculated the shipping cost. If this cost has already been set, the DefaultShipping component overwrites the value with zero (0) to ensure that components later in the Shipping stage begin with a reliable value.

The OPP further coordinates the work of components by ensuring that every component in an OPP is reading from and writing to the same purchase order. This purchase order is the OrderForm object.

The OrderForm object, which is the link between the Web site and the pipeline, contains all the necessary information to process a purchase, including user, shipping, tax, and item price information. In addition, the OrderForm object supports the methods needed to add new items to itself. After each component in the OPP performs its work on the OrderForm object, the OPP passes the OrderForm object to the next component in the pipeline.

The designer of the pipelines for your site needs to take measures to ensure that the OPP functions correctly. First, configure pipeline components so that they do not overwrite the work done by another component. (Components such as the DefaultShipping component are exceptions to this rule.) Second, define the conditions under which the OPP will stop processing an OrderForm object. As each component executes, it returns a status value indicating success, a warning, or failure. If you configure a stage to tolerate warnings, the OPP continues to operate despite warnings. If you configure a stage to tolerate only success, and the component returns a warning, then the OPP stops processing the OrderForm object, and returns an error.


Default and Required Components

All the templates for the Order Processing pipelines (OPP) include Default and Required components. These components are provided to ensure the integrity of data as it comes into and goes out of a pipeline stage.

In general, Default components appear at the beginning of a stage and site developers will often replace them. Default components are all named as such, DefaultShipping, DefaultPayment, and so on. Default components ensure that critical values for the stage exist. This may involve copying the values of one set of dictionary keys to another set of keys, or initializing some values to zero. If your pipeline does not require special functionality then the default components do not need to be replaced. However, if you need these Default components to function differently you will either need to replace these components with other components included in Commerce Server 2000 or create your own custom components. For more information about creating custom components, see Building Pipeline Components. For a list of components included with Commerce Server 2000, see Pipeline Component Reference.

Required components ensure the integrity of the data as it leaves the pipeline stage. In many cases this involves setting values, and raising errors or warnings. It may also involve checking that values were set in a previous component.

In addition, some Required components (RequiredItemPrice, for example) automatically perform currency and integer conversions at the end of a pipeline stage when the Currency Mode is set to Currency and Integer (compatibility). This means that if a pipeline stage contains only Site Server 3.0 Commerce Edition or only Commerce Server 2000 objects, you do not need to worry about converting the values. For more information about currency handling, see Currency Enhancements.


Currency Enhancements

With Commerce Server 2000, you have the option of using a high-precision currency value representation. This section describes the new currency representation, explains how to use it in both old and new pipelines, and lists the new data functions for handling the currency type.

This section contains:

  • Currency Overview. Describes how Site Server 3.0 Commerce Edition and Commerce Server 2000 represent currency values.

  • Currency Modes. Explains the two modes Commerce Server 2000 pipelines use that allow you to mix old and new components together, or to improve the performance of your pipelines by using only the new currency value representation.

  • Rounding. Explains how fractional units are rounded in the different currency value representations.

  • New Data Functions. Lists the new data functions that allow you to use the new currency value representation on your Active Server Pages (ASP) pages.


Currency Overview

Site Server 3.0 Commerce Edition uses long (32-bit) integers to represent money values in the base monetary unit of a locale. The base monetary unit is the smallest denomination of a currency, for example, US pennies. This representation set a relatively low limit on the maximum value that could be represented.

Commerce Server 2000 supports the OLE automation currency data type for monetary values. This representation allows for larger values as well as allowing up to four decimal places (internally the data type is a 64 bit integer scaled by 10000). Site Server 3.0 Commerce Edition used an integer representation ($1.99 needed to be stored as 199). Commerce 2000 uses a direct decimal representation ($1.99 is stored as 1.99).

Commerce Server 2000 retains the Site Server 3.0 Commerce Edition representation, as well as providing the higher-precision representation. Two different types of keys in the dictionaries depict the two representations. When a key has a high-precision currency value assigned to it, the key is prefixed with "cy_". The prefix follows any other prefix in the key name. For example, the high-precision currency version of the key _oadjust_adjustedprice is _cy_oadjust_adjustedprice.

See Also

Currency Modes

Rounding

New Data Functions


Currency Modes

In Commerce Server 2000, the Order Processing pipelines work in two modes: compatibility mode and high precision mode. The default mode is compatibility mode. In this mode, monetary values are maintained in both formats, though under different dictionary keys. Compatibility mode allows Site Server 3.0 Commerce Edition pipelines to run without change. It also allows for mixing Site Server 3.0 Commerce Edition and Commerce Server 2000 components.

In high precision mode, only the high-precision currency type is used. This provides better performance because the pipeline maintains only one set of keys. It also avoids possible loss of precision in converting the values to and from the lower-precision integer format.

You can change the mode of a pipeline in the Pipeline Editor. For more information, see Pipeline Properties. If you use the high-precision mode all the components in the pipeline must support the high-precision currency type.

If you use compatibility mode and you use all Commerce Server 2000 components or all Site Server 3.0 Commerce Edition components within a stage, you do not have to modify your pipeline. Each stage that uses monetary types includes a Required component at the end of the stage. These components automatically update both sets of keys used in compatibility mode.

If you mix Site Server 3.0 Commerce Edition components and Commerce Server 2000 components within a stage, you will need to surround the Site Server 3.0 Commerce Edition component with the MoneyConverter component to ensure that the dictionary values are kept current for both types of components. For more information, see MoneyConverter.

See Also

Currency Overview

Rounding

New Data Functions


Rounding

High-precision currency values, unlike the Site Server 3.0 Commerce Edition integer values, have a fractional part. Because of this, Commerce Server 2000 rounds high precision currency values before writing them to the dictionary. This helps prevent situations where a fractional value might cause a total value that was not equal to the sum of displayed values.

The Commerce Server 2000 Software Development Kit (SDK) sample code for developing pipeline components includes monetary rounding functions for use in building components. See the files moneyinfo.h and moneyinfo.cpp in the SDK for more information.

See Also

Currency Overview

Currency Modes

New Data Functions


New Data Functions

Commerce Server 2000 provides two new data functions for handling the high precision currency type. Both are methods of the DataFunctions object.

Function | Description
ConvertStringToCurrency | Converts a string representation of money into a currency Variant, based on the specified locale and currency symbol.
LocalizeCurrency | Creates a string representation of a currency value using a specified locale and currency symbol.

See Also

Currency Overview

Currency Modes

Rounding


Discount Objects

Microsoft Commerce Server 2000 provides a flexible and powerful way to apply and manage discounts. The Content Selection Framework processes discounts using the same pipelines that are used for ad selection and order processing.

Discounts are set up as parts of campaigns. For information about setting discounts through the Commerce Server Business Desk, see Adding a Discount Campaign Item. For information about the Content Selection pipeline, see Content Selection Pipelines.

This section contains:

  • Overview. Describes the basic parts of a discount: requirements, conditions, awards, and offer. Also described are the differences between order-level and item-level discounts.

  • How Discounts Are Applied. Describes how the condition, award, and offer are evaluated in order to apply discounts to the purchases in the basket.


Overview

In Microsoft Commerce Server 2000, discounts have four parts. In addition, discounts can apply to either the entire order or to individual items in the order. The four elements of a discount are:

  • Requirement. Requirements are general conditions that must be true for the discount to apply. These are often target expressions that are evaluated based on the user profile and the context profile. An example of a requirement would be that the user be a preferred shopper.

  • Condition. A condition that must be true for the discount to apply. Conditions are evaluated on individual items in the order form. Expressions for conditions can be built with the product picker or the Expression Builder. A condition includes things such as a specific SKU, a product category, or a particular manufacturer.

  • Award. An award condition that must be true for the discount to apply. An award condition is evaluated for individual items in the order form. An award condition may be an expression, that the discount applies to any item, or that it applies to all items.

  • Offer. An offer that is applied if the requirement, condition, and award are met. An offer is what is normally thought of as a discount — a percentage or dollar amount off taken off the price of the product.

Discounts can be applied against an entire order (an order-level discount), or they can be applied against items in the order (an item-level discount). Free shipping is the only order-level discount built into Commerce Server. Other order-level discounts require custom programming.

See Also

How Discounts Are Applied


How Discounts Are Applied

In a Content Selection pipeline, the ScoreDiscounts component adjusts the scores in the list of possible discounts to ensure that the most relevant discounts receive the highest priority.The OrderDiscount pipeline component in an Order pipeline applies the list of discounts to the basket of the user.

The OrderDiscount component first evaluates the requirements of the available discounts. Depending on the discount involved, it uses the user profile and context profile information to form target expressions that it evaluates. In addition, if a discount requires a click, the component checks the discounts_clicked list (a list of campaign item IDs of every item that was clicked).

For each line item in the order, the OrderDiscount component writes two keys to the item dictionary: _n_unadjusted and _cy_oadjust_adjustedprice. The first key is the quantity of the item that has not had discounts applied. The second key is the total price of the items before discounts. The _n_unadjusted key is set to the quantity of the item; the _cy_oadjust_adjustedprice key is set to the total price for the items.

The OrderDiscount component next goes through the items, testing the conditions and awards. As an item is used in a discount, the two keys (_n_unadjusted and _cy_oadjust_adjustedprice) are adjusted appropriately. Discounts are applied from highest to lowest priority. If two discounts have the same priority, the discount appearing first in the database is applied.

There may be limits to how many discounts can be applied to a basket. This limit is set in Commerce Server Business Desk. If the discount limit has a value of zero (0), discounts are unlimited. The discount limit is a basket limit and does not apply across baskets.

The OrderDiscount component uses a list to ensure integrity in the process. The component stores a list of discounts that were applied and the last time the discount was modified. If, on the next request, discounts that were applied no longer apply, the pur_dicountremoved error is added to the _Basket_Errors list.

The discount cache must be manually refreshed after changes are made to any discount. You can do this by using the Production Refresh module in Business Desk.

One way to implement discounts on your site is to accept promotional codes. First, set up the discount properties and the display information through Business Desk. Next, configure the discount definition using the Expression Builder. For example, the expression could be Context.PromoCode equals 1234. Modifications will need to be made to the source code for the site. When the basket pipeline is called, a ContextProfile dictionary (which is a sub dictionary of the Context dictonary) must be passed, and the promotional code entered must be set.

See Also

Discount Overview


Inventory Objects

Inventory management in Commerce Server sites usually occurs in two stages in the Order Processing pipelines (OPP).

The first stage, the Inventory stage, is usually configured to include components that determine whether a sufficient number of items are available to fill the order for a given product.

The second stage, the Accept stage, may be configured to modify the product table for a site to reflect the new number of items available for a given product. Optionally, you can use the SQLItemADO component in either the Inventory or Accept stages to reduce the local inventory once the items have been purchased.

This section explains how to use the inventory components included in Commerce Server 2000, and explains how you can use Commerce Server to address issues that arise in the context of inventory control.

Inventory and Backordering

Reducing Inventory

Inventory and Backordering

How you manage inventory in your site depends largely on how you want to respond to a situation in which a given item is out of stock. In such a situation you can either place the item on backorder, or you can notify the customer that the item is not currently available.

The FlagInventory and LocalInventory components, which have an affinity with the Inventory stage, coordinate with the Product Info stage to support either response.

Flag Inventory Checking

The FlagInventory component is designed to identify items in the items SimpleList object that are out of stock. When this component runs, it iterates through the items in the items SimpleList object to verify that the _product_in_stock name/value pair for a given item is not zero (0).

If the _product_in_stock name/value pair evaluates to zero (0), the FlagInventory component can respond in one of two ways. The component supports a Disallow Backorder property, which you set using the property page for the component. If the Disallow Backorder check box is selected, and evaluates to zero (0), the FlagInventory component adds a _pur_out_of_stock message to the _Purchase_Errors SimpleList object. If the Disallow Backorder component is not selected, and _product_in_stock evaluates to zero (0), then the _inventory_backorder name/value pair for the affected item is set to zero (0).

Note

  • The FlagInventory component requires that each line item specify _product_in_stock.

Quantity-Based Inventory Checking

The LocalInventory component compares the number of units in the Quantity name/value pair to the number in the _product_local_inventory name/value pair. The _product_local_inventory name/value pair should represent the actual number of items in stock. If the Quantity name/value pair exceeds _product_local_inventory, the difference between these two numbers is written to the _inventory_backorder name/value pair, provided that the LocalInventory component is configured to allow backordering. Otherwise, the LocalInventory component, like the FlagInventory component, writes a _pur_out_of_stock message to the _Purchase_Errors SimpleList object.

The LocalInventory component should be added to the basket pipeline to check item availability when the product is added to the basket. If you include the LocalInventory component in the pipeline for your site, the script that you use to display the basket to your users should be written to notify them that a requested item is either out of stock or on backorder.

Note

  • The LocalInventory component requires that each line item specify product_local_inventory.

Reducing Inventory

The FlagInventory and LocalInventory components are strictly informational components. This means that while they provide notification that a given item is out of stock, they assume that _product_local_inventory for the line item has been maintained by some other process. The SQLItemADO pipeline component can be used for executing a SQL query that updates the product inventory.

Note

  • You must unpackage a site before starting the following procedure.

To update your inventory using the SQLItemADO pipeline component

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2000, and then click Pipeline Editor.

  2. In the Pipeline Editor, browse to the location of the file total.pcf (for example, <drive:>\Inetpub\wwwroot\<site name>\pipeline), and then double-click the file.

    The total.pcf pipeline appears.

  3. On the pipline, select the Inventory stage, and then on the Edit menu, point to Insert Component, and then click After.

  4. On the Choose a component dialog box, do the following:
    Use this | To do this
    Stages | Select All.
    Components | Select SQLItemADO.

  5. Click OK. The SQLItemADO component appears as a valve on the pipeline.

  6. Double click the SQLItemADO component.

  7. In the Component Properties dialog box, on the SQL Item (ADO) tab, do the following:
    Use this | To do this
    Connection String | Type an OLEDB connection string to the table storing the inventory data.
    Query Type the SQL query that will update the inventory in the database. The syntax required to replace values in the SQL query is:

    :<position>

    This will replace the items in the SQL query with items listed in the Parameter List box. For example, if you had to replace two values in a SQL query, the format would be:

    SELECT * FROM:1 WHERE Param2=':2'
    Parameter List | Type the list of values you want to use in the SQL query that will be evaluated at run time. The Parameter List box uses a special format for replacement. To retrieve data from the order form, use the notation item.<orderformvalue>. For example, to retrieve the quantity of the items ordered from the order form, you would use item.quantity.

    Click OK.

  8. To save your changes, on the File menu, click Save.

Special Considerations for Inventory

You may have a situation in which two customers want an item of which there is only one in stock. As the OrderForm object for each customer passes through the Plan pipeline, the inventory components indicate to both customers that the product is in stock. This is correct behavior, because the number that indicates how many items of a given SKU are in stock has not yet been reduced to zero (0) by an Accept stage component.

However, when the first customer runs through the Purchase pipeline, the SQLItemADO component will reduce the in-stock value to zero (0). When the second customer runs through the Purchase pipeline, the SQLItemADO component will reduce this value to a negative integer. This scenario creates a backorder, even if the Plan pipeline for the site is configured to not allow back ordering.

There are several ways to address this problem.

One solution is to include at the beginning of the Accept stage a SQLItemADO component that checks to ensure that the number of items in stock for a given SKU is larger than zero (0). If no items for a given SKU are in stock, the SQLItemADO component can place the items on backorder (by initializing the _inventory_backorder name/value pair) or can raise the _pur_out_of_stock error.

A second solution is to include an instance of the appropriate inventory component, FlagInventory for example, in both the Inventory stage (Plan pipeline) and in the Accept stage (Purchase pipeline). Following this component, you would include the SQLItemADO component. The inventory component would execute the query to decrement the in-stock value for the item.


Shipping Objects

Microsoft Commerce Server 2000 provides components to support multiple shipments per order.

This section contains:

  • Multiple-shipment Shipping Architecture. Describes the multiple-shipment shipping architecture, the components and objects it uses, and provides code showing how to use these features.

  • Using Site Server 3.0 Commerce Edition Shipping Components. Describes how to use the Site Server 3.0 Commerce Edition shipping components.


Multiple-shipment Shipping Architecture

The Commerce Server 2000 multiple-shipment shipping architecture consists of three pipeline components and two objects that work together to create a powerful and easy-to-use way of handling shipping.

This section contains:

  • Overview. Describes the multiple-shipment shipping architecture and components.

  • Setting Up the Pipeline and Cache. Describes the Active Server Pages (ASP) code required for using the multiple shipment components in the pipeline.

  • Using the Splitter Component to Create Multiple Shipments. Describes how to set up the Splitter component to divide orders into multiple shipments.

  • Previewing Shipping Costs. Describes how to provide shipping cost previews.

  • Adding Shipping Methods and Components. Describes how to add shipping methods and individual shipping components to the multiple-shipment shipping architecture.

  • The Shipments and Addresses Structures. Describes the dictionaries and simple lists used in the processing of multiple shipments.

See Also

Using Site Server 3.0 Commerce Edition Shipping Components

MinMaxShip Sample Pipeline Component


Overview

The multiple-shipment shipping architecture of Commerce Server 2000 has two purposes: simple modification of shipping method configuration by non-programmers, and the processing of multiple shipments per order.

In the multiple-shipment shipping architecture, the Shipping stage generally uses the same three components: the Splitter, the ShippingMethodRouter, and the ShippingDiscountAdjust components. The Splitter component in its shipping configuration takes the order and splits it into separate shipments. The ShippingMethodRouter component then processes the separate shipments. From the shipment and a database table of shipping information, the ShippingMethodRouter component determines which individual shipping component to use to process a given shipment. The optional third pipeline component, the ShippingDiscountAdjust component, applies shipping discounts to the order.

The ShippingMethodRouter, Splitter, and ShippingDiscountAdjust components are the only shipping components that should be inserted in the pipeline. The ShippingMethodRouter component runs shipping methods configured with the ShippingMethodManager object.

All shipping cost calculation components, except the Splitter component, should be registered with the ShippingMethodRouter component. The shipping cost calculation components that the ShippingMethodRouter component runs are configured in the Shipping Method module in Commerce Server Business Desk.

The following figure illustrates the relationships between all of the parts of the shipment component process.

This diagram illustrates how the Splitter component and the ShippingMethodRouter component work with other objects to process shipments
ShippingMethodRouter
ItemIndexes
(SimpleList)
ShippingMethodManager
ShippingConfig
database table
Pipeline Execution
. . .
address1
last_name
Address Dictionaries
first_name
Orderform.addresses
(SimpleList)
Business Desk
ShippingManagerCache
Shipping Pipeline Components
ItemIndexes
_cy_shipping_total
shipping_method_id
Shipment Dictionaries
shipping_address_id
Orderform.shipments
(SimpleList)
Context.shipments_to_process
(SimpleList)
Splitter

Two components use the ShippingConfig table, which is used by the ShippingMethodRouter component. Business Desk uses one of these components, the ShippingMethodManager, to modify the database. The business manager can modify shipping methods through the Shipping Method module in Business Desk.

The second component is the ShippingManagerCache. The CacheManager object uses this component to load data from the ShippingConfig table into the cache. The ShippingMethodRouter component, in turn, uses the ShippingManagerCache component to get and maintain the cached shipping information.

The following table lists the components and objects in the multiple-shipment shipping architecture, and provides links to more detailed information about each object and component.

Object | Description
ShippingMethodRouter | Determines the shipping method, runs the individual shipping components, and calculates the total shipping costs for the order.
StepwiseShipping | A pipeline component that calculates shipping for individual shipments. It handles charging by weight, quantity, and price. This component is run and configured by the ShippingMethodRouter component. This component may be replaced or augmented by custom components.
ShippingMethodManager Object | This object manages the ShippingConfig database table. This table is used by Business Desk through the ShippingMethodManager object. The ShippingConfig table contains the information used by the ShippingMethodRouter component.
ShippingManagerCache | The loader component used by the CacheManager object to handle data from the ShippingConfig database table.
Shipping Object | The object provides a method, PreviewShipments, to produce shipping cost previews.
ShippingDiscountAdjust | This component applies shipping discounts to an order; it uses the multiple-shipment shipping architecture.
Splitter | In its shipping configuration, this component divides an order into multiple shipments based on a set of distinguishers.

Taxes are calculated on individual shipments since they may vary based on the shipment. New tax components need to take into account the multiple shipment structure. The SampleRegionalTax component is an example of such a tax component. For more information about the multiple shipment structure, see Shipments and Address Structures.

Handling charges, however, are calculated based on the order, rather than the individual shipment.

See Also

Setting Up the Pipeline and Cache

Using the Splitter Component to Create Multiple Shipments

Previewing Shipping Costs

Adding Shipping Methods and Components

Shipments and Address Structures


Setting Up the Pipeline and Cache

In the multiple-shipment shipping architecture, the Shipping stage of a pipeline contains two or three components: Splitter, ShippingMethodRouter, and occasionally the ShippingDiscountAdjust component. The Splitter component divides the order into a series of shipments; the ShippingMethodRouter component takes the shipments created by the Splitter component, checks the shipping method, and runs the appropriately configured shipping component.

In addition to including the two pipeline components in the pipeline, you need to add some Active Server Pages (ASP) code to your pages to handle setting up the CacheManager object and to provide the Context dictionary values expected by the Splitter and ShippingMethodRouter components.

Both the Splitter and ShippingMethodRouter components use the CacheManager object to retrieve information from the ShippingConfig database table. The CacheManager object, in turn, uses a loader component, ShippingManagerCache, to retrieve the information from the database. Setting up the CacheManager object for the shipping components is roughly the same as for any other component using the CacheManager object. Most of the code is contained in the Global.asa file, in the Application_OnStart procedure. For example:

' Code to set up the CacheManager object and loader for the
' multiple shipping components.

' Create a Dictionary object to hold the configuration information.
Set dShipConfig = Server.CreateObject("Commerce.Dictionary")

' Add the connection string to the configuration dictionary.
dShipConfig("ConnectionString") = "DSN=shipsamples;UID=sa;PWD="

' Create a CacheManager object.
Set oCM = Server.CreateObject("Commerce.CacheManager")

' Set the ProgID of the loader for the cache.
oCM.LoaderProgId("ShippingManagerCache") = _
                    "Commerce.ShippingManagerCache"

' Set the loader's configuration dictionary.
Set oCM.LoaderConfig("ShippingManagerCache") = dShipConfig

' Set the CacheManager object refresh interval to 10 minutes.
oCM.RefreshInterval("ShippingManagerCache") = 10 * 60

' Set the CacheManager object retry interval to 1 minute.
oCM.RetryInterval("ShippingManagerCache") = 60

' Store a reference to the CacheManager object in the Application object.
Set Application("MSCSCacheManager") = oCM

Note that in the preceding code, you must use the identifier "ShippingManagerCache" when setting the LoaderProgID, LoaderConfig, and other properties. On the page that runs the pipeline, only one additional line of code is needed:

' Add the items specific to the shipping components.
'
'Add a reference to the CacheManager object created in the Global.asa file
'to the Context dictionary.
Set dContext("CacheManager") = Application("MSCSCacheManager")

The code to invoke the pipeline would follow this code.

See Also

Shipping Overview

Using the Splitter Component to Create Multiple Shipments

Previewing Shipping Costs

Adding Shipping Methods and Components

Shipments and Address Structures


Using the Splitter to Create Multiple Shipments

The Splitter component allows you to split orders based on any of the attributes of the line items. The default distinguishers for splitting orders are shipping_method_id and shipping_address_id. You can specify other keys to use as criteria in the Input Distinguishers box on the Component Properties tab.

Each line in the following table would represent a dictionary pointed to by an element of the SimpleList object.The dictionaries also include a key, ItemIndexes, that is a reference to a SimpleList object. Each element in the SimpleList object is an index into the LineItems dictionary, containing line items in the actual order.

The following example has four line items, numbered zero through three. The following table contains a list of some of their attributes.

shipping_method_id | shipping_address_id | shipping_date | catalog | vendor
A | Home | ASAP | A | A
A | Home | ASAP | A | A
B | Work | ASAP | B | B
A | Work | 3/1 | C | B

If the previous information were split by the distinguishers shipping_method_id and shipping_address_id, to an output struct called _shipments, a SimpleList object of dictionaries will be on your order form called "shipments" with the following entries:

shipping_method_id | shipping_address_id | ItemIndexes
A | Home | 0,1
B | Work | 2
A | Work | 3

If you the the four lineitems by vendor, to an output struct called _Vendors, a simplelist of dictionaries will be on your orderform called "_Vendors" with the following entries:

vendor | ItemIndexes
A | 0,1
B | 2,3

Previewing shipping costs for a user is more complex when shipments are split. You can use the PreviewShipments method of the Shipping object to get the data to display in your ASP page. For more information, see Shipping.PreviewShipments.

See Also

Shipping Overview

Setting Up the Pipeline and Cache

Previewing Shipping Costs

Adding Shipping Methods and Components

Shipments and Address Structures


Previewing Shipping Costs

To display the shipping cost previews on your page, use the PreviewShipments method of the Shipping object.

The PreviewShipments method creates the shipping cost previews by splitting the order into individual shipments, just as the Splitter component does in its shipping configuration. For more information about how shipment distinguishers are used to split shipments, see Using the Splitter to Create Multiple Shipments and Splitter.

The PreviewShipments method returns a SimpleList object of dictionaries, one for each shipment. Each shipment dictionary in turn contains a SimpleList object of dictionaries, each of which contains the shipping cost for using a particular shipping method.

To loop through all the shipping cost previews for all shipments, you might use code like the following:

Set oShip = Server.CreateObject("Commerce.Shipping")
ADistinguishers = Array("shipping_method_id", "shipping_address_id")
slShipments = oShip.PreviewShipments(dOrder, dContext, ADistinguishers)
For Each dShipment In slShipments
    For Each dPreview In dShipment.Previews

        ' Inside the loop, you can get the preview
        ' information:
        ' dPreview("shipment_error")  -  the shipment error, if any
        ' dPreview("shipping_method_id")  -  the shipping method ID
        ' dPreview("shipping_method_name")  -  the shipping method name
        ' dPreview("description")  -  the shipping method description
        ' dPreview("_cy_shipping_total")  -  the shipping cost

    Next
Next

See Also

Shipping Overview

Setting Up the Pipeline and Cache

Using the Splitter Component to Create Multiple Shipments

Adding Shipping Methods and Components

Shipments and Address Structures


Adding Shipping Methods and Components

For business managers and most site developers, the process of adding shipping methods and installing components is straightforward. Shipping methods using installed components are added through Commerce Server Business Desk. For information about using Business Desk to add shipping methods, see Customizing Shipping Methods.

Similarly, installing third-party shipping pipeline components should be a matter of following the installation instructions.

Component developers, however, who need to test components or provide component installers, need to know how to add custom shipping methods to the multiple-shipment shipping architecture. This process is described in Adding a Custom Shipping Method.

Important

  • Shipping components should expose the IPipelineComponentAdmin::GetConfigData and IPipelineComponentAdmin::SetConfigData methods from the IDispatch implementation, because the Business Desk module(s) that manage these components must be able to call these methods from a late-bound (Active Server Pages) environment.

Adding a Custom Shipping Method

Creating a Custom Shipping Method Page

Adding a Custom Shipping Method

The shipping method editing pages in Business Desk contain two sections, Shipping Method Properties and Rates. These edit pages should be implemented by the component writer in any custom shipping method that they create. The framework handles some of the edit page implementation and all of the list page implementation.

The Shipping Method Properties section is responsible for getting data into and out of the ShippingConfig table. This data is processed by the ShippingCommon_edit.asp page using edit fields in the top section. This section also sets up the taskbar for the page and handles all the necessary framework files to make the custom pages fully functional. Be sure to include the ShippingCommon_edit.asp page at the top of any custom shipping method page you create.

The custom shipping method page you create is responsible for processing data in the second section of the page, Custom Properties. This data will reside in the TableShippingRates table.

Creating a Custom Shipping Method Page

To create a page for your custom data section, begin with an existing page such as the MinMax_edit.asp (or another of the Shipping Method pages) and then customize it.

To create a custom shipping method page

  1. At the top of the page, place a reference to include the file ShippingCommon_edit.asp.

  2. Replace the XML meta- and data- islands with your custom XML meta- and data-islands.

  3. Customize the DIV section to describe the new XML meta- and data-islands.

  4. If necessary, add hidden form input fields to hold values and an event handler (client-side).

  5. Replace the strings in GetActionPageName and GetActionFriendlyName with the names of your custom method page.

  6. Add code to the ProcessCustomShippingData function to handle task button events (loading and saving your custom data).

All the appropriate changes have been made to the shipping page and you are now ready to install it and use it in the Shipping Methods module in Business Desk.

To install the new page

  1. Add information about the new method to the Shipping_methods.xml file in the <drive:>\Inetpub\wwwroot\<Business Desk site name>\Config directory. This information notifies the framework that a new method exists and sets action (posting) information. It will then display the new method as a choice on the taskbar menu located on the list page, and it will handle posting correctly (see the Shipping_methods.xml file for an example).

  2. Add the new page to <drive:>\Inetpub\wwwroot\<Business Desk site name>\Shipping and install and register the custom DLL containing the shipping component (for example, Minmaxatl.dll). When Business Desk has been reloaded, your custom module should appear on the menu of the Shipping Methods module list page. When editing this method, your custom components should display in the lower section of the edit page.


Shipments and Address Structures

The list of shipments produced by the Splitter component contains several nested structures.

The Splitter component in the shipping configuration assigns the list of shipments to the Order.Shipments object. The ShippingMethodRouter component breaks this list down further into a list of shipments_to_process for each individual component run. The list of shipments is a SimpleList object of dictionaries, one for each shipment. The following table shows a sample of the keys in the shipment dictionaries.

Key | Description
shipping_address_id | The ID in the Address dictionary of the dictionary containing the address information.
shipping_method_id | The shipping method ID,taken from the ShippingConfig database table.
shipping_method_name | The name of the shipping method.
_cy_shipment_total | The total shipping cost for the items in this shipment.
ItemIndexes | A SimpleList object of indexes to the line items in the order.

The following example code shows how a component might get at the data in the shipments list:

' Assume that dContext is the Context dictionary.
For Each dShipment In dContext.shipments_to_process

    ' Get the address information by getting the Address dictionary.
    Set dAddress = dOrder.Addresses(dShipment.address_id)
    ' Manipulate the address information here.

    ' Get the information about each line item in the shipment.
    ' Items is a SimpleList of dictionaries. ItemIndexes stores
    ' the indexes of the items in the current shipment.
    For Each nIndx In dShipment.ItemIndexes
        ' Retrieve the dictionary for the given item.
        dItem = dOrder.Items(nIndx)
        ' Manipulate the individual item dictionary here.
    Next

Next

Each address dictionary contains the following keys:

Key | Description
address_name | Descriptive name for the address.
address_type | Address type: 0 Neutral. 1 Shipping. 2 Billing.
first_name | First name of the addressee.
last_name | Last name of the addressee.
address_line1 | First line of the address.
address_line2 | Second line of the address.
city | City name.
region_name | Name of the state, region, or province .
region_code | Code for the state, region, or province.
postal_code | Postal code.
country_name | Country name.
country_code | Country code.
tel_number | Telephone number.

Notice that although the shipping address is attached to each item, the billing address is attached to the order. The billing_address_id key identifies which address in the Addresses dictionary is the billing address:

' dOrder is an Order dictionary.
' dBillingAddress is a dictionary.
Set dBillingAddress = dOrder.Addresses(dOrder.billing_address_id)

See Also

Shipping Overview

Setting Up the Pipeline and Cache

Using the Splitter Component to Create Multiple Shipments

Previewing Shipping Costs

Adding Shipping Methods and Components


Using Site Server 3.0 Commerce Edition Shipping Components

If you want to use the Site Server 3.0 Commerce Edition single-shipment shipping components, you will first need to remove the Splitter, ShippingMethodRouter, and the ShippingDiscountAdjust components from the pipeline. Site Server 3.0 components do not support the multiple-shipment shipping architecture used in Commerce Server 2000. You must also revert to Site Server 3.0 tax components, because tax components typically look at address and shipment information. And if you are using a site that has a Commerce Server 2000 an Active Server Pages (ASP) code base, code changes will also be necessary.

The _cy_shipping_totoal name/value pair on the OrderForm object stores the total cost of shipping for an order.

The DefaultShipping component sets this name/value pair to zero (0). If you do not want to charge shipping on an order, you can make this the only component in the stage.

In the Site Server 3.0 Commerce Edition single-shipment shipping architecture, components are coordinated to compute the shipping_total. For more information, see Component Coordination.

See Also

Multiple-shipment Shipping Architecture

MinMaxShip Sample Pipeline Component


How to Use Table Shipping

Table shipping uses values retrieved from a database to set the shipping total for an order.

The TableShippingADO component is designed to retrieve a single currency value from a database table based on a query that you specify, and to write this currency value to order.[_shipping_total] key. To use this component, perform the following steps:

  1. Determine the basis of the calculation. For example, the basis might be the total weight of all the items in the order, and it might also depend on the shipping method selected by the customer.

  2. Create a table in the site database that stores the shipping cost as a function of the basis.

  3. Create a query designed to retrieve this value. If this query uses a product characteristic such as the sum total of the weight of the items in the order form, you may also need to modify the Product Information stage to ensure that this product information is present in the order form.

  4. Configure the property page for the TableShippingADO component to reference this query.

The sections that follow describe how to reference these steps. In this example, you will modify some existing code so that it uses a table to determine shipping costs based on the total weight and the shipping method.

Adding a Weight Attribute to the Product Table

Creating the Shipping Cost Table

Configuring the Component

Special Considerations for Table Shipping

Adding a Weight Attribute to the Product Table

In this example, the weight of each product is used to calculate the shipping cost. For this reason, weight must be specified for every item on your Web site. The following procedure describes how to add a column called weight to the product table.

Note

  • This procedure assumes that you are using a site similar to the SiteServer 3.0 Commerce Edition sample sites. It also assumes that you are using the QueryProductInfoADO component, and not the QueryCatalogInfo component in your Product Information stage.

To add a database column using SQL Enterprise Manager

  1. Click Start, point to Programs, point Microsoft SQL Server, and then click Enterprise Manager.

  2. Expand the Microsoft SQL Servers node,, expand the SQL Server Group node, expand the node for server that contains the Web site databases, expand the Databases node, expand the name of the database containing your Commerce Server site databases, expand the Objects node, and then expand the Tables node. Double-click the product table for the site. (In this example,the table is called healthy_product.)

  3. In the Manage Tables dialog box, do the following:
    Use this | To do this
    Column Name | Add a new column on the last row named weight.
    Datatype | Select Float.

  4. Click Close to close the dialog box and, when prompted, click Yes to apply your changes.

Next, you need to add the weight column to the query that is used by the QueryProdInfoADO component in the Plan or Basket pipeline for the site. In this example, the name of this query is product_info, and is defined in the Global.asa file.

To add the weight attribute to the product query

  1. Open the Global.asa file for the site using an editor such as Notepad.

  2. Locate the script where product_info is added to the query map. It begins with the following commands:
    Set MSCSQueryMap.product_info = AddQuery("SELECT
  3. Add pf.weight to the list of columns returned by the SELECT statement. This ensures that the product weight is included in the item list for each product in the order form.

Creating the Shipping Cost Table

You will need to add a shipping cost table to the database. The shipping cost table in this example uses the sum of the weight of each of the items in the items list, as well as the shipping method, as the basis of the shipping cost. The weight of each item is expressed in pounds. The shipping cost is expressed as an integer, in the smallest units of the currency (in this example, pennies). The following SQL script generates such a table:

CREATE TABLE dbo.healthy_shipping_costs (

    shipping_method varchar (20) NOT NULL ,

    min_weight float NOT NULL ,

    max_weight float NOT NULL ,

    cost int NOT NULL

PRIMARY KEY (shipping_method,min_weight,max_weight)

)

GO

truncate table healthy_shipping_costs

go

insert into healthy_shipping_costs values ('shipping_method_1', 0.0, 2.0, 450)

go

insert into healthy_shipping_costs values ('shipping_method_1', 2.0, 3.0, 540)

go

insert into healthy_shipping_costs values ('shipping_method_1', 3.0, 4.0, 630)

go

insert into healthy_shipping_costs values ('shipping_method_1', 4.0, 5.0, 720)

go

insert into healthy_shipping_costs values ('shipping_method_1', 5.0, 6.0, 810)

go

insert into healthy_shipping_costs values ('shipping_method_1', 6.0, 7.0, 900)

go

insert into healthy_shipping_costs values ('shipping_method_1', 7.0, 8.0, 990)

go

insert into healthy_shipping_costs values ('shipping_method_1', 8.0, 9.0, 1080)

go

insert into healthy_shipping_costs values ('shipping_method_1', 9.0, 15.0, 1400)

go

insert into healthy_shipping_costs values ('shipping_method_1', 15.0, 100.0, 2000)

go

insert into healthy_shipping_costs values ('shipping_method_2', 0.0, 2.0, 300)

go

insert into healthy_shipping_costs values ('shipping_method_2', 2.0, 3.0, 390)

go

insert into healthy_shipping_costs values ('shipping_method_2', 3.0, 4.0, 480)

go

insert into healthy_shipping_costs values ('shipping_method_2', 4.0, 5.0, 570)

go

insert into healthy_shipping_costs values ('shipping_method_2', 5.0, 6.0, 660)

go

insert into healthy_shipping_costs values ('shipping_method_2', 6.0, 7.0, 750)

go

insert into healthy_shipping_costs values ('shipping_method_2', 7.0, 8.0, 840)

go

insert into healthy_shipping_costs values ('shipping_method_2', 8.0, 9.0, 930)

go

insert into healthy_shipping_costs values ('shipping_method_2', 9.0, 15.0, 1000)

go

insert into healthy_shipping_costs values ('shipping_method_2', 15.0, 100.0, 1200)

go

After creating the shipping cost table, add a query to the QueryMap dictionary for the site. This query should be designed to take as parameters all the values that are used as the basis. In this example, these parameters are the weight of all the items in the order, along with the shipping method. The query should be included among the queries initialized in the Global.asa file for the site, as shown in the following code:

Set MSCSQueryMap.ship_cost = AddQuery("SELECT cost FROM healthy_shipping_costs WHERE min_weight <= ? AND max_weight > ? AND shipping_method = ?")

Because the QueryMap dictionary for the site is usually included in the pipe context that is passed to an Order Processing pipeline, the TableShippingADO component can be configured to reference this query.

Configuring the Component

To configure the TableShippingADO component to use the query that you added to the QueryMap dictionary, use the Pipeline Editor to insert the TableShippingADO component into a pipeline.

To insert the TableShppingADO component into the pipeline

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2000, and then click Pipeline Editor.

  2. On the File menu, click Open. Browse to the location of your existing .pcf file, and open it.

    A graphic of your pipeline appears.

  3. In the Shipping stage of the pipline graphic, delete the DefaultShipping component if it exists.

  4. On the Edit menu, point to Insert Component, and then click After.

  5. In the Choose a component dialog box, do the following:
    Use this | To do this
    Stages | Select Shipping.
    Components | Select TableShippingADO.

  6. Click OK. The TableShippingADO pipeline component appears as a valve on the pipeline graphic.

  7. Double-click the TableShippingADO component.

  8. In the Component Properties dialog box, on the Table Shipping (ADO) tab, do the following:
    Use this | To do this
    Apply when | Select Has any value, which means that the query is executed only when the order form contains a shipping_method value. This setting enables the Plan pipeline to be run in the Basket.asp page, before the customer has selected a shipping method and before the _shipping_cost name/value pair has been added to the order form. The Apply When setting identifies the circumstances under which the value returned by the query is written to the _shipping_cost name/value pair. If this field were set to Always, this component would fail on the Basket page because the query could not run successfully. When the Plan pipeline is run again on the Payment.asp page, the shipping_method name/value pair now appears in the order form, and the ship_cost query is run.
    Method | Leave blank.
    Connection String | The connection string on which the query in the Query box is executed.
    Query | Type the name of the query to be executed. This example uses ship_cost, the name of the Dictionary entry that was added to the QueryMap dictionary.
    Parameter List Type the values to pass to the query. The first two values must be the same (the weight of the total order), because the weight is used as the first two parameters in the query. The third parameter is the shipping method. To implement this example, enter the following parameter list:
    sumq._product_weight sumq._product_weight order.shipping_method
    Column | Type the name of the column that contains the shipping cost. In this example, this setting equates to the column cost that was defined as part of the shipping table. If no value is entered in this column, the component defaults to the value cost. In addition, if you specify a query that returns multiple rows of data, all rows after the first row are ignored.

  9. Click OK.

  10. To save your changes, on the File menu, click Save.

Special Considerations for Table Shipping

When configuring the TableShippingADO component, keep the following in mind:

  • If your query references an item in the item Dictionary, you should make sure that the query that you execute in the Product Information stage is designed to retrieve that value from the product database. For example, if the TableShippingADO component references _product_weight as a parameter to the component's query, then your product table should contain a column named weight, and your QueryProdInfoADO component should execute a query that retrieves this column to storage in the item Dictionary.


Tax Objects

Although Microsoft Commerce Server 2000 includes the Site Server 3.0 Commerce Edition tax components, those components will not work with the new multiple-shipment shipping architecture. Only the SampleRegionalTax pipeline component in Site Server 3.0 Commerce Edition takes into account the multiple-shipment shipping architecture.

Note

  • The tax components shipped with Commerce Server 2000 are provided only for evaluation and testing purposes. Microsoft strongly recommends that you have an independent tax professional verify all applicable tax rates and data generated by these components before you use such information for personal or business purposes.

This section contains:

  • Site Server 3.0 Commerce Edition Tax Components. Explains how to use Site Server 3.0 tax components.

See Also

SampleRegionalTax


Site Server 3.0 Commerce Edition Tax Components

The Tax stage and other tax components ensure that order._tax_total and order._tax_included keys are set. If not, an error is generated.

If you want to use the Site Server 3.0 Commerce Edition components, you will not be able to use the Splitter, ShippingMethodRouter, and StepwiseShipping pipeline components. For information about using Site Server 3.0 Commerce Edition shipping methods, see Using Site Server 3.0 Commerce Edition Shipping Components.

All components in the Tax stage will execute (unless a fatal error is returned). To cooperate, one component in the tax stage must set the _tax_total key, or a shopper warning is raised. Each component must check the resulting _tax_* values. If these values are already set, the component should return without doing anything. If the values are not set, the component will attempt to calculate the tax and if it is successful, set the _tax_* values.

In addition, some Site Server 3.0 Commerce Edition tax components require that the value of the _ship_to_country key is set to the intended country; otherwise, the component will not execute.

In each of the tax components, the country name can be specified as a parameter even though the name of the country is part of the name of the component (for example, SimpleCanadaTax). This is because the name of the component describes only the model for computing sales tax, and not the country to which it applies. For example, another country may actually use a tax model similar to Canada. Because the country name is specified, the tax model (and its corresponding component) can be used for more than one country.

See Also

DefaultTaxCy, DefaultTax

SampleRegionalTax

SimpleCanadaTax

SimpleJapanTax

SimpleUSTax

SimpleVATTax

RequiredTaxCy, RequiredTax


Business-to-Consumer Pipelines

The business-to-consumer Order Processing pipelines (OPP) are used in Commerce Server sites designed for retail shopping by the public. These pipelines implement functions that are performed at different times during the shopping process.

This section contains:

  • Product Pipeline (Product.pct). Runs OPP components that compute price and discount information on individual products. This pipeline is often used to compute information that is displayed on the Product.asp page.

  • Plan Pipeline (Plan.pct). Runs OPP components that present the user with an order total, including all promotional discounts, taxes, shipping and handling charges.

  • Purchase Pipeline (Purchase.pct). Runs OPP components that validate the payment for a user, performs the actual purchase transaction, writes an order to database storage and, optionally, finalizes a receipt by writing the contents of the OrderForm object to the receipt database.


Product Pipeline

The Product pipeline runs components that compute price and discount information on individual products. This pipeline is often used to compute information that is displayed on the Product.asp page.

The template for this pipeline is Product.pct.

The Product pipeline consists of the following stages:

  • Product Info Stage

  • Shopper Information Stage

  • Item Price Stage

  • Item Adjust Stage

  • Inventory Stage

Product Info Stage (Product Pipeline)

The Product Info stage contains components that retrieve product information about the items in the items list from the site database. If information about a given item cannot be retrieved, Product Info stage components mark the item for deletion by creating a delete key in the item Dictionary object, and giving it the value one (1).

After the Product Info components have been executed, the RequiredProdInfo component in the Product Info stage goes through the items list, deleting every item marked for deletion.

The components related to this stage are shown in the following table.

Component | Description
QueryCatalogInfo | Retrieves catalog information for every item in the order form. Uses the Commerce Server 2000 Product Catalog System. Marks missing items for deletion and adds basket errors if necessary.
QueryProdInfoADO | Executes a database query, based on the SKUs in the items list of the OrderForm object, and puts the returned data in the items collection of the OrderForm object. Marks missing items for deletion and adds basket errors as necessary.
RequiredProdInfo | Deletes items marked for deletion and writes the appropriate error messages.

Shopper Information Stage (Product Pipeline)

The Shopper Information stage adds information about the user to the OrderForm object.

The components related to this stage are shown in the following table.

Component | Description
DefaultShopperInfo | Copies information from the Shopper dictionary in the Context dictionary to the OrderForm object.

Item Price Stage (Product Pipeline)

The Item Price stage sets the _iadjust_regularprice key on each item in the order form.

The Item Price stage contains components that set the _iadjust_regularprice key for each item in the items list, as well as components that verify this value has been set. If this value cannot be set, an error occurs.

This initialization ensures that the _iadjust_regularprice dictionary key entry contains the most current price information for the given SKU.

The components related to this stage are shown in the following table.

Component | Description
DefaultItemPriceCy, DefaultItemPrice | For each item in the items list, sets the _iadjust_regularprice key to the value stored in the _product_list_price key.
RequiredItemPriceCy, RequiredItemPrice | Ensures that _iadjust_regularprice key is set for each item in the items list.

Item Adjust Price Stage (Product Pipeline)

The Item Adjust Price stage contains components to initialize the value of the_iadjust_currentprice key. When the stage is complete, _iadjust_currentprice key contains the current price of the item, adjusted for sales or promotions.

If no sale or promotion component is included in this stage, the key is set to the value stored in _iadjust_regularprice key.

Once the item._iadjust_currentprice key is set for an item, the item cannot be adjusted a second time. For example, if a stage includes both an ItemPromo and a SaleAdjust component, and an item on the order form qualifies for both the promotion and the sale adjustment, the _iadjust_currentprice key of the item is set by the component executed first within the stage. This generalization applies for any combination of Item Price Adjust stage components that you include in your pipeline.

Note

  • Do not use this stage to calculate discounts in new pipelines. Use the OrderDiscount component in the Order Adjust Price stage of the Plan pipeline. The OrderDiscount component uses the Commerce Server 2000 Targeting System to apply item and order discounts.

The components related to this stage are shown in the following table.

Component | Description
ItemPromo | Adjusts the value of the _iadjust_currentprice key, based on promotions.
SaleAdjust | Determines whether an item is on sale. If it is, the SaleAdjust component sets the _iadjust_currentprice key of the item to the value stored in the _product_sale_price key.
RequiredItemAdjustPriceCy, RequiredItemAdjustPrice | Verifies that the _iadjust_currentprice key exists and has a value.

Inventory Stage (Product Pipeline)

The Inventory stage contains components that verify that every item ordered is in stock.

The components related to this stage are shown in the following table.

Component | Description
FlagInventory | Flags items in the items SimpleList object that are out of stock.
LocalInventory | Checks the OrderForm object to ensure that an item does not require more of a given SKU than is in stock.

See Also

Plan Pipeline

Purchase Pipeline


Plan Pipeline

The Plan pipeline contains fourteen stages. These stages consist of components that verify the integrity of the OrderForm object. For example, if the items list in an OrderForm object contains no items, then the RequiredOrderCheck component in the Order Check stage generates an error.

The template for this pipeline is Plan.pct.

The Plan pipeline template consists of the following stages:

  • Product Info Stage

  • Merchant Information Stage

  • Shopper Information Stage

  • Order Initialization Stage

  • Order Check Stage

  • Item Price Stage

  • Item Adjust Price Stage

  • Order Adjust Price Stage

  • Order Subtotal Stage

  • Shipping Stage

  • Handling Stage

  • Tax Stage

  • Order Total Stage

  • Inventory Stage

Product Info Stage (Plan Pipeline)

The Product Info stage contains components that retrieve product information about items in the items list from the site database. If there is no information about an item, Product Info stage components mark the item for deletion by creating a delete key in the Item dictionary with a value of one (1).

After the Product Info stage components run, the RequiredProdInfo component in the stage goes through the items list, and deletes every item marked for deletion.

The components related to this stage are shown in the following table.

Component | Description
QueryCatalogInfo | Retrieves catalog information for every item in the order form. Uses the Commerce Server 2000 Product Catalog System. Marks missing items for deletion and adds basket errors if necessary.
QueryProdInfoADO | Executes a database query, using Microsoft ActiveX Data Objects (ADO). This component differs from the QueryProdInfo component in that the query that it executes can take multiple parameters, and can reference a query in the QueryMap dictionary.
RequiredProdInfo | Deletes any items marked for deletion and writes the appropriate error messages.

Merchant Information Stage (Plan Pipeline)

The Merchant Information stage can retrieve static merchant data and write the data to the OrderForm object. Commerce Server 2000 includes no component for this stage (other than the Scriptor component). However, you can add your own custom component to process merchant information. For more information see, Building Pipeline Components.

Shopper Information Stage (Plan Pipeline)

The Shopper Information stage contains the DefaultShopperInfo component, which adds shopper information to the OrderForm object.

The components related to this stage are shown in the following table.

Component | Description
DefaultShopperInfo | Copies information from the Shopper dictionary in the Context dictionary to the OrderForm object.

Order Initialization Stage (Plan Pipeline)

The Order Initialization stage sets initial order information on the OrderForm object and verifies that the OrderForm object contains an order ID.

The components related to this stage are shown in the following table.

Component | Description
RequiredOrderInitCy, RequiredOrderInit | Initializes the payment authorization code, order ID, totals, and subtotals prior to processing the order.

Order Check Stage (Plan Pipeline)

The Order Check stage verifies that the order can be processed.

The components related to this stage are shown in the following table.

Component | Description
RequiredOrderCheck | Ensures that there is at least one item in the OrderForm object.

Item Price Stage (Plan Pipeline)

The Item Price stage contains components that set the _iadjust_regularprice key for each item in the items list and components that verify that this value has been set. If this value cannot be set, an error occurs.

This initialization ensures that the _iadjust_regularprice key contains the most current price information for the given item.

The components related to this stage are shown in the following table.

Component | Description
DefaultItemPriceCy, DefaultItemPrice | For each item in the items list, sets the _iadjust_regularprice key to the value stored in the _product_list_price key.
RequiredItemPriceCy, RequiredItemPrice | Ensures that _iadjust_regularprice key is set for each item in the items list.

Item Adjust Price Stage (Plan Pipeline)

The Item Adjust Price stage contains components to initialize the value of the _iadjust_currentprice key. When the stage is complete, the _iadjust_currentprice key contains the current price of the item, adjusted for sales or promotions.

If no sale or promotion component is included in this stage, the key is set to the value stored in the _iadjust_regularprice key.

Once the item._iadjust_currentprice key is set for an item, the item cannot be adjusted a second time. For example, if a stage includes both an ItemPromo and a SaleAdjust component, and an item on the order qualifies for both the promotion and the sale adjustment, the _iadjust_currentprice key of the item is set by the component executed first within the stage. This generalization applies for any combination of Item Price Adjust stage components that you include in your pipeline.

Note

  • Do not use this stage to calculate discounts in new pipelines. Use the OrderDiscount component in the Order Adjust Price stage of the Plan pipeline. The OrderDiscount component uses the Commerce Server 2000 Targeting System to apply item and order discounts.

The components related to this stage are shown in the following table.

Component | Description
ItemPromo | Adjusts the value of the _iadjust_currentprice key, based on promotions.
SaleAdjust | Determines whether an item is on sale. If it is, the SaleAdjust component sets the _iadjust_currentprice key of the item to the value stored in the _product_sale_price key.
RequiredItemAdjustPriceCy, RequiredItemAdjustPrice | Verifies that the _iadjust_currentprice key exists and has a value.

Order Adjust Price Stage (Plan Pipeline)

The Order Adjust Price stage contains components that set the adjusted price of each item.

The item._oadjust_adjustedprice key contains the total cost of a given item. For example, if a user purchases three items costing $5.00 each, and none of the items are discounted, the total for the item is $15.00. If two of the items are sold at the regular price, but the third is sold at half price (because of a discount), the adjusted price is $12.50.

The components related to this stage are shown in the following table.

Component | Description
DBOrderPromoADO | Queries the database to determine a promotion amount.
OrderDiscount | Applies scheduled discounts to the shopping basket.
RequiredOrderAdjustPriceCy, RequiredOrderAdjustPrice | Checks the _oadjust_adjustedprice key member of each item in the items collection to ensure that it is set.

Order Subtotal Stage (Plan Pipeline)

The Order Subtotal stage calculates the subtotal for an order and stores the resulting value in the _oadjust_subtotal key of the OrderForm object. The _oadjust_subtotal key is the sum of the _oadjust_adjustedprice key for all items.

The components related to this stage are shown in the following table.

Component | Description
DefaultOrderSubtotalCy, DefaultOrderSubtotal | Calculates the subtotal for an order and stores the result in the order._oadjust_subtotal key.
RequiredOrderSubtotalCy, RequiredOrderSubtotal | Checks the order._oadjust_subtotal key to ensure that it is not NULL.

Shipping Stage (Plan Pipeline)

This stage calculates the total shipping charge for the order and sets the order._shipping_total key accordingly. For information about how the components in this stage interact, see Shipping Objects.

The components related to this stage are shown in the following table.

Component | Description
DefaultShippingCy, DefaultShipping | Ensures the integrity of the OrderForm object by setting the order._shipping_total key to zero (0).
FixedShipping | Sets the order._shipping_total key to a fixed amount.
LinearShipping | Sets the order._shipping_total key by multiplying a rate by the sum of a specified value on the OrderForm object.
ShippingDiscountAdjust | Applies shipping discounts to an order. The component uses the multiple-shipment shipping architecture.
ShippingMethodRouter | Looks up and runs the components to process the shipments and calculates the shipping total for the entire order. The component uses the multiple-shipment shipping architecture.
Splitter | Divides an order into groups based on a list of item keys. The component uses the multiple-shipment shipping architecture.
TableShippingADO | Sets the order._shipping_total key to a value returned by a specified query. Uses Microsoft ActiveX Data Objects (ADO) to perform the query, and can be included in a transacted pipeline.
RequiredShippingCy, RequiredShipping | Checks the OrderForm object to ensure that the order._shipping_total key has been set.

Handling Stage (Plan Pipeline)

If handling charges are not included in the shipping charge, this stage calculates the total handling charge for the order and sets the order._handling_total key accordingly.

Multiple components can be specified to allow for different handling charges depending on the handling component used. You can use the shipping components to calculate shipping and handling charges together. However, some tax systems require shipping and handling charges to be calculated and taxed separately.

This stage verifies that order._handling_total key is set. If not, it generates an error.

The components related to this stage are shown in the following table.

Component | Description
DefaultHandlingCy, DefaultHandling | Assigns zero (0) to the order._handling_total key.
FixedHandling | Assigns a fixed amount to the order._handling_total key.
LinearHandling | Calculates the handling by multiplying a rate by the sum of a specified item on the OrderForm object. Assigns the value to the order._handling_total key.
TableHandlingADO | Calculates the handling based on the results of a database query and assigns the value to the order._handling_total key. Uses Microsoft ActiveX Data Objects (ADO) to perform the query and can be included in a transacted pipeline.
RequiredHandlingCy, RequiredHandling | Checks the OrderForm object to ensure that the total handling (order._handling_total key) has been set.

Tax Stage (Plan Pipeline)

The tax stage computes the sales tax for each item in the order and the sum of tax for the entire order. The stage assigns values to the item._tax_total, order._tax_total, and order._tax_included keys accordingly. Multiple components can be specified to allow for different tax rates depending upon the destination country. For information about how these components interact, see Tax Objects.

The components related to this stage are shown in the following table.

Component | Description
DefaultTaxCy, DefaultTax | Sets the _tax_total and _tax_included keys on the OrderForm object to zero (0).
SampleRegionalTax | Calculates taxes using the multiple shipment features of Commerce Server 2000.
SimpleCanadaTax | Computes taxes for Canada, including GST (goods and services tax) and PST (provincial sales tax).
SimpleJapanTax | Computes the taxes for the Japanese model.
SimpleUSTax | Applies a given tax rate to any order sent to a specified state.
SimpleVATTax | Computes a value-added tax (VAT) on the items.
RequiredTaxCy, RequiredTax | Checks to ensure that the _tax_total and _tax_included keys in the OrderForm object do not have NULL values.

Order Total Stage (Plan Pipeline)

The Order Total stage sums the subtotal (less any discount), tax, shipping, and handling values and assigns the total to the order._total_total key.

The components related to this stage are shown in the following table.

Component | Description
DefaultTotalCy, DefaultTotal | Writes the total cost of the order to the _total_total key.
RequiredTotalCy, RequiredTotal | Performs a _VERIFY_WITH check of the OrderForm object.

Inventory Stage (Plan Pipeline)

This stage verifies that every item ordered is in stock. For information about how the inventory components interact, see Inventory Objects.

The components related to this stage are shown in the following table.

Component | Description
FlagInventory | Flags items in the items SimpleList object that are out of stock.
LocalInventory | Checks the OrderForm object to ensure that an item does not require more of a given SKU than is in stock.

See Also

Product Pipeline

Purchase Pipeline


Purchase Pipeline

The Purchase pipeline consists of three stages. These stages use components that accept the final purchase of an order form, write an order to database storage and, optionally, finalize a receipt and write the contents of the OrderForm object to the receipt database.

The Purchase pipeline can be run after you have run an OrderForm object successfully through the Plan pipeline, and have confirmed that the user wants to finalize a purchase.

Because Purchase pipeline components write to a database, a Purchase pipeline is often a transacted pipeline.

The template for this pipeline is Purchase.pct.

The Purchase pipeline template consists of the following stages:

  • Purchase Check Stage

  • Payment Stage

  • Accept Stage

Purchase Check Stage (Purchase Pipeline)

The Purchase Check stage is typically used to verify that the address and credit card information the user provides meets certain criteria.

In the Purchase.pct template, this stage contains no components by default.

This pipeline configuration contains two Scriptor components:

  • Validate Bill_to. Verifies that each of the bill_to_* fields on the order form contain data. If not, the script gets the appropriate message from the MessageManager object, adds the error text to the error list, and returns a return value of two (2) indicating that an error occurred.

  • Validate CC Info. Verifies that each of the credit card fields on the order form contain data, and that the credit card type is one of a list of acceptable values. If not, the script gets the appropriate message from the MessageManager object and adds the error text to the error list, and returns a return value of two (2) indicating that an error occurred.

The components related to this stage are shown in the following table.

Component | Description
ValidateCCNumber | Performs a standard checksum test on the credit card number and checks the expiration date.

Payment Stage (Purchase Pipeline)

The Payment stage is used to approve credit card payments. It sets the order._payment_auth_code key upon credit card approval. This stage always ensures that the _payment_auth_code key is set. Otherwise, it generates a pur_bad_payment error.

If a credit card is not approved, this stage sets the _payment_auth_code key to DENIED and returns error level 2.

The details of the payment components vary depending on the third-party payment processing system used.

The components related to this stage are shown in the following table.

Component | Description
DefaultPayment | Assigns an initial value to the _payment_auth_code key.
RequiredPayment | Ensures that the value of the _payment_auth_code key is not NULL.

Accept Stage (Purchase Pipeline)

The Accept stage handles the completed order, including initiating order tracking, generating purchase orders, and inventory.

The components related to this stage are shown in the following table.

Component | Description
ExecuteProcess | Executes an application on the server with the specified arguments.
MakePO | Generates a purchase order, based on a template file.
POtoFile | Sends a purchase order (typically the result of the MakePO component) to a file.
SaveReceipt | Writes the contents of the OrderForm object to the receipt storage.
SendSMTP | Sends an e-mail message to the specified address.
SQLItemADO | Runs the specified SQL command for each item in the order with the given fields from the order and item as arguments. This component uses Microsoft ActiveX Data Objects (ADO), and can be included in a transacted pipeline.
SQLOrderADO | Runs the specified SQL command once per order, with the given fields from the order as arguments. This component uses Microsoft ActiveX Data Objects (ADO), and can be included in a transacted pipeline.

See Also

Product Pipeline

Plan Pipeline


Using the Order Processing Pipeline

The Order Processing pipelines (OPP) provide much of the functionality for a working Web site, therefore understanding the components and processes of the OPP will aid in the development of a high-performance Web site.

This section contains:

  • OrderForm. Describes the structure of the OrderForm dictionary and how the OPP uses the dictionary.

  • Transactions and the Order Processing Pipeline. Describes the advantages of using transacted pipeline objects and how those objects work with COM+.

  • Error Handling. Describes the use of the MessageManager object with pipeline objects.

  • Using an Order Log. Describes how to use logging in pipelines when designing and debugging pipelines.

  • Displaying the Contents of an Order Form. Describes how to use Microsoft Visual Basic Scripting Edition (VBScript) in a Scriptor pipeline component to display the contents of an OrderForm dictionary.

  • Send a Purchase Confirmation by E-mail. Describes how to automatically send a purchase confirmation by e-mail when a new order is received.

  • Component Coordination. Describes how components within a pipeline stage coordinate their use of common OrderForm object keys.

  • Specifying the Basis Item Key. Describes how to specify the Basis Item key.

See Also

Shipping Objects

Inventory Objects

Tax Objects


OrderForm

The Order Processing pipeline (OPP) requires that data passed from the site to the pipeline, and from the pipeline to the site, be in an OrderForm object. This requirement applies to components included in the default OPP and to components designed to extend it.

The OrderForm object is a dictionary containing individual entries, and entries that are Dictionary and SimpleList objects. The structure makes it possible to present a detailed summary of all or part of one or more shopping sessions to the user or to the pipeline. This summary includes user data, such as name, address, and credit-card information, as well as product information related to the purchase.

The first element in the top-level Dictionary object of the OrderForm object is a reference to a SimpleList object of the items that make up the order. Each of these items is itself another Dictionary object. This SimpleList object is referred to as the items list.

The elements that make up both the order Dictionary object and the Dictionary objects in the items SimpleList object consist of a key and a value. Each component that you include in the OPP for your site is designed to operate on one or more of these keys and values. Typical operations include:

  • Key and value creation. Several components create keys and values in an OrderForm object. For example, the QueryCatalogInfo component gathers information about a product from a database, prepends _product_ to the column name, and adds the resulting key and value to the OrderForm object.

  • Key and value initialization. The Required components in the OPP fall into this category. These components check to make sure that certain keys are initialized with values, and if they are not, these components initialize them. Thus, the RequiredOrderInitCy component, which is part of the Order Initialization stage, sets the _cy_total_total, _cy_oadjust_subtotal, _cy_shipping_total, _cy_tax_total, _cy_handling_total keys to NULL.

  • Key and value verification. The OPP fails if certain keys and values in an OrderForm object are not initialized when the pipeline is invoked. For example, the RequiredOrderInitCy component verifies that the items SimpleList object on an OrderForm object is not empty. If this SimpleList object is empty, the component returns a status that indicates failure.

  • Key and value calculation. The optional components in the OPP initialize keys and values based on the work performed by other components. For example, the components in the Tax stage calculate the tax on an order, based on the list of items in the items SimpleList object of the OrderForm object, and writes the tax to the _tax_total key.

The underscore (_) character that precedes many of the keys in the OrderForm object indicates that the key is not persisted.

Note

  • The contents of an OrderForm object can vary, depending on how the pipeline for a site is configured.

Values Commonly Used in the OrderForm Object

Referencing Items on an OrderForm Object

Modifying the OrderForm Object

Values Commonly Used in the OrderForm Object

The following table lists the typical keys in the OrderForm object, and includes a brief description of each item. Where monetary values are involved, the currency version of the dictionary key is shown. For more information about naming conventions and currency data, see Currency Overview

Key | Definition
item._cy_iadjust_currentprice | Contains the current price of the item. Whereas the _cy_iadjust_regularprice key contains the regular price of the item, this key reflects the regular price minus any promotional discounts.
item._cy_iadjust_regularprice | Contains the regular price of the item. The DefaultItemPrice component, in the Item Price stage, initializes this key to the value in the _product_list_price key. The RequiredItemPrice component ensures that this key is initialized. Some promotional components use this key as the basis for price adjustments. For example, if an item is to be reduced by a given percentage, that percentage is based on the value stored in the_cy_iadjust_regularprice key.
item._cy_oadjust_adjustedprice | Total cost of this item. This key contains the current price of the item times the quantity, minus discounts resulting from a promotion or sale.
item._cy_tax_included | Value that indicates how much tax is included in the cost of the item.
item._cy_tax_total | Total tax for the items of this stock keeping number (SKU).
item._n_unadjusted | Number of items of this SKU that have not participated in a promotional price reduction.
item._product_* | Contains information about items of a given SKU. The key is initialized by the QueryProdInfoADO component. The key consists of the prefix _product_ followed by the name of the database table column from which the information was retrieved.
item.cy_placed_price | The price an item had when placed in the basket. Used to check for price changes during a purchase.
item.delete | A flag indicating the item should be deleted from the order. Set by the QueryCatalogInfo component and used by the RequiredProdInfo component.
item.discounts_applied | A dictionary containing the IDs of the discounts that apply to this item. Keys are the IDs, values are the date-time stamps of the discounts. Used by the OrderDiscount object.
item.list_price | The list price of the item.
item.quantity | Number of items of a given SKU.
order._Basket_Errors | A SimpleList object in which components in the OPP store basket error messages retrieved from the MessageManager object.
order._cc_expmonth | Month in which the provided credit card expires.
order._cc_expyear | Day on which the provided credit card expires.
order._cc_number | Credit card number for the card used to finance this purchase. By default, the SaveReceipt component, which persists other information in the OrderForm object, does not save credit card numbers.
order._cy_handling_total | Total cost for handling the order. This value is initialized by the Handling stage components (TableHandlingADO, FixedHandling).
order._cy_oadjust_subtotal | Subtotal of all the items in the items list. This value, which is initialized by the DefaultSubtotal component, represents a total of item._cy_oadjust_adjustedprice keys for each item in the list. The item._cy_oadjust_adjustedprice key represents the total for a given item (its quantity times its list price, minus promotional discounts).
order._cy_shipping_total | Total cost for shipping the items in the OrderForm object. By default, this is the key initialized by every shipping component.
order._cy_tax_included | Value that indicates how much tax is included in the cost of the order.
order._cy_tax_total | Total tax for this order. This key is initialized by the Tax stage components. How this value is calculated depends on the Tax stage component used.
order._cy_total_total | Total cost of the order, including the order subtotal, shipping, handling, and tax. This value is initialized by the DefaultTotal component, and is verified by the RequiredTotal component.
order._payment_auth_code | Payment authorization code for the order form.
order._Purchase_Errors | A SimpleList object in which components in the OPP store purchase error messages are retrieved from the MessageManager object.
order._Verify_With | A dictionary whose keys and values are tested against keys and values in the order form.
order.cc_name | Name that appears on the credit card used to finance the purchase. This key is initialized prior to the submission of the OrderForm object to the OPP.
order.cc_type | Type of credit card submitted. Valid types are VISA, MC, AMEX, or Discover. The ValidateCCNumber component uses this type as the basis for performing routine validation on the credit card number.
order.order_id | Unique identifier for this order.
order.shipment._cy_tax_included | Total tax for the shipment included in the cost. Part of the multiple-shipment shipping architecture.
order.shipment._cy_tax_total | Total tax for the shipment. Part of the multiple-shipment shipping architecture.
order.shipments | A SimpleList object of dictionaries, one dictionary per shipment. Part of the multiple-shipment shipping architecture.
order.shipments._cy_shipping_total | The shipping totals for each individual shipment. Part of the multiple-shipment shipping architecture.
order.shopper_id | Unique identifier for the user who submitted this order. This key is initialized prior to the submission of the order to the OPP.

The following table lists the name/value pairs on an OrderForm object and the OPP components that read from or write to the specified pair. Where monetary values are involved, the currency version of the dictionary key is shown. In the case where there are components that use only the non-currency version of the key, both forms are shown. For more information about the naming convention and currency data, see Currency Overview.

Key | Read By | Written By
item._cy_iadjust_currentprice | Not applicable | Not applicable
item._cy_iadjust_regularprice | Not applicable | Not applicable
item._cy_oadjust_adjustedprice | Not applicable | Not applicable
item._cy_tax_included | Not applicable | Not applicable
item._cy_tax_total | Not applicable | Not applicable
item._iadjust_currentprice | DbOrderPromoADO, ItemPromo, RequiredItemAdjustPrice, RequiredOrderAdjustPrice | ItemPromo, RequiredItemAdjustPrice, SaleAdjust
item._iadjust_regularprice | ItemPromo, RequiredItemAdjustPrice, RequiredItemPrice | DefaultItemPrice
item._inventory_backorder | Not applicable | FlagInventory, LocalInventory
item._n_unadjusted | DbOrderPromoADO, RequiredOrderInit | RequiredOrderInit
item._oadjust_adjustedprice | RequiredOrderAdjustPrice, SimpleCanadaTax, SimpleJapanTax, SimpleUSTax, SimpleVATTax | DbOrderPromoADO, DefaultOrderSubtotal, RequiredOrderAdjustPrice, RequiredOrderInit
item._oadjust_discount | Not applicable | RequiredOrderAdjustPrice
item._product_* | QueryProdInfoADO | Not applicable
item._product_gst | SimpleCanadaTax | Not applicable
item._product_in_stock | FlagInventory | Not applicable
item._product_jpn_tax_included | SimpleJapanTax | Not applicable
item._product_jpn_tax_rate | SimpleJapanTax | Not applicable
item._product_list_price | DefaultItemPrice | Not applicable
item._product_local_inventory | LocalInventory | Not applicable
item._product_pst | SimpleCanadaTax | Not applicable
item._product_sale_end | SaleAdjust | Not applicable
item._product_sale_price | SaleAdjust | Not applicable
item._product_sale_start | SaleAdjust | Not applicable
item._product_tax_rate | SimpleVATTax | Not applicable
item._tax_included | Not applicable | SimpleCanadaTax, SimpleJapanTax, SimpleUSTax, SimpleVATTax
item._tax_total | Not applicable | SimpleCanadaTax, SimpleJapanTax, SimpleUSTax, SimpleVATTax
item._tax_vat_item | Not applicable | SimpleVATTax
item.cy_placed_price | RequiredItemAdjustPrice | RequiredItemAdjustPrice
item.delete | RequiredProdInfo, QueryProdInfoADO | Not applicable
item.discounts_applied | Not applicable | Not applicable
item.list_price | Not applicable | Not applicable
item.quantity | DbOrderPromoADO, FlagInventory, LocalInventory, ReduceLocalInventory, RequiredItemAdjustPrice, RequiredOrderInit | RequiredOrderInit
item.sku | LocalInventory, QueryProdInfoADO, ReduceLocalInventory | Not applicable
order._Basket_Errors | Not applicable | RequiredProdInfo
order._cc_expmonth | ValidateCCNumber | Not applicable
order._cc_expyear | ValidateCCNumber | Not applicable
order._cc_number | ValidateCCNumber | Not applicable
order._cy_handling_total | Not applicable | Not applicable
order._cy_oadjust_subtotal | Not applicable | Not applicable
order._cy_shipping_total | Not applicable | Not applicable
order._cy_total_total | Not applicable | DefaultTotal, RequiredOrderInit
order._handling_total | RequiredHandling, DefaultTotal | RequiredOrderInit, DefaultHandling, FixedHandling, LinearHandling, TableHandlingADO
order._oadjust_subtotal | RequiredOrderSubtotal, DefaultTotal | DefaultOrderSubtotal, RequiredOrderInit
order._payment_auth_code | RequiredPayment | DefaultPayment, RequiredOrderInit
order._Purchase_Errors | Not applicable | FlagInventory, LocalInventory, RequiredHandling, RequiredItemAdjustPrice, RequiredOrderCheck, RequiredPayment, RequiredShipping, RequiredTotal, ValidateCCNumber
order._shipping_total | RequiredShipping, DefaultTotal | DefaultShipping, FixedShipping, LinearShipping, RequiredOrderInit, TableShippingADO
order._shopper_* | Not applicable | DefaultShopperInfo, QueryProdInfoADO
order._tax_included | Not applicable | DefaultTax, RequiredOrderInit, SimpleCanadaTax, SimpleJapanTax, SimpleUSTax, SimpleVATTax
order._tax_total | DefaultTotal | DefaultTax, RequiredOrderInit, SimpleCanadaTax, SimpleJapanTax, SimpleUSTax, SimpleVATTax
order._tax_total_gst | Not applicable | SimpleCanadaTax
order._tax_total_pst | Not applicable | SimpleCanadaTax
order._Verify_With | RequiredTotal | Not applicable
order.bill_to_* | Not applicable | Not applicable
order.cc_name | Not applicable | Not applicable
order.cc_type | ValidateCCNumber | Not applicable
order.date_changed | Not applicable | Not applicable
order.items | Not applicable | Not applicable
order.order_id | Not applicable | RequiredOrderInit
order.ship_to_city | Not applicable | Not applicable
order.ship_to_country | SimpleCanadaTax, SimpleJapanTax, SimpleVATTax | Not applicable
order.ship_to_state | SimpleCanadaTax, SimpleUSTax | Not applicable
order.ship_to_street | Not applicable | Not applicable
order.ship_to_zip | TableShippingADO, TableHandlingADO | Not applicable
order.shipment._cy_tax_included | Not applicable | Not applicable
order.shipment._cy_tax_total | Not applicable | Not applicable
order.shipments | Not applicable | Not applicable
order.shipments._cy_shipping_total | Not applicable | Not applicable
order.shipping_method | TableShippingADO, TableHandlingADO | Not applicable
order.shopper_id | Not applicable | Not applicable

Referencing Items on an OrderForm

Dictionary items are identified both by their names and by the section of the OrderForm object they are in. Thus, the cc_name item in the order Dictionary object is referenced as follows:

order.cc_name

Similarly, the elements of items in the items SimpleList object are prefixed with the word item:

item.SKU

This form of reference, while not necessarily technically accurate, allows for clarity of the description.

Modifying the OrderForm Object

When you pass an OrderForm object to the Order Processing pipeline (OPP), the OrderForm object must already be initialized with certain data elements.

You can modify an OrderForm object in any of the following ways:

  • By direct assignment. To initialize the shopper_id key in a page, you may make a direct assignment:

    objOrderForm.shopper_id = objPage.GetShopperID()

  • Using the native methods of the OrderForm object. The OrderForm object implements the AddItem, ClearItems, and Clear methods, which are designed to add items to the items SimpleList object, clear items from the items SimpleList object, and clear the entire OrderForm object, respectively.

  • Using the DBStorage object. The DBStorage object is designed to load a row of data from a database table into an OrderForm or Dictionary object. For more information, see DBStorage Object.


Transactions and the Order Processing Pipeline

A transaction is a series of operations performed as a single unit. In case of an error, the operations in a transaction can be undone. In the Active Server Pages (ASP) environment, transactions occur on a per-page level. To mark an ASP page as one that requires a transaction, you include the following script at the top of the page:

<%@ LANGUAGE=VBScript Transaction=Required%>

When you mark a page as transacted, the objects created on the page and the work those objects perform become part of the transaction, provided the objects are registered on the server as components supporting transactions. In the event of an error, the work performed by those objects can be rolled back.

Suppose, for example, that you create a page that includes an object using Microsoft ActiveX Data Objects (ADO) to insert or update data in a database. In the event that this component fails, you can call the SetAbort method of the ObjectContext object to abort the transaction. This will undo all of the modifications made by the object to the database.

Note

  • In Windows 2000, the transaction support provided by Microsoft Transaction Server (MTS) is now incorporated in COM+. The COM+ transaction support provides full backward compatibility with MTS. However, COM+ provides significant extensions to transactions. For more information, see "More on Porting Applications from MTS to COM+" on the MSDN Web site.

Calling Transacted Pipeline Objects

The Commerce Server Order Processing pipeline (OPP) supports COM+ transactions through the MtsTxPipeline and PooledTxPipeline objects. These objects are marked as requiring a transaction. If you create an MtsTxPipeline object or a PooledTxPipeline object on a page not marked as requiring a transaction, there is still a transaction, but the transaction includes only the pipeline and the components it runs. To extend the transaction to all operations on the page, the page must be marked as requiring a transaction.

In either case, the transaction support of the MtsTxPipeline object and the PooledTxPipeline object provides many benefits to the site builder. Most importantly, transaction support means that if any component in an MtsTxPipeline object or PooledTxPipeline object fails, the work of the preceding components in the pipeline is rolled back, and the pipeline object ends the transaction.

The transaction support of the MtsTxPipeline object and the PooledTxPipeline object is especially useful with pipeline components that modify the site database. If you use components that modify the database, and a component following them fails, the modifications the components made to the database are automatically rolled back. This is true whether or not the page is transacted because, as described above, the pipeline and the components it runs are always transacted.

For more information about the transacted pipeline objects, see MtsTxPipeline Object and PooledTxPipeline Object.


Error Handling

Error handling in a Commerce Server 2000 Web site revolves around the interaction of the Order Processing pipeline (OPP) with the OrderForm object, the pipeline objects (MtsPipeline, MtsTxPipeline, PooledPipeline, and PooledTxPipeline), and the MessageManager object.

The OrderForm object provides a detailed, in-memory summary of one or more shopping sessions, including merchant, user, and item information. You pass an initialized OrderForm object to the OPP by calling the Execute method of the pipeline object you are using.

As the OrderForm object goes through various stages of the OPP, the components in each stage read and write values to and from the OrderForm object.

For error processing, the critical members of the OrderForm object are its _Basket_Errors and _Purchase_Errors collections. These collections store strings describing error conditions the OPP detects while processing other elements of the OrderForm object.

The OPP gets the error strings from the MessageManager object. The MessageManager object is the central repository of locale-based error messages for a site. Each message stored in the MessageManager object consists of a string that describes a given error condition, and a string identifier that uniquely identifies the message to the OPP. The MessageManager object creates the association between the string identifier and the string message through the AddMessage method that adds a message to the MessageManager object.

Although the string describing an error may vary from one site to the next, the string ID identifying a message does not change. For example, if the OPP is unable to validate a credit card in the OrderForm object, the pipeline attempts to retrieve the string associated with the message ID pur_bad_cc in the MessageManager object for the site. If the site developer has not associated a string with this message ID, the error condition is ignored. Otherwise, the OPP retrieves this message and writes it to the _Purchase_Errors collection in the OrderForm object. When the Execute method returns, you can examine this collection, and the strings in it can be used to provide site users with detailed descriptions of errors that occurred during order processing. For more information, see MessageManager Object.

See Also

Error Levels


Using an Order Log

There are two ways to view Order Processing pipeline (OPP) information. You can create an OPP run-time information log, which includes all the keys and values written to the OrderForm object by each component in each stage. You can also view the contents of the OrderForm object using the DumpOrder sample Scriptor component. The DumpOrder sample is available in the Order Sitelet at: <Drive>:\Program Files\Microsoft Commerce Server\SDK\Samples\Sitelets\Order\source\pipeline.

You can log run-time information for each stage in the pipeline to a text file. By doing so, you see each stage and each component within that stage as it is executed, including the information written to the OrderForm object at each stage. This is especially useful for debugging an Order Processing pipeline. To do this, add a call to the SetLogFile method before the call to the Execute method.

When you run the pipeline, stage and component information is written to the file you specify.

Note

  • For the log file to be created, you must specify a location in which you have write permission; otherwise, the log file creation fails without a warning. Also be sure to comment out or delete the SetLogFile method when you have finished debugging the pipeline. Logging significantly slows down pipeline execution.

In the log file, components are numbered in the order that they are run and listed by name, but are not separated by pipeline stage.

The log file is easier to read if you use a spreadsheet application, such as Microsoft Excel, to view it.


Displaying the Contents of an Order Form

A sample Microsoft Visual Basic script, DumpOrder.vbs, is supplied in the <Drive>:\Program Files\Microsoft Commerce Server\SDK\Samples\Sitelets\Order\source\pipeline subdirectory. When it runs, DumpOrder writes the contents of the OrderForm object to a file.

To use the DumpOrder script

  1. Add the Scriptor component to any stage in the pipeline. Double-click its icon. In the resulting property page, click the Scriptor tab, click VBScript in the Language drop-down list, and then click File.

  2. In the File box, type the path to the DumpOrder.vbs file (or click Browse to find it).

  3. DumpOrder takes a file name as a parameter, so type the full path name of the output file in the Config field. For example, filename=c:\order.log.

  4. Click OK, and then save the pipeline configuration file.

  5. Stop and restart Internet Information Services (IIS), or modify the Global.asa file to restart the application. DumpOrder will write a file with the name you specified as a parameter when the Order Processing pipeline runs.

See Also

Scriptor

Configuring a Scriptor Component


Send a Purchase Confirmation by E-mail

This section describes the procedure for adding a pipeline component that will automatically send an e-mail order confirmation message when a new order is received. This example assumes that an e-mail address is required when users fill out their profile. This e-mail address is stored with the user information, and is therefore available in the order form.

In this example, the desired format of the confirmation e-mail is as follows:

Subject: Order Confirmation

Thank you for shopping at our store. Your order is confirmed.

Tracking number: 93LFF5XNE9SK2TVX00L1R0D9N7

Total purchase: $57.25

This section contains:

Step 1: Adding the Text Strings to the MessageManager Object

Step 2: Creating a Script to Format the E-mail messages

Step 3: Adding the Scriptor Component to the Pipeline

Step 4: Adding the SendSMTP Compoent to the Pipeline

Step 1: Adding the Text Strings to the MessageManager Object

The first step is to add the text of the message to the MessageManager object. Although this step is not strictly necessary (the text could appear as string literals in the script), using the MessageManager object centralizes all text for the site and makes it easy to add support for additional languages at a later time. Add the necessary messages to the MessageManager object by performing the following steps:

  1. Using a text editor, such as Notepad, open the retail site Global.asa file. The file is usually located at C:\Inetpub\wwwroot\retail.

  2. After the call to Main At the end of the list of MessageManager strings, add the following lines:
Dim oMessageManager
Set  oMessageManager = Server.CreateObject("Commerce.MessageManager")
Call oMessageManager.AddLanguage("usa", &H0409)
Call oMessageManager.AddLanguage("FRA", &H040c)
Call oMessageManager.AddLanguage("ENC", &H1009)
oMessageManager.defaultLanguage = "usa"
Call oMessageManager.AddMessage("email_subject", "Order Confirmation")
Call oMessageManager.AddMessage("email_body", "Thank you for shopping at our store. Your order is confirmed. ")
Call oMessageManager.AddMessage("email_tracking", "Tracking number: ")
Call oMessageManager.AddMessage("email_total", "Total purchase: ")

Step 2: Creating a Script to Format the E-mail Message

After the proper code has been added to the Global.asa file, the next step is to create a script that formats the e-mail message. The script is to be used in a Scriptor component. The script must add the subject and message body text to the order form, so that a later component in the pipeline can send the e-mail.

Create a file named Email.vbs in the <drive:>\Inetpub\wwwroot\<sitename>\pipeline directory. Using a text editor such as Notepad, type or copy the following script into the file:

Function mscsexecute(config, orderform, context, flags)
    Dim oMessageManager, oDataFunctions
    Set oMessageManager = context.MessageManager
    Set oDataFunctions = context.DataFunctions

    orderform.[_email_subject] = _
              oMessageManager.GetMessage("email_subject")
    orderform.[_email_body] = _
              oMessageManager.GetMessage("email_body") _
              & chr(10) & chr(13) _
              & oMessageManager.GetMessage("email_tracking") _
              & orderform.[order_id] _
              & chr(10) & chr(13) _
              & oMessagemanager.GetMessage("email_total") _
              & oDataFunctions.Money(CLng(orderform.[_total_total]))
    mscsexecute = 1
End Function

When this script is executed by a Scriptor component in the pipeline, it adds two new fields to the order form: _email_subject is used as the subject line for the e-mail, and _email_body is used as the body of the e-mail.

The script formats these strings by getting the appropriate messages from the MessageManager object and concatenating these strings with values from the order form, including the tracking number (order_id) and the purchase total (_total_total).

mscsMessagemanager.GetMessage("email_tracking") & orderform.[order_id]

generates this portion of the e-mail message body:

Tracking number: 93LFF5XNE9SK2TVX00L1R0D9N7

To format the total price as text in the local currency, the price is converted from numeric form as it is stored in the order form, using the DataFunctions.Money method.

Because the script uses methods of both the MessageManager object and the DataFunctions object, it first creates references to these objects. These references are provided by the PipeContext dictionary, which is passed in as an argument to the pipeline.

The function concludes with the following script, which indicates that the component executed successfully in the pipeline:

mscsexecute = 1

Note

  • In a site where the e-mail field is optional, make sure that the SendSMTP component does not attempt to send e-mail. You can disable the SendSMTP component by submitting a To field that contains the text None. The Email.vbs script can check for the existence of an e-mail name. If the user did not provide such a name, the script would substitute the text None.

Step 3: Adding the Scriptor Component to the Pipeline

In order to execute the Email.vbs script within the OPP, a Scriptor component must be added to the Purchase pipeline configuration, as described in the following steps:

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2000, and then click Pipeline Editor.

  2. Open the Purchase.pct template, or the purchase pipeline for your site. Pipelines used in active sites are usually stored at C:/Inetpub/wwwroot/<site name>/pipeline.

  3. Open the Accept stage.

  4. Right-click the last component in that stage, or on the Accept stage itself if there are no components in the stage.

  5. Right-click Insert Component, and then click After.

  6. In the Choose a component dialog box, click Scriptor, and then click OK.

    The Scriptor component is added to the Accept stage.

  7. Double-click the Scriptor component icon.

  8. In the Component Properties dialog box, do the following:
    Use this | To do this
    Scripting Engine | Select VBScript.
    Source | Select External.
    Filename | Click Browse to find the location of the Email.vbs file, or type the path to the Email.vbs file.

  9. On the Component Properties tab, edit the Label box to provide a more helpful description (for example, Scriptor: Email.vbs (Format e-mail confirmation).

  10. Click OK to close the property page.

Step 4: Adding the SendSMTP Component to the Pipeline

The final step is to add the SendSMTP component to the Purchase pipeline configuration:

  1. In the Pipeline Editor, right click the Scriptor component that you just added in Step 3: Adding the Scriptor Component to the Pipeline.

  2. Right-click Insert Component, and then click After.

  3. In the Choose a component dialog box, click SendSMTP, and then click OK.

  4. Double-click the SendSMTP component or its icon in the Pipeline Editor.

    The Component Properties dialog box appears.

  5. On the Component Properties dialog box, on the SendSMTP tab, do the following.
    Use this | To do this
    From | Type the e-mail account of the computer from which the e-mail is sent.
    SMTP Host | Type the active SMTP host name that the computer uses to send e-mail.
    To | Type _shopper_email.
    cc | Leave blank
    Subject | Type _email_subject.
    Message Body | Type _email_body.
    Message Body Contains | Select one of the three choices based on the content of your e-mail. For our example, select Text Body.

    These values in the order form object will be used to format the e-mail. On the To line, _shopper_email, is part of the user information that is added to the order form; on the Subject and Message Body lines,_email_subject and _email_body are the values added to the order form by the Email.vbs script.

  6. On the Component Properties dialog box, on the SendSMTP tab, do the following:
    Use this To do this
    Email address to send test message to: Type an e-mail address to send the test message to.

  7. Click Send test Email button.

    The test e-mail message will appear in the inbox of the specified recipient.

  8. On the Component Properties tab, in the Label box, type a description.

  9. Click OK to close the property pages.

  10. On the File menu, click Save As.

  11. In the Save As dialog box, browse to the location where you would like to save the file, and then click Save.

  12. On the File menu, click Exit.

Reload the site so that your changes to the Global.asa file take effect.

Note

  • When adding components to a pipeline, it is important to consider the order in which the components appear. In the case of confirmation by e-mail, once the SendSMTP component has successfully sent the e-mail, the e-mail cannot be recalled if subsequent pipeline components fail. For this reason, the e-mail components have been placed last in the pipeline configuration. In this way, the e-mail is sent only if all other components succeed.

Using a Template

Depending on the complexity of the desired e-mail reply, you may prefer to use a template to generate the e-mail message body. The component combines values on the order form with text in a template file.

To use a template, create a script to format the subject line and to convert any numeric values to their displayable text form. The following script does not generate the message body. The following file, Email.vbs, is loaded into a Scriptor component:

Function mscsexecute(config, orderform, context, flags)
    Dim mscsDataFunctions
    Set mscsDataFunctions = context.DataFunctions

    orderform.[_email_subject] = "Order Confirmation"
    orderform.[_email_total] = mscsDataFunctions.Money(CLng(orderform.[_total_total]))
    mscsexecute = 1
End Function

Next, create a template file. In this example, the file is named Confirm_Template.vbs, and resides in the <drive:>\Inetpub\wwwroot\<sitename>\pipeline directory:

Thank you for shopping at our store. Your order is on its way.

Tracking number: <%%= order_id %%>
<%% Dim nItemcount
    nItemCount = Items.Items.count
if (nitemcount > 0) then
    dim iItem,Item
    for iItem = 0 to nitemcount - 1
    Set Item = Items.Items.Item(iItem) %%>
<%%= item.quantity %%> <%%= item.[_product_name] %%> <%%
    next
end if  %%>

Total purchase: <%%= [_email_total] %%>

Using the Pipeline Editor, insert a MakePO component in the Accept stage, immediately following the Scriptor component. Specify the Template File Name to indicate the template file just created (Confirm_Template.exe). Specify the Output Property Name as _email_body. The MakePO component, when run, will merge the template text with the values on the order form specified by the commands in the template, and write the result to the _email_body name/value pair in the order form.

Insert after the MakePO component the SendSMTP component as described in Step 4: Adding the SendSMTP Component to the Pipeline. The SendSMTP component, when run, will use the subject line text generated by the Scriptor component, and the body message generated by the MakePO component.

The following is an example of a message body generated by this template:

Thank you for shopping at our store. Your order is on its way.

Tracking number: 8BMKQ3NHKES12M9D00L1R0D8N7

1 Plastic Commuter Mug

Total purchase: $14.28


Using the Scriptor Component

The Scriptor component makes it possible to insert code modules into your pipeline. These modules are written using Microsoft Visual Basic Scripting Edition (VBScript). From within a Scriptor component, you can access the OrderForm object, pipeline context information, create other objects, and even execute other pipelines. In addition, because the Scriptor component supports configuration parameters, the Scriptor component provides perhaps the easiest way to write custom components for the Order Processing pipeline (OPP).

When you add a Scriptor component to your pipeline, you configure the component using the Component Properties dialog box. For more information about using the Component Properties dialog box, see Configuring a Scriptor Component.

Scriptor Methods

When you display the property pages for a Scriptor component in the Pipeline Editor, select Internal, and then click the Edit button. The Scriptor component displays an edit window that contains the three routines that the Scriptor component can process:

'The following entry points are available (shown in VBScript format):

function MSCSExecute(config, orderform, context, flags)

    MSCSExecute = 1

end function

sub MSCSOpen(config)

end sub

sub MSCSClose()

end sub

These routines are called entry points for the Scriptor component, and you can think of them as you would think of the event handlers for a Visual Basic object or Microsoft ActiveX control. You fill in the body of these routines with your own task-specific scripting code, and when the Order Processing pipeline (OPP) runs the Scriptor component, it executes the code that you write.

The script that you write for your MSCSOpen subroutine is executed immediately after the Scriptor component is created. The MSCSExit subroutine is executed after the Scriptor component is destroyed. The MSCSExecute function is called after the MSCSOpen subroutine, but before the MSCSExit subroutine.

Of the three exports that make up a default Scriptor component, only the MSCSExecute function is required. The parameters that the Scriptor component passes to this function include the following:

  • config. The configuration Dictionary for the script, which contains the information in the following table.
    Name | Value
    User-defined configuration parameters | Parameter value. For example, if you type tax=1 in the Config box on the property page for the Scriptor component, the tax name/value pair appears in the Configuration dictionary.
    script_type | Identifies whether the script is internal or external. If internal, script_type contains the value INTERNAL; otherwise, it contains the value EXTERNAL.
    script_text | Contains the entire script for the component.
    script_name | Contains the fully qualified path to the file that contains the script to execute. If the script_type is INTERNAL, this name/value pair does not contain a value.
    engine_prog_id | Identifies the scripting engine used to interpret the script. Possible values are VBScript and JScript.

  • orderform. The OrderForm object that you pass to the Execute method of the pipeline object.

  • context. The Context dictionary that you pass to the Execute method of the pipeline object.

  • flags. The flags that you pass to the Execute method of the pipeline object.


Using the ExecuteProcess Component

The ExecuteProcess component runs a specified executable, passing the executable the arguments that you provide. The process must not display any user interface elements. This component is typically run during the Accept stage, but can be run in any stage.

See Also

ExecuteProcess


Component Coordination

Because Commerce Server 2000 pipeline components run in a linear fashion, certain coordination must exist between those components. Component coordination is critical when multiple components exist within the same stage but only some of the components in the stage will be implemented. The components that are implemented correlate to the actions of the Web site user. For example, the Payment stage may include one component that implements payment by electronic currency, and another that charges to a credit card. But you only want to run the component that corresponds to the request made by the user. If the user would like to pay by credit card, the payment by electronic currency component should not be run.

The Commerce Server pipeline architecture dictates that components in certain stages must coordinate to allow such multiple-choice components to exist in the same stage. The components that come with Commerce Server 2000 already follow this convention, and special care must be taken when writing your own components to ensure that they follow this convention.

Keep the following in mind when you create new components:

  • If the value that the component is supposed to compute is already set when the pipeline component begins running, the component should immediately exit. For example, if the user chooses to pay by credit card and the credit card component is run before the electronic currency component, then the credit card component will set the payment_method key to credit card. Then, when the electronic currency component is run, it should see that the payment_method key has been set and should exit.

  • If a component determines that it cannot or should not perform the task for the stage, it should leave the dictionary entry for the stage alone. The payment_method key is a commonly used apply dictionary key in the Payment stage and the component should only continue to run if the proper payment_method key value is set. For example, the user chose to pay by credit card and the credit card component set the payment_method key to credit_card. Then, when the electronic currency component is run it checks to see if the payment_method key is set to electronic currency, and when it determines that the payment method key is not set to electronic currency, it should not apply the rest of the component by charging the user via electronic currency.

Component coordination is critical in the following stages:

  • Shipping. Component coordination is critical for backward compatable components, but usually is not neccessary when using the new multiple-shipping shipment architecture in Commerce Server. The _cy_shipping_total key must be coordinated. The shipping_method key is the apply key.

  • Handling. The _cy_handling_total key must be coordinated. The shipping_method key is the apply key.

  • Tax. Although this stage should be coordinated, it is recommended that you only have one tax component in your pipeline. Having only one tax key makes Business Desk management easier. The _cy_tax_total is the key to coordinate. The country key is the apply key.

  • Payment. The payment_method key is the key to coordinate and the apply key.

For information about building pipeline components, see Building Pipeline Components.


Specifying the Basis Item Key

Many of the Order Processing pipeline components use a Basis Item Key to determine applicable rates. For this key, you can use any of the values in the following table.

Basis Item Key Prefix | Description
order.fieldname | The value of the specified field, where fieldname is a property on the order form.
sum.fieldname | The sum of the value of the specified field for each item, where fieldname is a property in the item list.
sumq.fieldname | The sum of the value of the specified field for each item, where fieldname is a property in the item list, times the quantity of that item.
count | The number of line items in the order form. (Does not depend on quantity of each item.)

The following table shows some useful values for the Basis Item Key.

Example Basis Item Key | Result
order._oadjust_subtotal | Subtotal on the order form.
sum.quantity | Sum of all quantities (total number of items ordered).
sum._oadjust_adjustedprice | Sum of adjusted prices.
sumq._iadjust_currentprice | Sum of current price times quantity for all items in the order.
sumq._product_weight | Total weight of order. (Assumes that the weight column exists in the product table and that the query used by the QueryProdInfoADO component includes this field.)

For example, if the sumq._product_weight key is specified, and if the order has two items, one item weighing 2 pounds with a quantity of 3 and the other item weighing 4 pounds with a quantity of 1, then the basis value is 10 pounds.


Order Processing Component Reference

The following components are commonly run in the Order Processing pipeline (OPP):

  • DBOrderPromoADO

  • DefaultHandlingCy, DefaultHandling

  • DefaultItemPriceCy, DefaultItemPrice

  • DefaultOrderSubTotalCy, DefaultOrderSubTotal

  • DefaultPayment

  • DefaultShippingCy, DefaultShipping

  • DefaultShopperInfo

  • DefaultTaxCy, DefaultTax

  • DefaultTotalCy, DefaultTotal

  • ExecuteProcess

  • FixedHandling

  • FixedShipping

  • FlagInventory

  • ItemPromo

  • LinearHandling

  • LinearShipping

  • LocalInventory

  • MakePO

  • MoneyConverter

  • OrderDiscount

  • POtoFile

  • QueryCatalogInfo

  • QueryProdInfoADO

  • RequiredHandlingCy, RequiredHandling

  • RequiredItemAdjustPriceCy, RequiredItemAdjustPrice

  • RequiredItemPriceCy, RequiredItemPrice

  • RequiredOrderAdjustPriceCy, RequiredOrderAdjustPrice

  • RequiredOrderCheck

  • RequiredOrderInitCy, RequiredOrderInit

  • RequiredOrderSubtotalCy, RequiredOrderSubtotal

  • RequiredPayment

  • RequiredProdInfo

  • RequiredShippingCy, RequiredShipping

  • RequiredTaxCy, RequiredTax

  • RequiredTotalCy, RequiredTotal

  • SaleAdjust

  • SampleRegionalTax

  • SaveReceipt

  • Scriptor

  • SendSMTP

  • ShippingDiscountAdjust

  • ShippingMethodRouter

  • SimpleCanadaTax

  • SimpleJapanTax

  • SimpleUSTax

  • SimpleVATTax

  • SQLItemADO

  • SQLOrderADO

  • StepwiseShipping

  • TableHandlingADO

  • TableShippingADO

  • ValidateCCNumber


Direct Mailer Pipeline

The Commerce Server Direct Mailer program (Dmlrun.exe) uses a pipeline to process the list of recipients. You can add new components to the pipeline, integrate the components with line-of-business systems, or replace them with components supplied by third parties.

This section contains:

  • About the Direct Mailer Pipeline. Describes the function and structure of the Direct Mailer pipeline.

  • Stages and Components of the Direct Mailer Pipeline Describes the individual stages in the pipeline and the components most often used in those stages.

  • Using the Direct Mailer Pipeline. Explains how to use the Direct Mailer pipeline.

  • Direct Mailer Component Reference. Lists the pipeline components used in the Direct Mailer pipeline.


About the Direct Mailer Pipeline

The Commerce Server Direct Mailer program (Dmlrun.exe) uses a pipeline to process the list of recipients. In general, you will use the Direct Mailer pipeline as it is shipped with the product. However, you can add your own or third-party components to extend the features of the pipeline. For more information, see Building Pipeline Components.

Because of the load on a server, installing the Direct Mailer service on a separate server is recommended. For information about running Direct Mailer, see Running Direct Mailer.

This section contains:

  • Stages and Components of the Direct Mailer Pipeline. Describes the components in each stage of the Direct Mailer pipeline.


Stages and Components of the Direct Mailer Pipeline

The Direct Mailer pipeline runs components to screen recipients, personalize e-mail, and send the personalized e-mail. The following table lists the stages of the pipeline.

Stage | Description
Throttle | Controls the speed of the Direct Mailer process.
Preprocess Recipient | Verifies the data about the recipient.
Filter Recipient | Allows additional filtering of the recipient list.
Create Cookies | Creates the cookies used to produce personalized content. The Direct Mailer uses a Web server to generate the content.
Compose E-mail | Composes and formats the message.
Send E-mail | Sends the message.
Postprocess Recipient | Updates the Direct Mailer database to mark those messages that were sent, and writes the appropriate error messages if needed.

Throttle Stage

The Throttle stage controls the speed with which direct mail messages are processed by the pipeline. This controls the load on the Simple Mail Transfer Protocol (SMTP) server.

The components related to this stage are shown in the following table.

Component | Description
ThrottleDMLPerformance | Waits a specified number of milliseconds. The Direct Mailer program, Dmlrun.exe, calculates the delay needed to maintain an appropriate delivery rate. It passes this delay to the ThrottleDMLPerformance component through the Context dictionary.

Preprocess Recipient Stage

The Preprocess Recipient stage verifies data such as there being a recipient address.

The components related to this stage are shown in the following table.

Component | Description
VerifyRecipientData | The VerifyRecipientData component checks multiple values in the pipeline dictionaries to verify data about the recipient. If any one of the checks fails, the component sets rcp_bypass to True so that subsequent components in the pipeline skip the recipient.

Filter Recipient Stage

The Filter Recipient stage can perform additional filtering of potential e-mail recipients. Commerce Server 2000 includes no component for this stage (other than the Scriptor component). However, you can add your own custom component to perform filtering. For more information, see Building Pipeline Components.

Testing recipient names against an opt-out list could be performed in this stage. However, you may have better performance if you remove the opt-out names from the mailing list in the List Manager module before running the mail job.

Components that you write for this stage should check and, if necessary, set the rcp_bypass key in the Order dictionary. The component should set the rcp_bypass key to True if subsequent components in the pipeline should skip the recipient.

Create Cookies Stage

This stage collects data to create a cookie to use with an Active Server Page to generate a personalized message.

The components related to this stage are shown in the following table.

Component | Description
CreateUPMCookie | Combines information from the Order and Context dictionaries and creates a Cookie dictionary in the Order dictionary containing the information.

Compose E-mail Stage

The Compose E-mail stage creates the body of the e-mail message and adds any attachments.

The components related to this stage are shown in the following table.

Component | Description
ComposeDMLMessage | Creates the body of a direct mail e-mail message. Generates the cookie from data in the Cookie dictionary if the e-mail is personalized.
AddAttachments | Uses the Collaboration Data Objects (CDO) for Microsoft Windows 2000 to add the attachments to the message.

Send E-mail Stage

The Send E-mail stage verifies the body of a direct mail e-mail message and sends the message.

The components related to this stage are shown in the following table.

Component | Description
VerifyMessageBody | Use this component to check the body of a direct mail e-mail message.
SendPrecomposedMessage | Use this component to send a direct mail e-mail message composed in earlier stages in the pipeline.

Postprocess Recipient Stage

The Postprocess Recipient stage can perform additional recipient processing such as recording information in a database. Commerce Server 2000 includes no component for this stage (other than the Scriptor component). However, you can add your own custom components. For more information, see Building Pipeline Components.


Using the Direct Mailer Pipeline

You can create personalized direct mail e-mail messages by writing a custom ASP page. Similarly, you can add third party or custom components to the Commerce Server Direct Mailer pipeline. Those components need implement only the standard pipeline component interfaces. They also, however, need to understand the dictionary keys used by components in the pipeline.

This section contains:

  • Developing Direct Mail Content. Describes how to write an ASP page for use in sending personalized direct mail e-mail.

  • Implementing Direct Mail Opt-Out. Contains information on how to provide a link in direct mail e-mail messages to allow users to opt-out of future mailings.

  • Values in the Direct Mailer Pipeline Dictionaries. A list of the keys used in the Direct Mailer pipeline dictionaries.


Developing Direct Mail Content

The Direct Mail module of Commerce Server 2000 allows you to send targeted email messages by using customer information and custom Active Server Pages (ASP). Direct Mailer acts similarly to a Web browser by gathering the UserID for the customer from a cookie, using the profile service to obtain the user profile, and finally personalize the page. But Direct Mailer renders the content as an E-mail message instead of a Web page.

The following example, ServiceReminder.asp, can be used to create Direct Mail content. When implemented, this ASP file will send out personalized E-mail messages reminding each of your customers to come to your Web site to view new products. The ASP file also includes an opt-out link if they would like to be removed from your mailing list.

In this example, the UserID is retrieved from the AuthManager object, and the UserObject profile is retrieved from the profile service. For personalization to work correctly with this example, the mailing list must include both an E-mail address and a UserID for all entries. If the mail list has no UserID, the mail will not be sent. If the personalization flag is not turned on, the mail will not be sent. For more information about creating a mailing list, see Creating a Mailing List.

<%@ Language=VBScript %>

<%

Option Explicit

Response.AddHeader "pragma", "no-cache"

Response.Expires = 0

%>

<html>

<head>

</head>

<div class=Section1>

<%

Dim objAuthManager

Dim objUPM

Dim objProfile

Dim strUserID

Dim sCookieData

On Error goto 0

' Get User ID from AuthManager object.

SET objAuthManager = Server.CreateObject("Commerce.AuthManager")

objAuthManager.Initialize(Application("MSCSCommerceSiteName"))

if( Err.number <> 0 ) Then

Response.Write "<P>AuthManager Failed to initialize</P>"

End If

If Request.Cookies("CampaignItemID") <> "" Then' Part of a Campaign

strUserID = objAuthManager.GetUserID(1)

if( Err.number <> 0 ) Then

Response.Write "<P>Failed to get UserID</P>"

End If

Else' Not part of a Campaign

' The fix for being able to send personalized direct mail outside ' of a campaign is to toggle the comments on the two lines below.

' But please ensure that the web server that generates the

' personalized content is placed behind a firewall (since the user

' guid that is passed in not encrypted in this case).

Err.Raise  &H80004005, , "Error: CampaignItemID was not specified"

' strUserID = Request.Cookies("MSCSProfile")

End If

' Get UserObject from profile Service

Set objUPM = Application("MSCSProfileService")

If (Err.Number <> 0) Then

  Response.Write "<P>Failed to create Commerce.ProfileService</P>"

End If

Set objProfile = objUPM.GetProfileByKey("User_ID", strUserID, "UserObject")

If (Err.Number <> 0) Then

  strErrMsg = "<P>User profile not found: " & strUserID & "</P>"

  Response.Write strErrMsg

End If

%>

<table border=1 cellspacing=0 cellpadding=0 bgcolor="#ffff99" style='background:

 #FFFF99;border-collapse:collapse;border:none;mso-border-alt:solid windowtext .5pt;

 mso-padding-alt:0in 5.4pt 0in 5.4pt'>

 <tr>

  <td width=655 valign=top style='width:490.9pt;border:solid windowtext .5pt;

  padding:0in 5.4pt 0in 5.4pt'>

  <p class=MsoPlainText><span style='font-family:Tahoma;

    mso-fareast-font-family: "MS Mincho"'>

    From: E-mail Notifier<o:p></o:p></span></p>

  <p class=MsoPlainText><span style='font-family:Tahoma;

    mso-fareast-font-family:

    "MS Mincho"'>Sent: <% = Date() %><o:p></o:p></span></p>

  <p class=MsoPlainText><span style='font-family:Tahoma;

    mso-fareast-font-family:

    "MS Mincho"'>To: <% = objProfile.GeneralInfo.First_Name %><o:p> </o:p><% = objProfile.GeneralInfo.Last_Name %><o:p></o:p></span></p>

  <p class=MsoPlainText><span style='font-family:Tahoma;

    mso-fareast-font-family:

    "MS Mincho"'>Subject: </span><b><span style='font-size:12.0pt;

    mso-bidi-font-size: 10.0pt;font-family:Tahoma;

    mso-fareast-font-family:"MS Mincho";color:blue'>

    New product notice</span></b><span style='mso-fareast-font-family:

    "MS Mincho"'><o:p></o:p></span></p>

  </td>

 </tr>

</table>

<p class=MsoPlainText><b><span style='font-size:12.0pt;

    mso-bidi-font-size:10.0pt; mso-fareast-font-family:

    "MS Mincho";color:blue'><![if

    !supportEmptyParas]>&nbsp;<![endif]><o:p></o:p></span></b></p>

<p class=MsoPlainText><span style='font-family:Tahoma;

    mso-fareast-font-family:

    "MS Mincho"'>Dear <% = objProfile.GeneralInfo.First_Name

    %>,<o:p></o:p></span></p>

<p class=MsoPlainText><span style='font-family:Tahoma;

    mso-fareast-font-family:

    "MS Mincho"'><span style="mso-spacerun: yes">

    </span><o:p></o:p></span></p>

<p class=MsoPlainText><span style='font-family:Tahoma;

    mso-fareast-font-family: "MS Mincho"'>

    <span style="mso-spacerun: yes"> </span>We have added some exciting

    new products to our Web site. <o:p></o:p>

    <A HREF="<% =objAuthManager.GetUrl("default.asp", False, False)

    %>">Come see us today!</A>.<o:p></o:p></span></p>

<p class=MsoNormal style='mso-layout-grid-align:none;

    text-autospace:none'><span style='font-size:10.0pt;

    font-family:Arial;color:navy'>

    <![if !supportEmptyParas]>&nbsp;<![endif]><o:p></o:p></span></p>

<p class=MsoNormal style='mso-layout-grid-align:none;

    text-autospace:none'><span style='font-size:10.0pt;

    font-family:Arial;color:navy'><span style='mso-tab-count:

    1'> </span><o:p></o:p></span></p>

<p class=MsoPlainText><span style='mso-fareast-font-family:

    "MS Mincho"'>__________________________________________

    <o:p></o:p></span></p>

<p class=MsoPlainText><i><span style='font-size:8.0pt;

    mso-bidi-font-size:10.0pt; font-family:Verdana;

    mso-fareast-font-family:"MS Mincho"'>TO UNSUBSCRIBE: You

    have received this e-mail notifier as a result of your personal

    registration.<BR>To unsubscribe from this e-mail notifier, click

    the link below. <o:p></o:p></span></i></p>

<p class=MsoPlainText><i><span style='font-size:8.0pt;

    mso-bidi-font-size:10.0pt;

    font-family:Verdana;mso-fareast-font-family:"MS Mincho"'>

    <A HREF="<% On Error Goto 0

    Response.Write objAuthManager.GetUrl

        ("opt-out.asp", False, False, _

         Array("rcp_email", "campitem_id", "campitem_name"), _

         Array(CStr(objProfile.GeneralInfo.email_address),

         CStr(Request.Cookies("CampaignItemId")),

         CStr(Request.Cookies("CampaignItemName"))) _

        ) %>">Click here to opt-out of future

        mailings.</A><o:p></o:p></span></i></p>

</div>

</body>

</html>

To use this example you must first create a campaign. For more information, see Creating a Direct Mail Campaign.

On the Campaign Manager <Customer> <Campaign> New (direct mail) screen, in the Direct Mail Properties section, do the following.

Use this | To do this
Direct mail name | Type a name for the direct mail job.
Message from e-mail address | Type the address that the direct mail is being sent from.
Reply to e-mail address | Type the address to which the recipient is to reply if different from the default address. This box defaults to the address the direct mail is being sent from.
Message subject | Type the subject text for this direct mail job.
File path or URL containing message body | Type the URL that you are using to display the direct mail message. For example, http://<host_name>/<site_name>/ServiceReminder.asp.
Attachment | Leave blank.
Mailing list | Select the mailing list that this direct mail campaign will use from the drop-down list. This mailing list must have E-mail addresses and valid UserIDs, other columns are optional.
Personalize direct mail per user | Select the checkbox.
Mail format | Select MHTML.
Comments (not included in message) | Type any required comments that are pertinent to this direct mail job.

If you are sending the ServiceReminder.asp code from the command line you must comment out the following line:

Err.Raise  &H80004005, , "Error: CampaignItemID was not specified"

and uncomment the following line:

' strUserID = Request.Cookies("MSCSProfile")

as descibed in the comments of the ServiceReminder.asp code.

For more information about sending a test message, see Testing a Direct Mail Campaign.


Implementing Direct Mail Opt-Out

Direct mail e-mail should always, at a minimum, provide a way for the recipient to opt-out of future mailings. Depending on where you send direct mail from opt-out links will have different effects on your mailing lists.

For Direct Mail sent from the Business Desk

The unpacked site associated with the Business Desk module includes an ASP page that takes a query string consisting of the e-mail address of the recipient, the campaign item ID, and campaign name. When a user clicks on the opt-out link on the direct mail message sent from the business desk the user will be added to the opt-out list for the particular campaign that the direct mail was sent from. If the user is on mailing lists for multiple campaigns they will continue to receive direct mail from all campaigns except for the campaign that the direct mail was sent from.

In the direct mail e-mail you send, you would include a link to this ASP page. The code for a link might appear as follows:

Click

<A HREF="http://mswaldofr/retail/opt-out.asp?rcp_email=mailuser8@passport.com&campitem_id=2&campitem_name=TestMail&MSCSProf"> here </A> if you do not wish to receive future mailings.

The text the user would see in the e-mail would be "Click here if you do not wish to receive future mailings."

For Direct Mail sent from the Command Line

Direct mail sent from the command line is not associated with any campaign. Therefore the opt-out ASP page takes a query string containing only the e-mail address of the recipient. When a user clicks on the opt-out link on the direct mail message sent from the command line, the user will be added to the global opt-out list, and subsequently will be removed from all future mailings.

Note

  • If direct mail is sent using the Send Test Mail dialog box in Business Desk, and the recipient is on the opt-out list for the site, the recipient will still receive the mail. Opt-out links sent in direct mail messages from the Send Test Mail dialog box in Business Desk do not use the ListManager object to subtract the opt-out lists from the test mail mailing list. Additionally, if the user was not previously on the campaigns opt-out list and they click the opt-out link in the test mail, they will be added to the opt-out list.

For more information about the opt-out link included in the sample direct mail code, see Developing Direct Mail Content. If the direct mail is sent from the command line, and recipient clicks the opt-out link, the recipient will be added to global opt-out lists, and will no longer receive direct mail. If the direct mail is sent from the Business Desk module, and the recipient clicks the opt-out link they will be added to the opt-out list for the campaign. If the recipient was on multiple campaign mailing lists they will continue to receive direct mail from the other campaigns.


Values in the Direct Mailer Pipeline Dictionaries

The following table lists the keys used in the Commerce Server Direct Mailer pipeline dictionaries. Like other pipelines, the Direct Mailer pipeline uses two dictionaries: a Context (read-only) dictionary and an Order (read-write) dictionary.

Key | Dictionary | Description
Attachments | Order | A SimpleList of URLs pointing to attachments.
campaign_item | Context | The campaign item ID.
campaign_item_name | Context | The name of the campaign item.
cdo_config | Context | A reference to a Collaboration Data Objects (CDO) configuration object (CDO.Configuration).
cdo_error | Order | An error string from the most recent CDO operation, if any. NULL if no error.
cdo_message | Context | A reference to a CDO message object (CDO.Message).
cdo_result | Order | The result code (an HRESULT) from the most recent CDO for Microsoft Windows 2000 operation.
Cookie | Order | The dictionary containing the cookie data.
css_site | Context | The site ID string.
default_formatting | Context | The default format for the message.
default_locale | Order | The locale code to use if there is no recipient locale code (rcp_locale).
default_url | Context | The URL used to retrieve the mailing content.
default_url_content | Context | The content of the file pointed to by default_url if default_url_isfile is True.
default_url_isfile | Context | True if the default URL is a file path and not an http:// path.
delay_msec | Context | The delay between messages in milliseconds.
from_field | Order | The "From" field for the message.
messages_sent | Order | The total number of messages sent for this pipeline cycle.
precomposed_body | Order | The plain-text message body. Defaults to an empty string.
rcp_bypass | Order | Boolean. Component bypasses (skips) processing if True.
rcp_email | Order | The e-mail address of the recipient.
rcp_formatting | Order | The format of the message.
rcp_guid | Order | The GUID uniquely identifying this recipient, taken from the user profile.
rcp_locale | Order | The locale code to use for the recipient.
rcp_personalize | Order | Numeric. Whether or not to personalize the message for this recipient.
rcp_url | Order | The URL used to retrieve the mailing content. Takes precedence over default_url.
rcp_url_content | Order | The content of the file pointed to by rcp_url if rcp_url_isfile is True.
rcp_url_isfile | Order | True if the URL for the content (rcp_url) is a file and not an http:// address.
replyto_field | Order | The "Reply-to" field for the message.
subj_field | Order | The "Subject" field for the message.
use_precomposed_body | Order | Boolean. If True, the component creates the message from the plain-text body assigned to the precomposed_body key.
user_flags | Order | A bit mask indicating elements of the message to check. Only the rightmost bit is currently used.


Direct Mailer Component Reference

The following components are commonly run in the Direct Mailer pipeline:

  • AddAttachments

  • ComposeDMLMessage

  • CreateUPMCookie

  • SendPrecomposedMessage

  • ThrottleDMLPerformance

  • VerifyMessageBody

  • VerifyRecipientData


Content Selection Pipelines

The Content Selection pipelines are a significant part of the Content Selection Framework (CSF). They are used to select content or discounts, and to record events such as ad click-throughs.

This section contains:

  • About Content Selection Pipelines. Describes the role of Content Selection pipelines in the CSF, and introduces the two different forms of Content Selection pipelines.

  • Stages and Components in Content Selection Pipelines. Describes the individual stages in Content Selection pipelines and the components most often used in those stages.

  • Using Content Selection Pipelines. Explains how to use Content Selection pipeline components in Commerce Server sites.

  • Content Selection Component Reference. Lists the pipeline components used in Content Selection pipelines.


About Content Selection Pipelines

Content Selection pipelines are used with the CacheManager object and the ContentSelector object to select content items or other custom content, including discounts.

The advertising and discount delivery engines in Microsoft Commerce Server 2000 are built using Content Selection pipelines. You can create your own pipelines to do different types of content selection.

Two distinct pipelines exist for each content selection application. The first pipeline is responsible for selecting content to be displayed, and is known as the Content Selection pipeline (CSP). It is based on the ContentSelection.pct pipeline-template file. The second pipeline is responsible for processing events related to the displayed content, and is known as the Event Processing pipeline (EPP). An example of such an event is a user clicking on an ad or an ad being selected for display on a page. The pipeline is based on the EventProcessing.pct pipeline-template file.

Note

  • Although Content Selection pipelines are used to select discounts, the discounts are not applied in Content Selection pipelines. Discounts are applied to orders by the OrderDiscount pipeline component in an Order Processing pipeline.

The following table shows the CSP stages and the pipeline components provided for each of those stages, for each application.

CSP Stage | Advertising Application Pipeline Components | Discount Application Pipeline Components
Load Context | InitCSFPipeline LoadHistory | InitCSFPipeline LoadHistory
Filter | FilterContent | FilterContent
Initial Score | AdvertisingNeedOfDelivery | Not applicable
Score | HistoryPenalty EvalTargetGroups | ScoreDiscounts HistoryPenalty EvalTargetGroups
Select | SelectWinners | SelectWinners
Record | RecordHistory SaveHistory RecordEvent IISAppendToLog | RecordHistory SaveHistory RecordEvent IISAppendToLog
Format | FormatTemplate | FormatTemplate

The following table shows the EPP stages and the pipeline components provided for each of those stages, for each application.

EPP Stage | Advertising Application Pipeline Components | Discount Application Pipeline Components
Load Context | None | None
Record | RecordEvent IISAppendToLog | RecordEvent IISAppendToLog
Format | None | None


Stages and Components in Content Selection Pipelines

The following sections describe the stages and components in the Content Selection and Event Processing pipelines. The Content Selection pipeline selects custom content, such as ads or discounts, while the Event Processing pipeline processes events such as a user clicking on an ad.

  • Content Selection Pipeline. Describes the stages and components of the Content Selection pipeline.

  • Event Processing Pipeline. Describes the stages and components of the Event Processing pipeline.


Content Selection Pipeline

The Content Selection pipeline runs components that gather, filter, score, and select content. This pipeline is often used to select ads or discounts.

The Content Selection pipeline consists of the following stages:

  • Load Context Stage

  • Filter Stage

  • Initial Score Stage

  • Scoring Stage

  • Select Stage

  • Record Stage

  • Format Stage

Load Context Stage

This stage contains components that prepare for the execution of the rest of the pipeline.

The components related to this stage are shown in the following table.

Component | Description
InitCSFPipeline | Initializes values needed in the remainder of the pipeline.
LoadHistory | Retrieves a history string from a user profile, an item in the Active Server Pages (ASP) session collection, or a cookie.

Filter Stage

This stage contains components that filter or trim the content list.

The components related to this stage are shown in the following table.

Component | Description
FilterContent | Applies provided filters to the content list.

Initial Score Stage

This stage sets an initial score for each content item.

The components related to this stage are shown in the following table.

Component | Description
AdvertisingNeedOfDelivery | Scores ads so that they are selected often enough to meet business commitments.

Scoring Stage

This stage contains components that adjust the scores of each content item.

The components related to this stage are shown in the following table.

Component | Description
EvalTargetGroups | Targets particular groups for advertising, content, or discounts by evaluating a list of expressions for each item in a list and adjusting item selection.
HistoryPenalty | Applies penalties to content items based on how recently they have been selected.
ScoreDiscounts | Adjusts scores of discount items to promote discounts most relevant to the current user.

Select Stage

This stage, usually containing a single component, selects one or more content items for return.

The components related to this stage are shown in the following table.

Component | Description
SelectWinners | Selects items based on their final scores.

Record Stage

This stage contains components that record the selection made to a database, the server log file, or a history string.

The components related to this stage are shown in the following table.

Component | Description
IISAppendToLog | Records information about content selection results in the QueryString field of the Internet Information Services (IIS) log file.
RecordEvent | Records event delta counts for the selected content items (the winners) in the Performance dictionary. The values are used to calculate the need of delivery of an item.
RecordHistory | Records the identifiers of the winning content items in the history list string.
SaveHistory | Saves the history string in one of three locations: the user profile object, the ASP session collection, or the HTTP cookie.

Format Stage

This stage contains components that format selected items as HTML or XML for return to the page that ran the pipeline.

The components related to this stage are shown in the following table.

Component | Description
FormatTemplate | Merges data from selected items with their associated templates to form formatted strings. These are usually HTML strings ready for display on the page.


Event Processing Pipeline

The Event Processing pipeline runs components that record the occurrence of particular events, such as a user clicking on a particular ad.

The Event Processing pipeline consists of the following stages:

  • Load Context Stage

  • Record Stage

  • Format Stage

Load Context Stage

Microsoft Commerce Server 2000 includes no components for this stage. This stage is provided for custom extensions to CSF or for future enhancements to Commerce Server 2000.

Record Stage

This stage contains components that record the selection made to a database, the server log file, or a history string.

The components related to this stage are shown in the following table.

Component | Description
IISAppendToLog | Records information about content selection results in the QueryString field of the IIS log file.
RecordEvent | Records event delta counts for the selected content items (the winners) in the Performance dictionary. The values are used to calculate the need of delivery of an item.

Format Stage

Microsoft Commerce Server 2000 includes no components for this stage. This stage is provided for custom extensions to CSF or for future enhancements to Commerce Server 2000.


Using Content Selection Pipelines

Using Content Selection pipelines included in Microsoft Commerce Server 2000 requires setting up the CacheManager object and the information required by the ContentSelector object. However, custom Content Selection pipelines may or may not use the CacheManager object depending on the size of the content to cache. For code to set up the CacheManager and the ContentSelector objects, see Content Selection Objects

You can trace the actions of Content Selection pipelines by turning trace mode on for the pipeline. Trace mode uses the ContentSelector object to pass the value to the pipeline. In the following example, if CSO were a ContentSelector object, then the line of code would appear as follows:

oContentSelector.Trace=True

You should not turn trace mode on when running Content Selection pipelines in production Web sites.


Content Selection Component Reference

The following components are commonly run in Content Selection pipelines:

  • AdvertisingNeedOfDelivery

  • EvalTargetGroups

  • FilterContent

  • FormatTemplate

  • HistoryPenalty

  • IISAppendToLog

  • InitCSFPipeline

  • LoadHistory

  • RecordEvent

  • RecordHistory

  • SaveHistory

  • ScoreDiscounts

  • SelectWinners

In addition, the following writer and cache loaders play an important role in Content Selection pipelines:

  • CSFLoadAdvertisements

  • CSFLoadDiscounts

  • CSFWriteEvents


Pooled Pipelines

Pooled pipelines are a Commerce Server 2000 feature that significantly speeds up pipelines. Commerce Server 2000 pooled pipelines use COM+ object pooling to increase both loading and execution speed.

This section contains:

  • About Pooled Pipelines. Describes the PooledPipeline and PooledTxPipeline objects, how pooled and non-pooled components can be run in pooled pipelines, and debugging suggestions.

  • Managing Pooled Pipelines. Describes how to change properties of pooled pipeline components in order to maximize pipeline performance, and describes the Commerce Server tools you can use to monitor performance of your pooled pipelines.

  • Poolable Component Reference. Lists all components that are tagged as poolable.


About Pooled Pipelines

Commerce Server 2000 supplies two pooled pipeline objects, one for non-transacted pipelines (PooledPipeline) and one for transacted pipelines (PooledTxPipeline). Their use is identical to that of the non-pooled pipeline objects MtsPipeline and MtsTxPipeline. The difference between the two sets of pipelines is that the pooled pipeline objects are registered under COM+ to take advantage of object pooling.

Each of the pooled pipeline objects maintains a table of pipelines. When a pipeline is loaded, a pooled pipeline object first looks in its table of pipelines to see if the pipeline is already loaded. If the pipeline is not loaded already, the pooled pipeline object loads the pipeline and adds an entry to its protected table of pipelines. When the Execute method is called, the pipeline is retrieved from the table and run.

The individual components of a pooled pipeline — if they are poolable — are created once, and then held by the pipeline in the object pool. To be poolable, pipeline components must be free-threaded and cannot maintain state information between executions. Pipeline components written in Microsoft Visual Basic are apartment threaded; they cannot be pooled. Non-poolable components can still be run within pooled pipelines. However, these components are created each time there is an Execute method call. When you create custom poolable pipeline components, you must add the Component Object Model (COM) category, CATID_POOLABLE, to the component to make it poolable.

Although pooled pipelines are recommended in all new sites, older pipeline objects should be used during debugging. Because pipelines are effectively cached, changes to pipeline configurations may not take effect until either Microsoft Transaction Server (MTS) or Internet Information Services (IIS) is re-started. The objects MtsPipeline and MtsTxPipeline can be used for debugging a new pipeline and the objects PooledPipeline or PooledTxPipeline can be used in the production site.

Notes

  • Microsoft Application Center 2000 Component Load Balancing (CLB) can be used with Commerce Server pooled pipelines. Setup registers the Commerce Server pipeline as a COM+ package. In order to use it with CLB, you must go into the Component Services Microsoft Management Console (MMC) and change the Activation type of the package from "Library application" to "Server application." The pipeline object itself will be pooled by CLB, but pipeline components are not load balanced. This means that you cannot register any component that runs inside of a pooled pipeline as a COM+ application.

  • Setup also registers the Commerce Predictor Build Watcher component and the Commerce Event Logging components in COM+ packages. However, neither package should be used with CLB. These packages are created so that they can be used for administrative alert monitoring with distributed COM (DCOM), but there is no benefit to using them with CLB.


Managing Pooled Pipelines

You can change properties of COM+ object pools and monitor the performance of those pools using the Component Services administrative tool.

By monitoring pipeline performance and adjusting the parameters of the pooled objects, you can optimize pipeline pooling for your application.

Changing Pool Properties of Components

Monitoring Performance

Changing Pool Properties of Components

You can specify several properties that determine how COM+ handles the pool of pipeline objects. These properties include:

  • Minimum pool size

  • Maximum pool size

  • Creation request timeout

The minimum pool size is the minimum number of objects that are in the pool and the number of objects created when the application starts. When the pool reaches the maximum pool size, no more objects are created. This includes both active and inactive objects. The creation request timeout value is in milliseconds and specifies how long a client will wait for an object from the pool before the request times out (returns an E_TIMEOUT error).

To change pool properties

  1. Click Start, point to Programs, point to Administrative Tools, and then click Component Services.

  2. Expand Component Services, expand Computers, expand My Computer, expand COM+ Applications, expand CommercePipeline, and then expand Components.

  3. Right-click the pipeline you want to change, and then select Properties.

  4. In the Properties dialog box, on the Activation tab, and do the following:
    Use this | To do this
    Enable object pooling | Enable object pooling for the component.
    Minimum pool size | Type the minimum number of objects that will be maintained in the pool at any time.
    Maximum pool size | Type the maximum number of objects that can exist in the pool at any time.
    Creation timeout (ms) | Type the amount of time (in milliseconds) that the object pool has to provide a requested object.
    Enable object construction | Enable object construction for the component.
    Constructor string | Type a string that will be made available to the object at creation time when object construction is enabled.
    Enable Just in Time Activation | Specify that the object may be repeatedly deactivated and reactivated just in time to handle calls from a client, where the client is unaware that the object was ever deactivated.
    Component supports events and statistics | Enable object event reporting and object statistics, such as object call time.
    Must be activated in caller's context | Ensure that the object can only be activated within the context of its initial caller.

The new pool properties are saved.

Monitoring Performance

You can actively monitor pooled object performance in the Component Services administrative tool. The tool allows you to view the items listed in the following table for each pooled object.

Column | Description
Prog ID | The programmatic identifier of the object.
Objects | Number of objects currently held by clients.
Activated | Number of objects that are currently activated.
Pooled | Total number of objects created by the pool. Includes objects in use and deactivated objects.
In Call | Number of objects in the process of being called.
Call Time | The average call duration of method calls made in the last 20 seconds.

To monitor object status

  1. Click Start, point to Programs, point to Administrative Tools, and then click Component Services.

  2. Expand Component Services, expand Computers, expand My Computer, expand COM+ Applications, and expand CommercePipeline.

  3. Right click Components, select View, and then select Status View. The Status View appears on the right of the Component Services screen.


Poolable Component Reference

The following list contains the pipeline components that are tagged as poolable.

A-D

AddAttachment, AdvertisingNeedOfDelivery, ComposeDMLMessage

CreateAUOCookie, DefaultHandling, DefaultHandlingCy

DefaultItemPrice, DefaultItemPriceCy, DefaultOrderSubTotal

DefaultOrderSubTotalCy, DefaultPayment, DefaultShipping

DefaultShippingCy, DefaultShopperInfo, DefaultTax

DefaultTaxCy, DefaultTotal, DefaultTotalCy

E-Q

EvalTargetGroups, FilterContent, FixedHandling

FixedShipping, FlagInventory, FormatTemplate

HistoryPenalty, IISAppendToLog, InitCSFPipeline

LinearHandling, LinearShipping, LoadCSFHistory

LocalInventory, MoneyConverter, OrderDiscount

QueryCatalogInfo, QueryProdInfoADO

R

RecordCSFHistory, RecordEvent, ReduceLocalInventory

RequiredHandling, RequiredHandlingCy, RequiredItemAdjust

RequiredItemAdjustCy, RequiredItemAdjustPrice, RequiredItemAdjustPriceCy

RequiredItemPrice, RequiredItemPriceCy, RequiredOrderAdjust

RequiredOrderAdjustCy, RequiredOrderAdjustPrice, RequiredOrderAdjustPriceCy

RequiredOrderCheck, RequiredOrderInit, RequiredOrderInitCy

RequiredOrderSubTotal, RequiredOrderSubTotalCy, RequiredPayment

RequiredProdInfo, RequiredShipping, RequiredShippingCy

RequiredTax, RequiredTaxCy, RequiredTotal

RequiredTotalCy

S-Z

SQLItemADO, SaveCSFHistory, ScoreDiscounts

Scriptor, SelectWinners, SendPrecomposedMessage

TableHandlingADO, TableShippingADO, ThrottleDMLPerformance

ValidateCCNumber, VerifyMessageBody, VerifyRecipientData


Integrating with BizTalk Server

The Solution Sites for Microsoft Commerce Server 2000 are designed to integrate with Microsoft BizTalk Server in the following two ways:

  • Import/export of product catalogs

  • Multi-vendor order form processing

BizTalk Server integration is configured using Commerce Server Manager. These configuration settings are used to conditionally execute code within the Solution Sites that implements the integration with BizTalk Server. The remainder of this section provides some additional details regarding these areas of integration.

This section contains:

  • Product Catalog Integration. Describes how BizTalk Server can be used to import product catalogs from various vendors.

  • Order Form Integration. Describes how an order form can be divided into multiple purchase orders (POs) by vendor, and how BizTalk Server can be used to send those POs to their corresponding vendors.

See Also

Using BizTalk Server and Commerce Server


Product Catalog Integration

Product catalog integration is the process of offering products from different vendor catalogs for sale on a Web site. Another scenario that is conceptually similar concerns a company providing access of an office supply catalog on their internal Web site, allowing employees to order their own office supplies. This process needs to be considered from the perspective of the recipient of a vendor catalog as well as the perspective of the vendor providing the catalog.

This topic contains:

  • Importing Catalogs in the Commerce Server XML Format. Describes the process of importing product catalogs received from various vendors.

  • Generating Catalogs in the Commerce Server XML Format. Describes the process of exporting a product catalog for those vendors using Microsoft Commerce Server 2000.

Importing Catalogs in the Commerce Server XML Format

The process of importing a catalog is normally performed in the Catalog Editor module of Commerce Server Business Desk. For more information about importing a catalog in the proper XML format, see Importing an XML Catalog File. However, a catalog in the proper Extensible Markup Language (XML) format can be imported into the Commerce Server catalogs database programmatically using the ImportXML method of the CatalogManager object. For more information about this method, see CatalogManager.ImportXML.

To validate that your catalog XML file conforms to the proper schema:

  1. Edit the second line in your catalog XML file so that it references the catalog XML Data Reduced (XDR) file provided in the Commerce Server root installation folder. For example:

    <MSCommerceCatalogCollection xmlns="x-schema:C:\Program Files\Microsoft Commerce Server\CatalogXMLSchema.xml">

  2. Open your catalog XML file in Internet Explorer (IE). IE will validate that the XML file conforms to the specified schema and show diagnostic errors in the event that it does not conform.

Note

  • These steps only confirm that the catalog XML file conforms to the XDR schema. It does not validate whether the catalog schema such as product, category, and property definitions, are compatible with any pre-existing catalog schema, or whether products and categories in the catalog XML file are consistent with the catalog schema defined in that XML file. This validation occurs when the file is imported, and any problems found are written to the event log.

If Microsoft BizTalk Server is installed on the same computer as Commerce Server, you can use an Application Integration Component (AIC), as defined by BizTalk Server, to automate the process of importing XML catalogs into Commerce Server as they arrive from vendors via BizTalk Server. For more information about creating an AIC, see the BizTalk Server documentation.

Generating Catalogs in the Commerce Server XML Format

A product catalog must exist in the XML format expected by Commerce Server in order to be successfully imported. If the vendor supplying the catalog is also using Commerce Server as the source of the catalog, as well as using BizTalk Server to deliver the catalog, the process is quite simple. A business manager can select a catalog and send it to a trading partner. For more information about sending a catalog to a trading partner, see Sending a Catalog to a Trading Partner.

If you are a vendor who does not use Commerce Server as the source of your catalog, you can still use BizTalk Server to deliver your product catalog to Commerce Server. You might even be able to take advantage of the Mapper feature in BizTalk Server, using the Looping functoid, to convert your product catalog from its native format to the XML format expected by Commerce Server. For more information about using the Mapper feature and the Looping functoid to convert the catalog to the proper XML format, look for "Commerce Server catalogs" in the BizTalk Server documentation.

If vendors are not using BizTalk Server, they will need to devise a proprietary solution to convert their catalog format to the XML format expected by Commerce Server. For more information about this format, see Catalog XML Structures.


Order Form Integration

Order form integration is the process of splitting an order form into multiple purchase orders and sending them to the relevant vendors using Microsoft BizTalk Server. The following aspects of this process need to be considered:

  • Associating a Vendor ID with each Catalog

  • Configuring Commerce Server for Order Form Integration

  • Overview of Processing

Associating a Vendor with each Catalog

By associating a vendor ID with each product catalog, the vendor for any given product in an order can be determined by identifying the product catalog associated with the product, and then identifying the vendor associated with that catalog. Being able to determine the vendor associated with each product allows Commerce Server to construct purchase orders on a vendor-by-vendor basis, and deliver those purchase orders to the corresponding vendors using BizTalk Server.

The process of associating vendors with catalogs is typically done manually, using Commerce Server Business Desk. For more information about assigning a vendor to each catalog, see Setting Up Your Catalogs for BizTalk Server.

Commerce Server also provides a Component Object Model (COM) object designed to allow programmatic assignment of vendors to catalogs. This object also provides methods to, for example, retrieve a list of available vendors, and return vendor information given a particular catalog. For more information about this object, see CatalogToVendorAssociation Object.

Configuring Commerce Server for Order Form Integration

The Commerce Server Solution Sites include conditional code for submitting per-vendor purchase orders to BizTalk Server, allowing these purchase orders to be sent to the relevant vendors. This functionality is built into the Solution Sites, and is configured using the Commerce Server Manager. For more information about how to configure a Commerce Server Solution Site to create purchase orders for each vendor associated with a product in an order form, see Configuring Commerce Server to Work with BizTalk Server.

Overview of Processing

The following Microsoft Visual Basic code shows the processing that occurs in three functions involved in order form integration with BizTalk Server. Note the annotations in bold italics, and the fact that the first routine calls the second two routines in its innermost loop.

' Always call this routine when processing orders. It will
' return immediately if BizTalk PO integration is not enabled...
Sub InvokeBizTalk(ByVal mscsOrderGrp)
    Dim sOrderName, mscsOrderForm, oVendor, sXML
    Dim sVendorQualID, sVendorQualValue

    ' Do not do anything unless BizTalk PO integration is enabled...
    If dictConfig.i_BizTalkOptions = BIZTALK_PO_XFER_ENABLED Then

        ' Process each order form in the order group...
        For Each sOrderName In mscsOrderGrp.Value.OrderForms
            Set mscsOrderForm = _
                mscsOrderGrp.Value(ORDERFORMS).Value(sOrderName)

            ' Process each vendor known to the order form...
            For Each oVendor In mscsOrderForm.value("_vendors")

                ' Skip the default vendor, which
                ' is the local organization...
                If StrComp(oVendor.vendorID, DEFAULT_ORDERFORM, _
                                             vbTextCompare) <> 0 Then

                    ' Call second function defined here to
                    ' retrieve an XML string containing only
                    ' items associated with the current vendor...
                    sXML = GetXMLForVendorItems(mscsOrderForm, oVendor)

                    ' Get the vendor delivery information from
                    ' the orderform item...
                    sVendorQualID = _
                           mscsOrderForm.items( _
                                oVendor.itemindexes(0)).vendor_qual)
                    sVendorQualValue = _
                           mscsOrderForm.items( _
                                oVendor.itemindexes(0)).vendor_qual_value

                    ' Call third function defined here to submit
                    ' the single vendor PO to BizTalk Server...
                    Call SubmitUsingBizTalk(sXML, oVendor.vendorID, _
                                                     sVendorQualID, _
                                                  sVendorQualValue)
                End If
            Next
        Next
    End If
End Sub

' Returns an XML string containing the PO for the specified vendor...
Function GetXMLForVendorItems(ByVal mscsOrderForm, ByVal oVendor)
    Dim oXMLTransforms, oXMLSchema, oOrderFormXML, oXMLDoc
    Dim oNode, oAttribute
    Dim sFilePath

    ' Create a DictionaryXMLTransforms object...
    Set oXMLTransforms = _
        Server.CreateObject("Commerce.DictionaryXMLTransforms")

    ' Create a PO schema object...
    sFilePath = Server.MapPath("\" & MSCSAppFrameWork.VirtualDirectory) _
                & "\poschema.xml"
    Set oXMLSchema = oXMLTransforms.GetXMLFromFile(sFilePath)

    ' Create an XML version of the order form...
    Set oOrderFormXML = _
      oXMLTransforms.GenerateXMLForDictionaryUsingSchema(mscsOrderForm, _
                                                         oXMLSchema)

    ' Create a copy of the XML version of the order form...
    Set oXMLDoc = Server.CreateObject("MSXML.DOMDOCUMENT")
    oXMLDoc.loadXML oOrderFormXML.xml

    ' For each 'Item' node in the XML order form copy...
    For Each oNode In oXMLDoc.documentElement.childNodes
        If (oNode.nodeName = "Items") Then

            ' If this vendor ID of the 'Item' node is not the
            ' same as the passed vendor ID, discard the node...
            For Each oAttribute In oNode.Attributes
                If (oAttribute.nodeName = "vendorid") Then
                    If Not(oAttribute.nodeValue = oVendor.vendorID) Then
                        oNode.parentNode.removeChild oNode
                    End If
                    Exit For
                Else
                End If
            Next

        End If
    Next

    ' Return an XML string containing the remaining 'Item' nodes,
    ' all of which correspond to the passed vendor...
    GetXMLForVendorItems = oXMLDoc.xml
End Function

' Submit the vendor-specific PO to BizTalk Server...
Function SubmitUsingBizTalk(ByVal sXML, ByVal sVendorName, _
                            ByVal sDestQualID, ByVal sDestQualValue)
    Dim sSubmitType, sDocName
    Dim sSourceQualID, sSourceQualValue
    Dim oDBConfig, oOrg, sID, sName, sDef, oRes
    Dim oInterchange

    ' Retrieve the source BizTalk config values locally...
    sSubmitType = dictConfig.s_BizTalkSubmittypeQueue
    sDocName = dictConfig.s_BizTalkOrderDocType
    sSourceQualID = dictConfig.s_BizTalkSourceQualifierID
    sSourceQualValue = dictConfig.s_BizTalkSourceQualifierValue

    ' Create a BizTalk Interchange object and call its Submit
    ' routine using the passed and gathered parameters...
    Set oInterchange = Server.CreateObject("BizTalk.Interchange")
    oRes = oInterchange.Submit(sSubmitType, _
                               sXML, _
                               sDocName, _
                               sSourceQualID, _
                               sSourceQualValue, _
                               sDestQualID, _
                               sDestQualValue)
End Function


Customizing Style Sheets

Cascading style sheets, found in files with .css extensions, allow the appearance of whole classes of visual HTML elements to be controlled from one central location. This includes, for example, the background colors and fonts used for various classes of elements.

The Commerce Server Business Desk makes extensive use of two such style sheet files: Bizdesk.css and Navtree.css. The former is used to control the look of the content pane, and the latter is used to control the look of the navigation pane. The appearance of the Business Desk can be changed is by making modifications to these style sheets. For more information about the styles defined in these style sheet files, see Style Sheet Reference.

Important

  • Extreme care should be exercised when changing styles since undesired effects may be caused in other areas of the Business Desk.


Modifying Your Site for an International Audience

Microsoft Commerce Server 2000 provides functionality to ease the process of internationalizing your Web site. Commerce Server includes features for tracking the language chosen by the user, for maintaining Web site text in multiple languages, and for manipulating date, time, and currency strings for presentation in the language of choice.

This section contains:

  • Tracking Language Choice. Describes different mechanisms for tracking the language chosen by the user.

  • Localizing Web Site Text. Describes how to present Web site text in the language chosen by the user.

  • Localizing Dates and Times. Describes the Commerce Server objects provided for manipulating date and time strings and values so that they conform to the language chosen by the user.

  • Localizing Currencies. Describes the Commerce Server objects provided for manipulating currency strings and values so that they conform to the language chosen by the user. It also describes strategies for presenting product prices in different currencies.


Tracking Language Choice

If you are developing a Web site that will support multiple languages, you need a strategy for tracking the language choice made by the user. You can do this by:

  • Creating distinct Web sites for each language. If your site contains mostly static HTML pages, consider using pre-generated pages. Using this approach, you develop and maintain multiple parallel Web sites, one for each language that is supported. Typically, the links on these pages link to other pages in the same language, while the links that move the user to a different language link to the equivalent page in each supported language. In this approach, the language choice is inherent in the URLs.

    You can minimize the maintenance burden of this approach by pre-generating pages from a reference Web site. The reference Web site should have all language-specific strings expressed as replaceable variables. You could then develop a tool to substitute the appropriate language-specific strings for each of these variables for each language that is supported.

  • Storing the language choice in client-side cookies. Storing the language choice in a client-side cookie is the easiest way to track a language choice, but cookies must be enabled on client browsers. In this approach, you store a language code (for example, "en", "fr", or "nl") in the cookie and read the cookie on every page that displays language-dependent strings. The language code can then be used to make the appropriate selections for text, currency, and date/time formatting.

    Depending on the expiration date of the cookies, this option may allow language choice to be preserved from session to session.

  • Passing the language choice in URL query strings. You can store the language choice in the query string portion of the URL for each page to track a language choice. If you use this approach, each page must read the language choice from the query string and use it to dynamically append the language choice to all URLs on the page so that that choice can be passed to subsequent pages. The language choice must also be used to make the appropriate selections for text, currency, and date/time formatting.

  • Storing the language choice in the user profile. Another option for tracking a language choice is to persist the choice made by each user in the user profile. This approach requires you to add a language property to the user profile, which you initialize when the user first chooses a language, or changes languages. Each page retrieves the user profile and then uses the value stored in the language property to make the appropriate selections for text, currency, and date/time formatting. This is a cost-effective method of storing language preferences, because the only performance cost involved is retrieving and updating the profile.


Localizing Web Site Text

On Web sites that support multiple languages, rendered pages must be capable of displaying text in the language chosen by the user. You must first decide whether you will build and maintain parallel Web sites in different languages, or whether you will build a single Web site that dynamically builds each page in the appropriate language.

Though the parallel Web site approach offers better performance due to its more static nature, the maintenance burden of keeping multiple Web sites synchronized has made this approach unpopular.

Commerce Server includes features to make the dynamic approach easier to develop. These features include:

  • Product Catalog System. The extensible nature of the Product Catalog system provides a convenient mechanism for storing multiple language information for each product in the catalog. For example, rather than having a single product description property that stores the description of a product in a single, default language, the schema can be extended to contain multiple description properties, one for each language that is supported.

    For example, instead of having a short_description property, you could define three description properties, as follows: short_description_en for the English version, short_description_fr for the French version, and short_description_nl for the Dutch version. Then, based on the language choice of the user, your Active Server Page (ASP) code can dynamically request the appropriate description value to display.

    For more information about changing the product catalog schema, see Changing Catalog Schema.

  • MessageManager Object. This object serves as a repository for text strings used on a Web site. It includes a mechanism for separating the symbolic name of the string from the particular language translation of the string. For example, you could output the string "Weekly Specials" in English using the GetMessage method of the MessageManager object, as shown below:
    Dim sLangChoice
sLangChoice = "en"
<%= oMessageManager.GetMessage("Weekly_Specials", sLangChoice)%>

    By changing the way in which the sLangChoice parameter is initialized, the same line of code could be used to display the version of the string in a different language.

    An instance of the MessageManager object is typically created and loaded with messages in the file Global.asa. A reference to this object is then placed in the intrinsic Application object so that all pages in the Web site have easy access to the stored messages. If multiple languages are being used, the initialization code in Global.asa file will load the MessageManager object with multiple sets of messages, where each set corresponds to one of the languages being supported.

    If you provide a set of localized messages for a particular language, it is important that you provide a translated version of all corresponding text. If you attempt to call the GetMessage method of the MessageManager object and pass a string name and language for which no string exists, a run-time error occurs.

    For more information about using the MessageManager object, see MessageManager Object and Display Objects.

  • CacheManager Object. This object can serve as a high-performance repository for strings or other data that are used frequently. Since retrieval from a CacheManager object is dependent upon a single key string, and not a combination of a key string and a language string as is the case for the MessageManager object, the choice of language must be embedded within the key string itself. The recommended technique is similar to that used for supporting multiple languages in the Product Catalog System.

    For example, multiple language versions of the same string in English, French, and Dutch could be stored in a CacheManager object, with the key strings for each ending in "_en", "_fr", and "_nl", respectively. The key string would be built dynamically, altering the final component of the string based on the language choice of the user.

    For more information about using the CacheManager object, see CacheManager Object and General Purpose Objects.


Localizing Dates and Times

On Web sites that support multiple languages, rendered pages must display dates and times in the format appropriate for the language chosen by the user.

Commerce Server provides several Component Object Model (COM) objects for processing date and time values in different languages. These features include:

  • AppFrameWork Object. This object includes several methods for retrieving locale-sensitive date and time values from HTTP requests. These methods are:

    AppFrameWork.RequestDate

    AppFrameWork.RequestDateTime

    AppFrameWork.RequestTime

  • DataFunctions Object. This object includes several methods for converting locale-sensitive date and time strings to their equivalent Variant values, and back again. These methods are:

    DataFunctions.ConvertDateString

    DataFunctions.Date

    DataFunctions.ConvertDateTimeString

    DataFunctions.DateTime

    DataFunctions.ConvertTimeString

    DataFunctions.Time

For more information about these objects, see Display Objects.


Localizing Currencies

On Web sites that support multiple languages, rendered pages must display currency values in the format appropriate for the language chosen by the user. Further, the price of any given product needs to be displayable in multiple currencies.

This topic contains:

  • Objects for Manipulating Currencies

  • Presenting Product Prices in Multiple Currencies

  • Other Currency Issues

Objects for Manipulating Currencies

Commerce Server provides several Component Object Model (COM) objects for processing currency values in different languages. These features include:

  • AppFrameWork Object. This object includes a method for retrieving locale-sensitive currency values from HTTP requests. This method is:

    AppFrameWork.RequestMoneyAsNumber

  • DataFunctions Object. This object includes several methods for converting and formatting currency values. These methods are:

    DataFunctions.ConvertMoneyStringToNumber

    DataFunctions.ConvertStringToCurrency

    DataFunctions.CurrencySymbol

    DataFunctions.LocalizeCurrency

    DataFunctions.Money

  • EuroDisplay Object. This object includes several methods for converting locale-sensitive currency strings to their equivalent numeric values, and back again. These methods are:

    EuroDisplay.ConvertAltStringToCurr

    EuroDisplay.ConvertBaseStringToCurr

    EuroDisplay.ConvertMoney

    EuroDisplay.FormatAltMoney

    EuroDisplay.FormatBaseMoney

    EuroDisplay.Initialize

For more information about these objects, see Display Objects.

Presenting Product Prices in Multiple Currencies

An issue related to the display of currencies in Web sites that support multiple languages is the presentation of product prices in different currencies.

As with product text, one alternative is to extend the product catalog schema to allow for the storage of product prices in different properties, one per language. The advantage of this approach is that product prices can be presented in conventional, well-rounded amounts such as $4.95 or £9.99. If you adopt this approach, however, you will be offering your products at slightly different prices based on the language chosen by the user, and you will have the burden of maintaining multiple prices per product.

A different strategy involves storing product-pricing information in only one currency, known as the reference currency. For example, you can store your prices in U.S. dollars or European euros, and then recalculate prices in other currencies dynamically, as needed. To calculate prices based on the reference currency, you need to create an exchange rate table that specifies the rates for other currencies in comparison to the reference currency. The exchange rate table should contain the following fields:

  • Currency symbol

  • International Standards Organization (ISO) currency code

  • Exchange rate

  • Display format

An example of an exchange rate table is shown below.

Currency symbol | ISO currency code | Exchange rate | Display format
$ | USD (U.S. dollar) | 1.0 | ####.##
£ | UKP (U.K. pound sterling) | 1.2 | ####.##
F | BEF (Belgian franc) | 0.023 | ######,00
€ | EUR (European euro) | 0.9 | ####.##

When your site displays a price, it calculates the price based on the exchange rate and displays it with the associated currency symbol and display format.

Important

  • If you store search results and product detail pages in the CacheManager object, you must make the currency part of the cache key or you will retrieve the wrong results when you try to display pricing in a different currency.

Other Currency Issues

You may need to change the currency mode settings within the pipeline configurations to accommodate your choice of locale.


Migrating the Membership Directory

The Directory Migration Toolbox is a collection of components that you use to migrate a Site Server 3.0 Membership Directory to a Commerce Server 2000 user profile store.

This section describes the architecture of the components and how to migrate the Membership Directory, and is intended for use by the system administrators and site developers responsible for migrating a site based on Site Server 3.0 to Commerce Server 2000. Before you use the Directory Migration Toolbox, you should be familiar with the documentation for both products.

This section contains:

  • About the Directory Migration Toolbox. Describes the components in the Directory Migration Toolbox.

  • Planning for Migration. Describes issues you must consider before beginning your migration.

  • Preparing for Migration. Explains how to pre-populate Active Directory groups in the Profiles data store, and how to map attributes in the Membership Directory to attributes in the Profiles data store.

  • Starting the Migration Process. Explains how to start the migration process.

  • Troubleshooting with the Migration Log File. Explains how to investigate problems using the migration log file.

  • Verifying Successful Migration. Explains how to verify that the migration process is working correctly.

  • Programmer's Reference for Migration. Provides reference pages for the migration Component Object Model (COM) objects supplied with Commerce Server, and for each of the associated properties and methods.


About the Directory Migration Toolbox

The Directory Migration Toolbox contains the following components that you use to migrate users from the Site Server 3.0 Membership Directory to the Commerce Server Profiles data store:

  • Source Code for Migration Components. Provides the source code for the migration components so you can modify them as needed, and provides an example of C++ source code used to migrate a single user profile.

  • Groups Pre-Population Tool. Pre-populates Active Directory groups in the Profiles data store, if you need to use groups.

  • Migration ProfileBuilder Tool. Maps attributes in the Membership Directory to attributes in the Profiles data store.

  • Directory Migration Tool. Migrates profiles from the Membership Directory in batch mode or on-demand mode.

  • Subgroup Manager. Modifies code that determines where a user is stored in Active Directory. The Subgroup Manager helps you determine group membership.


Source Code for Migration Components

The Directory Migration Toolbox includes compiled versions of the components you can use to immediately migrate your Site Server 3.0 Membership Directory to the Commerce Server Profiles data store. In addition, the Toolbox includes the source code for all of the components so you can modify them to meet your needs.

The source code for these components is located in the following folder:

<Drive>:\Program Files\Microsoft Commerce Server\SDK\Tools\MembershipMigration

The following table lists the subfolders in the MembershipMigration folder, and describes the components in each subfolder.

Subfolder | Description
\bin\release | Pre-compiled binaries of the Directory Migration objects and the migration test client.
\Client | C++ source code for a simple client to migrate a single user profile.
\GroupMigration | Microsoft Visual Basic source code for the tool used to pre-populate Active Directory groups before migrating user profiles.
\include | Include header files used when you build the objects.
\MigrationLogObj | C++ source code for the MigrationLogObj object of the Directory Migration Tool.
\MigrationMainObj | C++ source code for the MigrationMainObj object.
\MigrationModifyObj | C++ source code for the MigrationModifyObj object.
\MigrationReadObj | C++ source code for the MigrationReadObj object.
\MigUtil | C++ source code for the Migration Utility Library of the Directory Migration Tool.
\MigrationWriteObj | C++ source code for the MigrationWriteObj object
\ProfileBuilder | Visual Basic source code for the Migration ProfileBuilder tool, used to build the Extensible Markup Language (XML) configuration file used by the Directory Migration tool objects.
\SubGroupManager | Visual Basic source code for a helper object, used to determine the group in which a user belongs.

The Readme.htm file in the MembershipMigration folder contains important information about the Directory Migration Toolbox for this release of Commerce Server.

See Also

Programmer's Reference for Migration


Groups Pre-Population Tool

Use the Groups Pre-Population tool to pre-populate Active Directory groups, if you use groups in your installation. You can create groups in the Active Directory domain or forest as appropriate. Because you must create groups before you add users to them, run the Groups Pre-Population Tool before migrating users.

By pre-populating Active Directory groups, you can set access control lists (ACLs) on the file system before enabling your Commerce Server site.

See Also

Run the Groups Pre-Population Tool


Migration ProfileBuilder Tool

Use the Migration ProfileBuilder tool to map attributes from the Site Server 3.0 Membership Directory to the Commerce Server Profile data store.

When you run the Directory Migration tool, it reads an Extensible Markup Language (XML) file that maps the user attributes from the Membership Directory to the Profiles data store(s).

The Migration ProfileBuilder tool performs the following tasks:

  • Reads user attributes from the Membership Directory schema

  • Reads user attributes from the User Profile Object schema

  • Creates the XML configuration file read by the Directory Migration Tool

Note

  • To use this tool, you must have administrative privileges to view all domains in the Active Directory forest.

See Also

Run the Migration ProfileBuilder Tool


Directory Migration Tool

You can run the Directory Migration tool in either of the following modes:

  • Batch Mode. Migrates a range of sequential users.

  • On-Demand Mode. Migrates one user at a time, on an as-needed basis.

You can run multiple instances of the Directory Migration tool simultaneously. When both modes are used to migrate a directory, the batch mode migrates all users together. For users who access the site before their accounts are migrated, on-demand migration can be triggered so the user can proceed on the new site with minimal interruption. The migration objects are installed on one or more servers and will migrate a user upon request. In batch mode, a sequential range of users is migrated. In on-demand mode, one user at a time is migrated as they log in to the Commerce Server 2000 site. The file Login.asp in the <Drive:>\Program Files\Microsoft Commerce Server\SDK\Tools\MembershipMigration\Client directory can be used to migrate users on demand.

To track the status of each user migration, the Migration attribute is added to the Membership Directory user schema. The Migration attribute type is binary.

For each attribute that is migrated, the Directory Migration tool assigns True to the Migration attribute if the migration was successful, and False if the migration was not successful. If the migration was unsuccessful, check the log for the reason.

Note

  • The Directory Migration tool interprets the lack of a migrated attribute as "no migration attempted."

MigrationMainObj Object

The MigrationMainObj object is the primary object that manages the migration of individual users or ranges of users upon demand. It calls the objects in the following order for each user to be migrated:

  1. MigrationReadObj object

  2. MigrationModifyObj object

  3. MigrationWriteObj object

  4. MigrationLogObj object

If the MigrationMainObj object is configured to run in batch mode, it uses a filter to generate Lightweight Directory Access Protocol (LDAP) queries for user profiles matching the filter criteria (for example, user names starting with "Aaa" through "Adz"). This filter is used to help prevent LDAP time-outs. For more information about this filter, see Migration ProfileBuilder Tool.

The following figure shows how the Directory Migration tool processes a user profile.

ASP
<XML>
Figure showing how the Directory Migration tool processes a user profile
Migration Configuration
ProfileServices
Object
MigrationLogObj
MigrationWriteObj
MigrationModifyObj
MigrationReadObj
Commerce Server 2000
LDAP
Server
SQL Server 2000
Windows 2000 Active Directory
Membership Directory Store
MigrationMainObj

The Directory Migration tool performs the following steps to process a user profile:

  1. It retrieves information from an Extensible Markup Language (XML) configuration file that contains details on the objects to be used, and instructions for mapping the data to be read to the data to be written.

  2. The MigrationMainObj object receives a request to migrate a user profile.

  3. The MigrationMainObj object sends the request to the MigrationReadObj object.

  4. If the Migration attribute is not set to True or False, the MigrationReadObj object sets the Migration attribute to True, which prevents other instances of the Directory Migration tool from migrating the same user profile again. If the update succeeds, the migration process continues to the next step; otherwise it fails.

  5. The MigrationReadObj object retrieves the user profile from the Membership Directory.

  6. If indicated in the XML configuration file, the MigrationReadObj object calls the MigrationModifyObj object.

  7. The MigrationModifyObj object changes the user profile as specified, and then returns the modified buffer to the MigrationReadObj object.

  8. The MigrationReadObj object sends a pointer to the buffer to the MigrationMainObj object. If the MigrationReadObj object returns a failure, the MigrationMainObj object logs the failure, calls the MigrationReadObj object to set the Migration attribute to "Failed," and then prepares to process the next migration request.

  9. The MigrationMainObj object sends the buffer to the MigrationWriteObj object, which writes the user profile to the Profiles data store.

  10. The MigrationWriteObj object sends the write request to the ProfileService object. If it succeeds, the MigrationWriteObj object then adds the user profile to the appropriate groups, and updates the MemberOf attribute accordingly. If the write fails, the write is rolled back. If the rollback fails, the MigrationWriteObj object logs the rollback failure.

  11. The ProfileService object returns a success/fail return code on the write attempt.

  12. If the migration is an Active Directory migration, the MigrationWriteObj object adds the user to the proper groups through direct Active Directory Service Interfaces (ADSI) calls.

  13. The MigrationWriteObj object logs the success (or failure) of the write attempt and adds users to the appropriate groups when completed. The MigrationWriteObj object returns the success/fail code as appropriate.

  14. The MigrationMainObj object logs a successful or failed migration attempt and returns the success/fail return code to the calling component.

MigrationReadObj Object

The MigrationReadObj object reads the user profile attributes from the Site Server 3.0 Membership Directory. The MigrationMainObj object calls the MigrationReadObj object when each user profile is to be migrated.

The source code for the MigrationReadObj object is provided in the SDK\Tools\MembershipMigration folder.

MigrationModifyObj Object

You use the MigrationModifyObj object to modify user profile data as it is migrated. The MigrationModifyObj object is responsible for buffer management. Refer to the source code for examples of buffer management.

The source code for a MigrationModifyObj object is provided in the SDK\Tools\MembershipMigration folder.

MigrationWriteObj Object

The MigrationWriteObj object writes the migrated user profile data to the ProfileService object. In addition, if the user is a member of a group, the MigrationWriteObj object adds it to the equivalent group in Active Directory.

MigrationLogObj Object

The MigrationLogObj object is used to create a transaction log, which you use to diagnose problems encountered during the migration process.

See Also

Programmer's Reference for Migration


Subgroup Manager

The SubGroupManager object is a helper object that is used in code that determines where a user in Active Directory is stored, as an aid to determining group membership.

It is a Visual Basic ActiveX dynamic-link library (DLL) and an associated test .exe file that takes as input the distinguished names of a user and the parent group.

Because of the effective limit of 5000 objects per group, most groups will require a series of sub-groups to fully contain the users of a large group. For example; in Membership Directory, a group named "friends" might exist with 10,000 users in the group. In Active Directory, you would create the master group "friends" and then create subgroups under this master group, which actually holds all of the users. You can identify one of these subgroups by the fact that it contains the name of the master group with a numeric suffix. For example, "friends_0001".

The following table shows the methods supported by the SubGroupManager object, and provides a description of each.

Method Description
SubGroupMembership
  • Returns as a string the Distinguished Name (DN) of the subgroup in which the user profile will be place.

  • No operations are performed against Active Directory.
AddUserToMasterGroup
  • Determines which subgroup of the master group this user profile should be in.

  • Verifies whether the subgroup exists. If it does not exist, it creates the subgroup automatically.

  • Writes the user profile to the subgroup.
RemoveUserFromMasterGroup
  • Determines which subgroup of the master group this user profile should be in.

  • Removes the user profile from the subgroup.
IsUserOfMasterGroup
  • Determines which subgroup of the master group this user profile should be in.

  • Tests the subgroup for whether the user profile is a member; returns True if it is, False if it is not.

The SubGroupManager object is functionally complete, but it does have a hard-coded user name and password in it for connecting to the directory service. You will need to alter these constants, recompile, and then register the resulting DLL with the following command:

regsvr32 subgroupmanager.dll

The ProgID for creating the SubGroupManager object is: SubgroupManagerProject.SubGroupManager.

Note

  • If you change the hashing algorithm, you must make the same changes to the source code corresponding to the migrationutil.dll file.


Planning for Migration

Before you begin the migration process, it is important that you plan for and understand the steps involved with this process.

This section contains:

  • Migrating Authentication Types

  • Migrating Groups

  • Migrating to Active Directory or SQL Server


Migrating Authentication Types

The tools in the Directory Migration Toolbox migrate data so that all authentication types in the Membership Directory are supported.


Migrating Groups

Although the Commerce Server Profiling System supports groups, the implementation is dependent upon the capability of the Profiles data store. You must use Active Directory to implement groups the same way they were implemented in Site Server 3.0 Membership Directory.

You can use Active Directory to create groups and assign access control lists (ACL) and Access Control Entries (ACE) on files and directories. However, the implementation is not completely compatible with a site as it would be implemented using the Site Server 3.0 Membership Directory. Active Directory limits a group to 5000 objects. This limit is necessary because of the manner in which the contents of the group are replicated between instances of the domain controllers. Although this limitation will be addressed in future versions of Active Directory, it is necessary to perform a work-around to migrate your Membership Directory.

You can use the Directory Migration tools to create subgroups, and then add user profiles to the subgroups. To preserve space for additional growth and subgroups, the tools fill 4500 user profiles per subgroup.

The following table shows how a group with 100,000 user profiles in the Membership Directory would be migrated to Active Directory.

Membership Directory Structure | Equivalent Active Directory Structure
GroupA | GroupA
User1 .. User100000 | GroupA_0000
 | User1 .. User4500
 | GroupA_0001
 | User4501 .. User9000
 | …
 | GroupA_0023
 | User99001.. User100000

Caution

  • You must set up Active Directory in Native mode. Do not set up Active Directory in Mixed mode; if you do, Active Directory will not create the required group hierarchy.

If you use a forest of domains to contain the user profiles, the migration becomes more complex. The following figure shows how to map user profiles and ACLs on content to Active Directory and still enforce site security.

A figure showing how to migrate to a forest of domains
Windows 2000 Active Directory Forest
Post-Migration
Windows 2000
Active Directory
ResourceDomain
Windows NT
4.0 Domain
Domain3
Domain2
File ACL/ACE: DomainLocalGroup3
File ACL/ACE: DomainLocalGroup2
File ACL/ACE: DomainLocalGroup1
File ACL/ACE: Group3
File ACL/ACE: Group2
File ACL/ACE: Group1
Group3

Group3
User1
User2
User3
Group11
User65
User66
User67

Group2
Group2
GlobalGroup1
GlobalGroup1
GlobalGroup2
GlobalGroup2
GlobalGroup3
Group1
Group1_0000
User1
Group11 Group11_0000
User66
GlobalGroup3
Group1
Group1_0000
User1
Group11 Group11_0000
User67
GlobalGroup3
Group1
Group1_0000
User1
Group11 Group11_0000
User65
GlobalGroup2
GlobalGroup1
DomainLocalGroup3
DomainLocalGroup2
DomainLocalGroup1
Group1
Group1
Domain1
Membership
Directory
Pre-Migration


Migrating to Active Directory or SQL Server

You must decide whether you are migrating users to Active Directory or Microsoft SQL Server. The following factors should be considered:

  • Migration Performance and Scalability

  • Migration Attribute Compatibility

Migration Performance and Scalability

Active Directory

The Windows 2000 Server Active Directory is a robust, highly secure directory store. When planning for performance and scalability, note the following:

  • Active Directory is necessary to support deployment requiring access control of files that map to groups of users.

  • Active Directory is tuned as a domain controller with write transactions representing only a fraction of the total directory input/output.

  • Current testing indicates that at about one million (1,000,000) users in a domain the replication input/output between Active Directory instances in the domain begins to impact read/write activity for the profile. In addition, there is a practical limit of approximately five domains with one million users in each domain before the global catalog replication overhead begins to impact profile request input/output. These numbers are subject to hardware performance and tuning optimization.

The following recommendations are based on testing conducted using a typical e-commerce user profile:

  • One million users per Active Directory domain

  • Five Active Directory domains per forest of domains (this equates to a practical limit of five million accounts in Active Directory deployments).

For more information, see the latest performance and scalability documents at http://www.microsoft.com/commerceserver.

SQL Server

Commerce Server supports both Microsoft SQL Server 7.0 and SQL Server 2000. It is recommended that you use SQL Server 2000; it has improved performance and an enhanced set of features. When you plan for performance and scalability, note the following:

  • SQL Server has excellent scalability and stability characteristics. SQL Server is tuned for highly dynamic data supporting read/write balances approaching 50/50 with no significant performance degradation. This maps nicely to e-commerce sites with highly dynamic attributes being kept for users (for example, Favorites and last visit date/time).

  • No limits have been found in testing up to 10 million users in the store with a one percent concurrency rate.

  • Groups created in SQL Server do not have system ACL/ACE integration that would allow you to protect static content (for example, pictures and audio files).

  • Groups implemented under SQL are created as multi-value strings with a practical limit of less than 200 users per group.

Using Active Directory and SQL Server

For those sites that require both the access control provided by Active Directory and the performance of SQL Server, it is recommended that both Active Directory and SQL Server be used together to store user profile information. In this scenario, you would store data that is associated with user credentials and data that is very stable in an Active Directory data store. You would store the remaining attributes in SQL Server.

For example, you may want to divide the attributes as shown below:

  • User profile attributes stored in Active Directory:
    • UserName

    • Password
  • User profile attributes stored in SQL Server:
    • Credit Card

    • Home Address, City, State, Zip

    • Home Phone Number

    • Date/Time of last visit

    • Favorite Color

    • Last page visited

    • Year-to-date total spent on site

Migration Attribute Compatibility

Not every Site Server 3.0 Membership Directory attribute has an equivalent attribute in a Commerce Server Profiles data store.

The following table lists the types of attributes in a Membership Directory, the equivalent type of attributes in a Profiles data store, and then the types in Active Directory and SQL Server. These are the attributes that are supported by Commerce Server without any modifications.

Membership Directory Attribute Type | Commerce Server Profile System Equivalent Type(s) | Active Directory Underlying Data Type | SQL Server Underlying Data Type
String | Text, Password, SiteTerm, Profile | String | String
Integer | Numbers Only, Decimal Currency | Number | Number
DateTime | Date/Time, Date, Time | DateTime | DateTime
Distinguished Name (DN) | Text, Password, SiteTerm, Profile | String | String
Binary | Binary | Binary | Binary
Multi-value String | Multi-value (Text, Password, SiteTerm, Profile) | Multi-value String | Multi-value String
Multi-value Integer | Multi-value NUMBER | Multi-value Integer | Not supported
Multi-value DateTime | Multi-value Date/Time, Date, Tim | Multi-value DateTime | Not supported
Multi-value DN | Multi-value (Text, Password, SiteTerm, Profile) | Multi-value String | Multi-value String
Multi-value Binary | Multi-value Binary | Multi-value Binary | Not supported

Caution

  • Use caution when enabling multi-value attributes in the profile. The underlying data type is not checked to verify whether it is flagged as a multi-value data type.

  • There are currently several data types that are supported in the profile but are not enabled at the data layer on either SQL Server or Active Directory stores. These include: Integer, Long Text, and Reference.


Preparing for Migration

Before you migrate the Membership Directory to Commerce Server, you must perform the following steps:

  1. Set Up Commerce Server Profiles. Perform this step to create the data elements and data types in the Commerce Server Profiles data store.

  2. Modify Your Migration Objects. Perform this step so your migration objects can read all of the user information, modify it as needed, and then write it to the Commerce Server Profiles store.

  3. Run the Migration ProfileBuilder Tool. Perform this step to create the Extensible Markup Language (XML) file used by the Directory Migration tool.

  4. Run the Groups Pre-Population Tool. Perform this step if you are using Windows 2000 Server Active Directory.

  5. Compile Migration Objects. Perform this step only if you have modified your migration objects.

  6. Register Migration Objects. Perform this step to register the Directory Migration tool objects. You must perform this step even if you have not modified your migration objects.


Set Up Commerce Server Profiles

The following steps assume you have installed Commerce Server 2000 and verified that a Solution Site runs successfully in your environment. You must verify that the Commerce Server Profiling System can access the required data stores (for example, SQL Server, Active Directory, other OLE DB store or a Lightweight Directory Access Protocol (LDAP) version 3-compliant store).

To set up your Commerce Server profiles

  1. Determine which attributes in the Membership Directory member class you want to migrate.

  2. Use the Profiles service in Commerce Server Manager to create the underlying data elements.

  3. Use the Profiles service to map the data elements to the relevant data types available.

See Also

Running the Profiles Resource


Modify Your Migration Objects

Depending on the requirements for your site, it may be necessary to modify the MigrationRead, MigrationWriteObj, or MigrationModifyObj objects. The objects are written in C++.

If you need to modify your objects, you should do so before running the Migration ProfileBuilder tool.

See Also

Programmer's Reference for Migration


Run the Migration ProfileBuilder Tool

After you have set up your Commerce Server profiles and modified your migration objects as required, you can run the Migration ProfileBuilder tool to generate the migration Extensible Markup Language (XML) file.

This topic contains:

  • Compiling Migration ProfileBuilder Tool

  • Mapping Attributes from Membership Directory to Profiles Data Store

Compiling Migration ProfileBuilder Tool

If you need to modify the Migration ProfileBuilder tool, you can access the source code in the following folder:

<Drive>:\Program Files\Microsoft Commerce Server\SDK\Tools\Membership Migration\ProfileBuilder

The application images were built using Microsoft Visual Basic 6.0 Professional.

After you modify the Migration ProfileBuilder tool, you must create a Data Source Name (DSN) for the Commerce Server Profiles data store using the Data Sources (ODBC) manager found in Programs | Administrative Tools on the Start menu. Create a System DSN using the SQL Server driver. Ensure you change the default connection string to point to the correct Profiles data store (for example, Retail_commerce).

Mapping Attributes from Membership Directory to Profiles Data Store

To run the Migration ProfileBuilder tool, the server running the tool must be able to access both the Membership Directory Lightweight Directory Access Protocol (LDAP) server and the Commerce Server computer running the ProfileService object.

To run the Migration ProfileBuilder tool

  1. In Windows Explorer, navigate to the folder that contains the Migration ProfileBuilder tool, and then double-click ProfileBuilder.exe.

  2. In the Step 1 dialog box, do the following:
    Use this | To do this
    Location to store all of the profiles | Type the directory that contains the XML files used by the MigrationMainObj object. Usually, you will use only one XML file.
    XML file name | Type the name of the file to be generated. The Migration ProfileBuilder tool appends a profile ID to the end of the name. In this sample, the files will be named "migration"<n>.xml where 'n' is incremented each time a profile is generated.
    ProgID of IMigrationRead | Type the ProgID of the MigrationReadObj object. This default is generated by the included source code.
    ProgID of IMigrationWrite | Type the ProgID of the MigrationWriteObj object. This default is generated by the included source code.
    ProgID of IMigrationModify | Type the ProgID of the MigrationModifyObj object. This default is generated by the included source code.
    ProgID of IMigrationLog | Type the ProgID of the MigrationLogObj object. This default is generated by the included source code.

  3. In the Step 2 dialog box, do the following:
    Use this | To do this
    Membership Directory Server | Type the Netbios name of the Membership Directory.
    Port Number | Type the port number of the Membership Directory instance.
    MD User Name | Type the distinguished name of the user for the connection to the Membership Directory.
    Password | Type the password for the Membership Directory User Name given in the MD User Name box.
    Server Name | Type the name of the SQL Server running the Commerce Server Administration database.
    Database Name | Type the name of the database where the Profiles store is located.
    DBA Name | Type the login of the user who has system administrator (sa) privileges.
    DBA's Password | Type the password of the login user.

  4. In the Step 3 dialog box, do the following:
    Use this | To do this
    Migrate MemberOf | Determine whether the migration object reading this XML file will migrate users to Active Directory groups.
    Object Schema | Type the schema representing the user to be read, for example, member. You can type in other custom classes if they are to be migrated.
    Filter Depth | Type a number to specify how fine a search is requested. This is provided as a mechanism for preventing LDAP query time-outs. A filter depth of 2 will search cn=xx*. A filter depth of 3 will search cn=xxx* ("x" = [a-z, 0-9]).
    Search Scope | Select the depth to which the tool can search sub-containers under the root from the drop-down list.
    Search Filter Base | Type a prefix for account names to be migrated in batch mode (for example, cn=a).

  5. In the Step 4 dialog box, do the following:
    Use this | To do this
    Group's parent RDN | Type the Active Directory Relative Distinguished Name (RDN).
    AD Administrator's User Name | Type the account to log in as when writing to Active Directory in the form of "domain\account."
    AD Administrator's Password | Type the password for the account named in the AD Administrator's User Name box.
    Catalog | Select the profile catalog to use. Typically this is Profile Definitions.

  6. Map the attributes to be read to those to be written. You can control the objects listed in the right pane by selecting the profile definitions from the top list boxes. To create an association, click the attribute in the Site Server box and then click the corresponding attribute in the Commerce Server box.

    The numbers on the left of the attributes indicate the mapping (for example, 49 Telephone Number = 49 tel_number).

    The following figure shows attributes mapped from the Membership Directory to the Commerce Server Profiles data store.

    A screen shot showing attributes that have been mapped

    Click the illustration to enlarge or reduce.

  7. When you are finished mapping the attributes, click Preview.

    The Step 5 dialog box displays the entire XML file.

  8. If the XML file is complete, click Yes.

The XML file is saved.


Run the Groups Pre-Population Tool

After you run the Migration ProfileBuilder tool to create the XML file, you can create the groups to which the user profiles will migrate.

To run the Groups Pre-Population tool, the server running the tool must be able to access both the Membership Directory Lightweight Directory Access Protocol (LDAP) server and the Commerce Server computer.

To run the Groups Pre-Population tool

  1. In Windows Explorer, navigate to the folder that contains the Groups Pre-Population tool, and then double-click GroupMigration.exe.

  2. In the Create group structure in AD dialog box, do the following:
    Use this | To do this
    Server Name | Type the name of the Membership Directory server.
    Port Number | Type the port number of the Membership Directory LDAP server.
    User Name | Type the login name to use to connect to the LDAP server. Use the format: domain\user.
    Password | Type the password for the login name.
    Groups DN | Type the distinguished name of the groups object.
    Group's Schema | Type the objects describing the group schemas.
    Organizational Unit | Type the organizational unit under which you want to create the groups in Active Directory.
    Server | Type the name of the server on which Commerce Server is installed.
    Port | Type the port number for the server on which Commerce Server is installed.
    Partition | Type the list of the partition(s) to be included in the Active Directory forest. Use the format: dc = <domainName>.
    Domain User Name | Type the login name of an authorized Active Directory user. Use the format: domain\user.
    Password | Type the password for the Domain User Name.

    Note

    • When entering the partitions, you must click Add to save the entry.
  3. Click Next.

  4. In the Group Attributes Map dialog box, do the following:
    Use this | To do this
    Top box on left | Select the Membership Directory group attribute category.
    Top box on right | Type the name of your Active Directory Profile data store.

  5. In the box below Description, select a user profile attribute, and then click Map to map it to the equivalent attribute in your Active Directory Profile data store. There are two entries by default: Description and MBSTokenID. In the right column type the name of the attribute to which you want to map. Make sure the attribute name you typed exists in Active Directory with the matching data type.

  6. Click Remove to remove any attributes you do not want to map.

  7. When you are finished mapping the attributes, click Finish.

The Groups Pre-Population tool reads the groups in the Membership Directory and recreates them in the Active Directory. This creation process can take a considerable amount of time, depending upon how many groups you have.


Compile Migration Objects

If you modify your migration objects, you must compile them in the following order:

  1. MigUtil

  2. MigrationModifyObj

  3. MigrationLogObj

  4. MigrationReadObj

  5. MigrationWriteObj

  6. MigrationMainObj

Note the following dependencies, and the resulting consequences for compilation order:

  • MigrationMainObj depends on the other four modules.

  • MigrationReadObj depends on MigUtil and MigrationModifyObj.

  • MigrationWriteObj depends on MigUtil and MigrationLogObj.

  • MigrationLogObj depends on MigUtil.

  • MigrationModifyObj depends on MigUtil.

The MigrationLogObj object is used by the MigrationWriteObj and MigrationMainObj objects to log errors.

The MigrationReadObj object does not log errors directly because any error it returns are logged from the MigrationMainObj object.

If the MigrationWriteObj object encounters errors while writing, it rolls back the entire user record, and then returns an error back to the MigrationMainObj object. Then the MigrationMainObj object logs the error. The MigrationWriteObj will only use the MigrationLogObj directly when errors occur in the roll back process itself.

If you make modifications to the code, recompile using Microsoft Visual Basic 6.0 Service Pack 3 or Microsoft Visual C++ 6.0 Service Pack 3.

The following table shows the required compiler settings for each component.

Component | Compile Using | Compiler Options
GroupMigration | Visual Basic 6 | Default settings.
ProfileBuilder | Visual Basic 6 | Default settings.
SubGroupManager | Visual Basic 6 | Default settings.
MigrationLogObj | Visual C++ 6 | Set active project = Release, Unicode, MinSize
MigrationMainObj | Visual C++ 6 | Set active project = Release, Unicode, MinSize
MigrationModifyObj | Visual C++ 6 | Set active project = Release, Unicode, MinSize
MigrationReadObj | Visual C++ 6 | Set active project = Release, Unicode, MinSize
MigrationWriteObj | Visual C++ 6 | Set active project = Release, Unicode, MinSize
MigUtil | Visual C++ 6 | Set active project configuration = Release


Register Migration Objects

You must register the directory migration objects on each computer on which they are installed. For example:

Regsvr32 /s MigrationLogObj.dll

Register all five objects together by copying the following code sample to a .bat file, and then run it:

Regsvr32 /s MigrationLogObj.dll
Regsvr32 /s MigrationMainObj.dll
Regsvr32 /s MigrationModifyObj.dll
Regsvr32 /s MigrationReadObj.dll
Regsvr32 /s MigrationWriteObj.dll


Starting the Migration Process

To begin the migration process, deploy the migration objects to the servers that will be running the migration process. Follow these steps:

  1. Extend the attributes for members by creating a Migration attribute in the Membership Directory.

  2. Create at least one migration profile using the Migration ProfileBuilder tool. You will need to create one for each type of migration you plan on (batch and on-demand combined).

  3. To deploy the objects you will need to copy the completed migration objects to each server and register the objects. For more information, see Register Migration Objects.

  4. You will also need to make sure that the registry keys are set appropriately. For more information, see the Requirements section of MigrationLogObj Object.

If you plan on migrating users with on-demand migration as they log into your new site, you will want to install the migration objects on the Web servers and use the Login.asp file found in the <Drive:>\Program Files\Microsoft Commerce Server\SDK\Tools\MembershipMigration\Client directory. Use this file as a sample of how to trigger a migration when a user first visits your new Commerce Server site.

If you want to migrate all of your users together, install the migration objects on the server from which you will migrate all of the users. For best performance, choose a computer that is dedicated to the migration process. When you build the profile for migrating a range of users using the Migration ProfileBuilder tool, establish a filter depth, a search scope, and a search filter base in the Step 3 dialog box. Experimenting with different values before beginning the actual migration process allows you to optimize migration performance. Note that the distribution patterns of user account names in the Membership Directory plays an important role in the tuning process.

Always test the on-demand migration process before putting it into production.


Troubleshooting with the Migration Log File

The migration objects record problems to a text log file in the directory specified by the "LogFilePath" registry key. The log file will contain reports of migration failures and events that prevented successful migration. Additional migration failure information will be logged using the data returned by the failing object.

A new log file is automatically created and used whenever the number of lines in the current log file reaches the limit defined by the "MaxNumLinesEachFile" registry key.


Verifying Successful Migration

To verify that all users have been successfully migrated, query the Membership Directory for all accounts for which the Migration attribute is missing, or for which the Migration attribute set to False. Until the query returns no accounts, migrate the returned accounts individually.

When the query returns no records, you know that all of the users were migrated.

After establishing that all users have been migrated, remember to perform the following tasks:

  • As required, replace the version of the Login.asp file that triggers on-demand migration with your original Login.asp file.

  • Unregister and remove the migration objects from the servers upon which they were installed.

  • Backup and delete the migration log files.


Programmer's Reference for Migration

This section contains reference material related to membership migration.

This section contains:

  • Migration Objects

  • Migration Utility Library

  • Sample XML File


Migration Objects

This section provides a reference page for each of the migration objects.

This section contains:

  • MigrationMainObj Object

  • MigrationReadObj Object

  • MigrationWriteObj Object

  • MigrationModifyObj Object

  • MigrationLogObj Object


MigrationMainObj Object

Use the MigrationMainObj object to coordinate the migration from the Site Server 3.0 Membership Directory to the Commerce Server Profile data store. The MigrationMainObj object uses the following four COM objects to implement this task:

  • MigrationReadObj Object

  • MigrationWriteObj Object

  • MigrationModifyObj Object

  • MigrationLogObj Object

Interface

The MigrationMainObj object supports the following interface:

interface IMigrationProfile::IDispatch
{
    HRESULT Initialize(BSTR sProfileDirectory);
    HRESULT MigrateObject(BSTR bstrKeyName, long lProfile_id);
    HRESULT ShutDown();
};

Methods

The following table shows the methods of the MigrationMainObj object, and provides a descripton of each.

Method | Description
Initialize Sets up all the components for the migration process. The sProfileDirectory parameter, indicating where all profile files reside, is parsed each for the following values:
  • An array containing the attribute names for each profile ID. These arrays will be stored in a structure that will be passed to the MigrationReadObj/MigrationModifyObj/MigrationWriteObj objects.

  • The connection string to the membership directory or SQL Server that will be passed to the MigrationReadObj/MigrationWriteObj objects in the form of an array of connection strings.

  • The profile ID for each profile so that the correct attribute array can be identified. The profile IDs will be passed to the MigrationReadObj and MigrationWriteObj objects in the form of an array of profile IDs. The profile ID is passed to the MigrationModifyObj object as a single ID.

  • The ProgID for each COM object so that it can be initialized with the above data. The ProgIDs will be stored in an array so that the correct objects can be called based on the profile ID.
MigrateObject | Called from the Active Server Pages (ASP) page or from Microsoft Visual Basic Scripting Edition (VBscript) to migrate an ADSPath key to the Commerce stores. The profile ID to be used for this ADSPath key is passed to the object. The MigrationProfile object then finds the appropriate attribute array for this profile to be filled in by the MigrationReadObj object. This array, along with the key (ADSPath) and profile ID is then passed to the MigrationReadObj/MigrationModifyObj/MigrationWriteObj objects to be processed.
ShutDown | Called from MigrationReadObj/MigrationWriteObj objects and also deallocates the data structures that were created upon initialization.

Remarks

The following structure should be added to the .IDL file to facilitate passing the profile information to each object.

typedef struct _PROFILE
    long lprofile_id;
    BSTR bstrConnection;  //bstrConfigStore in CS
    BSTR bstrCatalog;     // used in profile service initialization
    BSTR bstrMemberOf;    // migrate user's membership?
    SAFEARRAY(BSTR) Attributes;
    SAFEARRAY(USHORT) nAttributeTypes; // number of attributes types?
    SAFEARRAY(BSTR) ProfileTypes;      // only for write use
    BSTR bstrMOUserName;  // Membership User Name
    BSTR bstrMDPassword;
    BSTR bstrCSUserName
    BSTR bstrCSPassword;
    BSTR bstrADSite;      // True for ADSite, otherwise False
    BSTR bstrGroupOU;     // OU that holds all groups
    // modify info
    long lNumModifies;    // total number of modifiers in this profile
    SAFEARRAY(USHORT) rgModIndex;
} PROFILE;


MigrationReadObj Object

Use the MigrationReadObj object to read values for each attribute in the Membership Directory, and then send them to the MigrationProfile object. The MigrationReadObj object first reads the type of each attribute and then fills in the data.

Interface

The MigrationReadObj object supports the following interface:

interface IMigrationRead::IUnknown
{
    HRESULT Initialize([in] long lNumProfiles,
                       [in] size_is(lNumProfiles)] PROFILE Profile[],
                       [in] BSTR bstrModifyProgID);

    HRESULT ReadAttributes([in] BSTR bstrKeyName,
                           [in] long lProfile_id,
                           [out] SAFEARRAY(VARIANT)* AttributeStructure,
                           [out] VARIANT* varValueIndex,
                           [out] VARIANT* vMemberOfs);

    HRESULT MigrationFailed([in] BSTR bstrKeyName);

    HRESULT ShutDown();
};

Methods

The following table shows the methods of the MigrationReadObj object, and provides a description of each.

Method | Description
Initialize | Accepts an array of structs containing all the attributes for each profile ID and the connection to use. It uses this data to determine what attributes to read for a particular key based on the profile ID.
ReadAttributes | Called for each migration that needs to take place. This method uses the profile ID to find out what attributes are associated with the key and reads these from the data source into the array.
MigrationFailed | Called to set the attribute cn=Migration to FALSE when the migration of this object fails. This is of type binary and should not exist in the current schema.
Shutdown | The MigrationProfile object calls the Shutdown method, which is used to free the created connection pools.


MigrationWriteObj Object

Use the MigrationWriteObj object to write the values for each attribute to the Commerce Server Profile data store.

Interface

The MigrationWriteObj object supports the following interface:

interface IMigrationWrite::IUnknown
{
    HRESULT Initialize([in] long numBuffers,
                       [in] long numProfiles,
                       [in] size_is(numProfiles)] PROFILE Profiles[],
                       IUnknown * pIMigrationLog);

    HRESULT WriteUserAttributes([in] BSTR bstrKeyName,
                                [in] long lProfile_id,
                                [in] SAFEARRAY(VARIANT)*
                                                  AttributeStructure,
                                [in] VARIANT *varValueIndex,
                                [in] VARIANT *vMemberOfs);

    HRESULT ShutDown();
};

Methods

The following table shows the methods of the MigrationWriteObj object, and provides a description for each.

Method | Description
Initialize | Accepts an array of structs containing all the attributes for each profile ID. This method uses this data to determine what attributes to write for a particular key based on the profile ID.
WriteUserAttributes | Called for each migration that needs to take place. This method uses the profile ID to identify the attributes that are associated with the key and writes these from the array into the Commerce Server Profile data store.
Shutdown | The MigrationProfile object calls the Shutdown method, which is used to free the created connection pools.


MigrationModifyObj Object

Use the MigrationModifyObj object to change the data that has been read from the Membership Directory before it is migrated to the Commerce Server Profile data store.

Interface

The MigrationModifyObj object supports the following interface:

interface IMigrationModify::IUnknown
{
    HRESULT Initialize();
    HRESULT ModifyAttributes([in] long lProfile_id,
                             [in] BSTR bstrAttribute,
                             [in] USHORT targetType,
                             [in] USHORT sourceType,
                             [in, out] VARIANT *varTarg);
};

Methods

The following table shows the methods of the MigrationWriteObj object, and provides a description of each.

Methods | Description
Initialize | Initializes the MigrationModifyObj object. Call this method before calling the ModifyAttributes method.
ModifyAttributes | Accepts the key, profile ID, and array of values to be modified. This method uses the profile ID to determine the structure of the array based on the attributes that it read in the Initialize method.


MigrationLogObj Object

Use the MigrationLogObj object to write log data to a data store determined by the connection string. The data includes the status of each migration.

Interface

The MigrationLogObj object supports the following interface:

interface IMigrationLog::IUnknown
{
    HRESULT Initialize([in] int nLogSuccess);
    HRESULT RecordInfo([in] LOGINFO lgInfo);
    HRESULT LogSuccess([in] BSTR bstrKeyName,
                       [in] long lprofile_id);
};

The IMigrationLog interface depends on the following structure:

typedef struct _LOGINFO
{
    long  lProfile_id
    BSTR  bstrDN;
    BSTR  bstrObject;
    Long  lErrorCode;
    BSTR  bstrReason;
} LOGINFO;

Methods

The following table shows the methods of the MigrationLogObj object, and provides a description for each.

Method | Description
Initialize | Initializes the MigrationLogObj object. Call this method before calling the RecordInfo or LogSuccess methods.
RecordInfo | Use this method to record meaningful data to the log file.
LogSuccess | This method is called when a successful migration occurs and the LogLevel registry key is 1 or 3. The success code is written to a file with a name constructed by concatenating the value of the LogFilePath registry key, the string "_success", and a number that is incremented as the file exceeds the "MaxNumLinesEachFile" registry key. An example file name is: C:\MigrationLog_success1.

Requirements

The following table contains the requirements of the MigrationLogObj object.

Parameter | Description
Registry key | SYSTEM\\CurrentControlSet\\Services\\Migration\\Parameters
LogFilePath | The path of the log file. The default is "C:\MigrationLog". The data type is STRING.
MaxNumLinesEachFile | The maximum number of lines in each log file. If the number of lines exceeds this number, another log file is created in the same directory. The data type is DWORD.
MaxNumThreads | The maximum number of threads that run against the migration tool. The default value is four. The data type is DWORD.
AttributeFactors The number of entries in the mapping section for each attribute in an XML file. The type is DWORD. The default value is four, counting the following four lines:
<FromMembership>givenName</FromMembership>
<ToUPS>GeneralInfo.first_name</ToUPS>
<WProfileType>UserObject</WProfileType>
<WTypes>VT_BSTR</WTypes>

Each attribute in the mapping section contains these four lines, with different values.
ADsSearchPageSize | Size of search page. The type is DWORD. See the Active Directory Service Interfaces (ADSI) documentation for more information.
MaxNumLinesEachFile | The maximum number of lines in each log file. When this number is reached, a new log file is created in the same location with the file name extended with sequential numbers. The data type is DWORD.
NumberOfLinesToFlush | Use this parameter to flush the memory when the log file contains the indicated number of lines. The data type is DWORD.
MaxAttributesFetched The number of attributes having values you request from the Membership Directory. A number that is too high may result in a time-out; a number that is too low will adversely affect performance. Do not set this value first.

Set this value to 50 if you receive a time-out error in the MigrationReadObj object. The data type is DWORD.
InitialWaitPeriod | The time in milliseconds that the process sleeps for the first time. The default value is zero (0). It is recommended you set this to less than five (5). The data type is DWORD.
BackOffTimes | The number of times to retry in case of failure. The default value is zero (0). It is recommended you set this to less than four (4). The data type is DWORD.
LogLevel Log level values are:

0 = Logs error only

1 = Logs error and success

2 = Logs error and performance

3 = Logs error and success and performance

The data type is DWORD.


Migration Utility Library

The Migration Utility Library, MigUtil, contains global settings and methods. These include the following global variables:

  • Global variable g_pwszUserObject. Corresponds to the default setting in Commerce Server. If you switch to a different profile (other than UserObject), the name of the new profile should be assigned to this global variable.

  • Global variable g_searchOrder. Holds all the possible symbols that may appear in the search filters for Common Name (CN) except digits from 0 to 9, which will be converted to characters in the initialization stage. You have to allocate ten more spaces in this array to hold these ten numbers. For example:
    WCHAR g_searchOrder[128] = {L'a', L'b', L'c', L'd', L'e', L'f', L'g',
                            L'h', L'i', L'j', L'k', L'l', L'm', L'n',
                            L'o', L'p', L'q', L'r', L's', L't', L'u',
                            L'v', L'w', L'x', L'y', L'z'};

    In this example, the 128 characters that are reserved are more than sufficient (including the ten extra characters).

  • Global variable g_numSymbols. Contains the number of symbols you want to store in the array of g_searchOrder (not including the ten digits). For example:
    int g_numSymbols = 26;


Sample XML File

The following is a sample migration profile XML file. The Migration ProfileBuilder tool in the Commerce Server 2000 Software Development Kit (SDK) builds XML files that resemble the following:

<?xml version="1.0" ?>
<PROFILE1>
    <MIGRATION-PROFILE>
        <ProfileID>2</ProfileID>
    </MIGRATION-PROFILE>
    <MigrationObjects>
        <ReadObj>MigrationReadObj.MigrationRead</ReadObj>
        <WriteObj>MigrationWriteObj.MigrationWrite</WriteObj>
        <ModifyObj>MigrationModifyObj.MigrationModify</ModifyObj>
        <LogObj>MigrationLogObj.MigrationLog</LogObj>
    </MigrationObjects>
    <MembershipDirectory>
        <MConnectionString>LDAP://localhost1:1003</MConnectionString>
        <MigrateMemberOf>TRUE</MigrateMemberOf>
        <MDUserName>cn=administrator,ou=members,o=migration</MDUserName>
        <MDPassword>password</MDPassword>
    </MembershipDirectory>
    <SearchFilterInfo>
        <FilterDepth>2</FilterDepth>
        <ADsSearchScope>2</ADsSearchScope>
        <SearchFilterBase>cn=</SearchFilterBase>
    </SearchFilterInfo>
    <UserProfileService>
        <ADSite>TRUE</ADSite>
        <GenerateSamAccount>TRUE</GenerateSamAccount>
        <UConfigStore>SERVER=localhost2;
                      DATABASE=supplierAD_commerce;
                      UID=sa;PWD=</UConfigStore>
        <UCatalog>Profile Definitions</UCatalog>
        <GroupOUToDC>OU=MSCS_40_Root</GroupOUToDC>
        <CSUserName>administrator</CSUserName>
        <CSPassword>csdqfe</CSPassword>
    </UserProfileService>
    <Mapping>
        <FromMembership>givenName</FromMembership>
        <ToUPS>GeneralInfo.first_name</ToUPS>
        <WProfileType>UserObject</WProfileType>
        <WTypes>VT_BSTR</WTypes>
        <FromMembership>sn</FromMembership>
        <ToUPS>GeneralInfo.last_name</ToUPS>
        <WTypes>VT_BSTR</WTypes>
        <WProfileType>UserObject</WProfileType>
        <FromMembership>cn</FromMembership>
        <ToUPS>ProfileSystem.sam_account_name</ToUPS>
        <WTypes>VT_BSTR</WTypes>
        <WProfileType>UserObject</WProfileType>
    </Mapping>
</PROFILE1>


Deploying Your Site

You deploy a Microsoft Commerce Server 2000 Web site by obtaining and configuring the required hardware and software, installing Commerce Server 2000, unpacking your Web site, and putting in place the procedures for monitoring and managing your site. The overall deployment process falls into the stages described in this section.

This section contains:

  • Before You Deploy. Describes the items that should be completed before you begin the deployment process.

  • Setting Up Your Server Platforms. Explains how to set up development, test, and production environments so that you can move your site from a development environment, test it, and then deploy it. Explains how to configure your software platform before installing Commerce Server.

  • Installing Your Site. Explains how to install Commerce Server and unpack your Web sites on two different small site configurations.

  • Securing Your Site. Explains how to configure your sites to prevent unauthorized access to them.

  • Backing Up Your Site. Explains how to back up your site.

  • Updating Your Site. Explains how to update your site content and databases after the initial deployment.

  • Using Site Packager. Describes what you can do with Commerce Server Site Packager, and explains in general terms how to package and unpack a site. Also lists reference information for Site Packager.

See Also

Planning for Deployment

Planning Your Commerce Server Installation


Before You Deploy

Before you deploy your site, review the following checklists to ensure that your planning is complete.

This section contains:

  • Site Architecture Checklist. Provides a checklist for planning and implementing your site architecture.

  • High Availability Checklist. Provides a checklist for protecting against server failure.

  • Site Development and Testing Checklist. Provides a checklist for completing your site development and testing.

  • Business Processes Checklist. Provides a checklist for planning and implementing your business processes.

  • Platform Security Checklist. Provides a checklist for securing your Windows 2000 platform, and Internet Information Services (IIS) 5.0.

  • Commerce Server Security Checklist. Provides a checklist for setting up security on your site.

See Also

Planning for Deployment

Planning Your Commerce Server Installation

Hardware Requirements

Software Requirements


Site Architecture Checklist

Before you deploy your site, make sure you have planned and implemented your site architecture. Check for the following:

  • A Microsoft Windows 2000 Server network is in place, containing at a minimum one Microsoft Active Directory domain controller. Windows 2000 Advanced Server is recommended if you are using Network Load Balancing (NLB) or creating server clusters, both of which increase the availability of your site.

  • Ideally, you need two computers to handle Active Directory efficiently. They would serve as replicated domain controllers. Your other computers would then join the domain. For more information, see Setting Up Your Active Directory Servers.

  • The Windows 2000 domain architecture for the Commerce servers has been determined and is documented.

  • Server names, roles, ports, and required services are identified and documented.

    Note

    • If possible, do not change the names of your servers. For more information, see Changing the Names of Servers.
  • The necessary Internet domain names and Internet Protocol (IP) addresses have been obtained.

  • Windows 2000, Internet Information Services (IIS) 5.0, and Microsoft SQL Server security models have been determined.

  • Internet Explorer version 5.0 or later is installed. Commerce Server Business Desk client computers require Internet Explorer 5.5.

  • Firewalls and proxy servers are in place.

  • Initial users, groups, permissions, and policies are set up.

  • Server hardware is installed at the site.

  • Client hardware for Business Desk client computers is installed at the site.

  • Network hardware and connections are in place and connectivity to the Internet has been established.

  • Replacement hardware is available at the site.

  • Windows 2000 Terminal Services has been set up, if you plan to use remote computers for Business Desk sessions. For more information, see Terminal Services online documentation.

  • All the necessary software defined in Planning Your Commerce Server Installation is available at the site.


High Availability Checklist

Before you deploy your site, make sure you have planned for protecting against server failure using a combination of the following methods:

  • Geographically dispersed data centers.

  • Uninterruptible dual power supplies.

  • Data backups.

  • Clustered database servers. In Windows clustering, two servers sharing common data form a cluster that works as a single system. For more information, see Setting Up a Server Cluster.

  • Data replication. Microsoft SQL Server replication is used to ensure synchronization among the database servers for a site. SQL Server offers replication options that include snapshot replication and transactional replication. For more information, see Using SQL Server to Replicate Databases.

  • Network load-balanced clusters for Web servers. Network Load Balancing (NLB) provides availability and load balancing for Web (IIS/ASP-based) applications.

For more information about preventing site failure, see Planning for High Availability and the Commerce Server 2000 Resource Kit.


Site Development and Testing Checklist

Before you deploy your site, make sure you have completed your site development and testing. Check for the following:

  • Site development is complete.

  • Site is packaged.

  • A list of site resources has been documented.

  • Names have been determined for site servers.

  • Database names, user names, and passwords have been determined.

  • Testing is complete. You have tested for the following items: content, browser compatibility, performance, server load, databases, search options, query response time, data validity and integrity, system recovery, visual consistency, links, and routers. You have tested the performance of your site using the Web Application Stress tool.

  • An independent, outside company has completed a security audit of your site. Such a review is an effective means for discovering security risks.

  • For more information about testing your site, see the Commerce Server 2000 Resource Kit.


Business Processes Checklist

Before you deploy your site, make sure you have planned and implemented your business processes. Check for the following:

  • Workflows have been determined and tested.

  • System administrators have received initial training and business managers, the primary users of Commerce Server Business Desk, have completed the Business Desk tutorial.

  • The server environment team has been identified and operational procedures have been determined (for example, change request, change control log, server update, maintenance schedules, and problem escalation procedures).

For more information, see Planning for Business Process Pipelines.


Platform Security Checklist

There are several ways to enhance the security of a computer publishing information on an intranet or the Internet. If you have concerns about the security of your system, review this checklist to determine if aspects of your security could be improved.

Note

  • For highly sensitive information, you should seek the assistance of a professional security consulting firm. A consulting firm can help you establish proper security policies and procedures.

Windows Security

Internet Information Services Security

Physical Security

Personnel Security

Windows Security

The security features in Commerce Server are built upon those in Windows. The following settings in Windows will help make your Web site secure.

File System

 | Action | Reason
 | Use NTFS | The NTFS system is more secure than the FAT system. For information about converting your computer's hard disk from FAT to NTFS, see the Windows documentation.
 | Review directory permissions | By default, Windows creates new folders and assigns Full Control permissions to the Everyone group.
 | Set access control for the IUSR_computername account | This will help limit the access anonymous users have to your computer.
 | Store executable files in a separate directory | This makes it easier to assign access permissions and auditing.
 | Check NTFS permissions on network drives | By default, Windows creates new shared resources and assigns Full Control permissions to the Everyone group.

User Accounts

 | Action | Reason
 | Review user accounts often | Check for new accounts that were not created by a valid administrator. Review the rights given to the IUSR_computername account. All users gaining anonymous access to your site have the rights assigned to this account. You can also use auditing to monitor when and by whom security policies are changed.
 | Choose difficult passwords | Passwords are more difficult to guess if they consist of a combination of lowercase and uppercase letters, numbers, and special characters.
 | Maintain strict account policies | Keep track of what types of access are given to important user accounts and groups. This includes knowing who has the ability to change security policies.
 | Limit the membership of the Administrators group | This group typically has full access to the computer.
 | Assign a password to the Administrator account | By default the password used for the Administrator's account is blank. To improve security, set a difficult password for this account, as discussed earlier.

Services and Other Issues

 | Action | Reason
 | Run minimal services | Run only the services that are absolutely neccessary for your purposes. Each additional service that you run presents an entry point for malicious attacks. For more information about services and security, see the Microsoft Windows 2000 Server Resource Kit.
 | Do not use PDC as a server | The primary domain controller (PDC) is constantly processing authentication requests. Running a Web service on the PDC will decrease performance. It could also expose your PDC to attacks that could render your entire network non-secure.
 | Enable auditing | Auditing is a very valuable tool for tracking access to secure or critical files. Auditing can also be used for tracking server events, such as a change in your security policy. Audit logs can be archived for later use.
 | Use encryption if administering your computer remotely | Typically, remote administration involves the exchange of sensitive information, such as the password for the Administrator's account. To protect this information over open networks, use Secured Sockets Layer (SSL) encryption.
 | Use a low–level account to browse the Internet | Using the Administrator, Power User, or another highly-privileged account to browse the Internet can potentially open entry points on your computer for attacks. Likewise, never browse the Internet from the primary domain controller (PDC).
 | Back up vital files and the registry often | No security effort can guarantee data safety. For more information, see the Microsoft Windows 2000 Server Resource Kit.
 | Run virus checks regularly | Any computer on an open network is susceptible to computer viruses. Regular checkups can help avoid unnecessary data loss.
 | Unbind unnecessary services from your Internet adapter cards | Warning Be sure to check with your system administrator before unbinding services, because this could have undesirable effects on other users of your system.

Internet Information Services Security

IIS provides frontline security for your Web site, including authentication and Web permissions.

Authentication

 | Action | Reason
 | Use most secure form of authentication possible | Use the most secure form of authentication that your clients support. For example, integrated Windows authentication and Digest authentication are more secure than Basic authentication. Client certificates can also be used for highly secure authentication.
 | One-to-one mapping versus many-to-one mapping | You can use either or both of these methods to map client certificates to Windows user accounts. One-to-one mapping offers a higher level of certainty, but requires a copy of the client certificate to be stored on the server. Many-to-one mapping is easier to implement and does not require a copy of the certificate to be stored on the server.

Web Permissions

 | Action | Reason
 | Synchronize Web and NTFS permissions | If Web permissions and NTFS permissions are not synchronized, the more restrictive of the two is used. Synchronization can be done manually, or by using the Permissions Wizard.
 | Use IP address restriction if administering IIS remotely | For more information, see "Granting and Denying Access to Computers" in the IIS Documentation.
 | Use the most restrictive permission possible | For example, if your Web site is used only for viewing information, assign only Read permissions. If a directory or site contains ASP applications, assign Scripts Only permissions instead of Scripts and Executables permissions. For more information, see "Setting Web Server Permissions" in the IIS Documentation.
 | Write and Scripts and Executable permissions | Use this combination with extreme caution. It can allow someone to upload potentially dangerous executable files to your server and run them. For more information, see "Setting Web Server Permissions" in the IIS Documentation.

Physical Security

 | Action | Reason
 | Lock the workstation when away | When you are not at the computer, lock the desktop by pressing the shortcut keys CTRL + ALT + DELETE, and selecting Lock Workstation.
 | Use a password-protected screen saver | The time delay should be short so that no one can use the computer after you leave. The screen saver should be blank; animated screen savers can decrease server performance.
 | Lock up the computer | Keep the computer locked in a secure room in order to reduce the chance of access by malicious individuals.

Personnel Security

 | Action | Reason
 | Use different Administrator accounts | Each individual who has administrative privileges should be given a distinct user account and password. This will make it easier to track any changes that are made.
 | Use non-disclosure agreements | Further accountability can be enforced by using non-disclosure agreements.
 | Periodically reassign accounts | To lower the risk of user account information being compromised, assign new user accounts to personnel with Administrator or other high-level privileges.
 | Quickly delete unused accounts | This will lower the risk of a disgruntled former employee or vendor gaining access to your network.


Commerce Server Security Checklist

Before you deploy your site, make sure you have planned and implemented your site security.

Use the following guidelines when setting up security for your site:

  • Whenever possible, install Internet Information Services (IIS) 5.0 and SQL Server on separate computers. Having users connect to the computers that store your databases presents security risks to your data. You should keep Web applications and databases on separate computers.

  • Always keep sensitive data secure behind a firewall.

Use the following deployment guidelines to protect your site from internal attacks:

  • Restrict physical access to all computers.

  • Restrict the number of users logged on to all computers; give users only the minimum necessary privileges needed to get their work done.

  • Change passwords frequently, especially after someone leaves your organization.

  • Keep logs of all system activity and review them frequently.

  • Keep all backups in a secure place.

  • Use the Commerce Server CS Authentication resource to establish or change the authentication and identification method for your Microsoft Commerce Server 2000 site. For more information, see Managing the CS Authentication Resource

The following is a list of other security items that you should take care of during or immediately after you deploy your site:

  • Limit access to Commerce Server folders and files.

  • Limit access to Commerce Server services.

  • Limit access to Business Desk modules.

  • Limit access to the Administration database.

  • Secure log files.

  • Enable only the most secure version of Integrated Windows (NTLM) authentication.

  • Delete the "sa" SQL administrative login.

  • Provide full access to database administrators.

For information about these post-installation security items, see Securing Your Site.

This section contains:

  • Securing Business Desk Sessions

  • Using Active Directory to Store User Information

  • Separating Users from Internal Domains

  • Protecting SQL Server Passwords

  • Setting Up Data Warehouse Permissions

  • Securing Cookies

  • Using Scripts to Set Permissions on Folders that Contain Your Site

  • Hosting Sites for External Customers

Securing Business Desk Sessions

When Commerce Server Site Packager unpacks a Commerce Server Business Desk application, it is configured to use Integrated Windows authentication. Although this secures client authentication, the Business Desk session itself passes data in clear text. To provide security for Business Desk sessions, consider only allowing Business Desk clients inside your Internet firewall. To provide additional security, you can use Secure Sockets Layer (SSL) for Business Desk connections. For more information about SSL, see "Setting Up SSL on Your Server" in the IIS 5.0 documentation.

Using Active Directory to Store User Information

User information, including passwords, credit card numbers, and phone numbers are stored in clear text in the Commerce Server Profiles database. SQL Server secures this information against unauthorized access, but to improve its security, consider using Active Directory to store sensitive user data. For more information, see Planning for Active Directory Integration.

You can also consider using third-party products that encrypt SQL Server data.

Separating Users from Internal Domains

If you use Microsoft Active Directory for your site and for your internal organization, you should use separate domains. Administering user data outside of your corporate network might require more administrative time and effort, but the security improvement is usually worth the cost. If you share a domain for internal and external use, it is possible for external user data to wind up in your internal Active Directory global catalog. If you have a reason to use your internal Active Directory in your site, it is a good idea to put your Commerce Server Business Desk server on the same side of the firewall as your Active Directory domain controller. The risks of sharing internal and external Active Directory information include site defacement, fraudulent purchases, account changes, denial of service, and virus placement.

Protecting SQL Server Passwords

When a Web server connects to a SQL Server, the SQL password travels in clear text. To protect a SQL Server connection from intruders, use the multi-protocol network driver in SQL Server, which allows encryption of session connections. If you use Windows NT authentication, this password will be protected, except in Commerce Server Setup and if you choose the Quick Unpack option in Commerce Server Site Packager.

Setting Up Data Warehouse Permissions

One way to give Commerce Server Business Desk users the ability to read and modify objects in the Commerce Server Data Warehouse is to give them a Windows Administrator account. However, you may want some Business Desk users to be able only to read reports. You can do this by assigning specific SQL Server database roles to different users. The db_datareader role allows users to see all data from all tables in a database. The db_datawriter role allows users to add, change, or delete data from tables in the database.

To add a user to a SQL Server database role

  1. Click Start, point to Programs, point to Microsoft SQL Server, and then click Enterprise Manager.

  2. In SQL Server Enterprise Manager, expand a server group, and then expand the server you want.

  3. Expand Databases, expand the database in which the role exists, and then click Roles.

  4. In the details pane, right-click the role to which the user will be added, and then click Properties.

  5. In the Database Role Properties dialog box, click Add.

  6. In the Add Role Members dialog box, select the user you want to add, and then click OK.

    Only users in the selected database can be added to the role.

Securing Cookies

By default, cookies travel in clear text. It is possible for intruders to intercept information contained in cookies and use that information to impersonate users. However, cookies can be encrypted. Commerce Server 2000 employs authentication and anonymous cookies that are encrypted to enhance security. To help secure cookies, use encryption, and embed the Internet Protocol (IP) address of the client in them. This allows the target server to verify that cookies are actually sent by the correct user.

Using Scripts to Set Permissions on Folders that Contain Your Site

Commerce Server Site Packager does not package or unpack any NTFS folder or file permissions (access control lists). Make sure you secure the files and folders that contain your site after you unpack it. A good way to do this is to use the scripting hooks of Site Packager to change folder permissions while or after you run Site Packager. For more information, see Using Scripts with Site Packager.

Hosting Sites for External Customers

If you are an Application Service Provider (ASP) hosting sites for external customers, do not host multiple sites on a single computer. Each customer site should have its own Administration database. Users from one site may be able to read data from other sites if multiple sites share the same Administration database. If users can upload scripts to your site, the security risk is greater because these scripts could contain code that reads and writes from the Administration database and other Commerce Server databases.


Setting Up Your Server Platforms

The installation described in this topic is a four-computer configuration containing a pair of Web servers using Network Load Balancing (NLB) and a pair of SQL Server cluster servers. For more information about this configuration, see Small Site Configuration.

Follow these steps to set up servers for a Commerce Server 2000 Web site:

  • Review the computer configuration you have planned.

  • Incorporate any configuration changes discovered through testing.

  • Create a standard configuration for each computer role. In a small configuration, roles include Web servers and database servers.

  • Install Microsoft Windows 2000 Server or Advanced Server on all computers in your test environment, configuring them according to your configuration documentation with the appropriate domain membership, Internet Protocol (IP) addresses, Domain Name System (DNS) client configuration, services, and Microsoft SQL Server.

    Alternatively, you can create one server image for each role and use Microsoft Application Center 2000 to replicate the image to other servers in that role, if your server hardware meets the requirements for imaging. For more information, see the Microsoft Application Center 2000 documentation.

This section contains:

  • Setting Up Your Web Servers. Explains how to install Network Load Balancing clusters and install Web servers to an Active Directory domain on a four-computer configuration.

  • Setting Up Your Database Servers. Explains how to set up two SQL Server cluster servers on a four-computer configuration.

  • Setting Up Your Active Directory Servers. Explains how to set up two Web servers using Network Load Balancing, two SQL Server cluster servers, and two Microsoft Active Directory domain controllers on a six-computer configuration.


Setting Up Your Web Servers

This section applies to a four-computer configuration containing a pair of Web servers using Network Load Balancing (NLB) and a pair of SQL Server cluster servers. For more information about the configuration, see Small Site Configuration.

To set up your Web servers, ensure you do the following:

  • Verify that your Web servers are the computers you will use to host your Web sites and the Commerce Server run-time components. To separate the business logic tier from the database tier, your Web servers should not contain any of your databases. Before you install Commerce Server 2000, you must ensure that the required software platform exists on your Web servers. For more information, see Software Requirements.

  • Install Windows 2000 Server or Advanced Server.

  • Verify that Windows 2000 NLB clusters have been set up.

  • Verify that an Internet Information Services (IIS) 5.0 Web site has been created for each of your sites.

This section contains:

  • Installing Network Load Balancing Clusters

  • Joining Web Servers to an Active Directory Domain

  • Configuring IIS

See Also

Web Servers


Installing Network Load Balancing Clusters

Microsoft Windows 2000 Network Load Balancing (NLB) enhances the availability and scalability of Commerce Server applications. By combining the resources of two or more Web servers into a single load-balancing cluster, you can deliver a more reliable Web site.

Each server runs separate copies of your Commerce Server applications. NLB balances the workload among each server by allowing the group of them to be addressed by the same set of cluster Internet Protocol (IP) addresses.

You can install NLB by using any of the following programs:

  • Microsoft Application Center 2000

  • Windows 2000 Advanced Server

  • Windows 2000 Datacenter Server

For information about installing NLB, including hardware requirements, see the documentation for the product you will use for the installation.


Joining Web Servers to an Active Directory Domain

If you create a Microsoft Active Directory domain, make sure your Web servers belong to the domain before you install Commerce Server 2000. For more information about Active Directory, see Setting Up Your Active Directory Servers.

Note

  • You must be logged on as an administrator to the local computer and have a valid user name and password to join the computer to a domain. If you do not know which user name and password to use, contact your system administrator.

To join a domain

  1. Click Start, point to Settings, click Control Panel, and then click System.

  2. In the System Properties dialog box, on the Network Identification tab, click Properties.

  3. In the Identification Changes dialog box, in the Member of box, select Domain, type the name of the domain you want to join, and then click OK.

    You are prompted to provide a user name and password to join the computer to the domain.

    Note

    • If you want longer names to be recognized by the Active Directory domain, the domain administrator must enable registration of Domain Name System (DNS) names that are 16 bytes or longer.
  4. To close the System Properties dialog box after you have entered the user name and password, click OK.

You are prompted to restart your computer to apply your changes.

See Also

  • Setting Up Your Active Directory Servers


Configuring IIS

Internet Information Services (IIS) 5.0 is installed on Microsoft Windows 2000 Server and Advanced Server by default.

To provide additional security for your Web sites, you should create a new IIS Web site for each site you are planning to install with Commerce Server. By default, Commerce Server installs your site in the IIS Default Web Site. When you use Commerce Server Site Packager to unpack your site, you can specify that it reside in the IIS Web site you created rather than in the Default Web Site.

To create a new IIS Web site

  5. Click Start, point to Programs, point to Administrative Tools, and then click Internet Services Manager.

  6. In the Internet Information Services dialog box, right-click the name of the computer on which you want to create the new IIS site, point to New, and then click Web Site.

  7. In the Web Site Creation Wizard dialog box, click Next.

  8. In the Web Site Description dialog box, in the Description box, type a name for the new Web site. This name will appear as the site name in Internet Services Manager. Click Next.

  9. In the IP Addresses and Port Settings dialog box, do the following:
    Use this | To do this
    Enter the IP address to use for this Web site | Type or select from the drop-down list the Internet Protocol (IP) address for this Web site. The All Unassigned value on the drop-down list refers to IP addresses that are assigned to a computer but not assigned to a specific site. The Default Web Site uses all of the IP addresses that are not assigned to other sites. Only one site can be set to use unassigned IP addresses.
    TCP port this Web site should use (Default: 80) | Type the port address for this Web site.
    Host Header for this site (Default: None) | Assign the host header name for this Web site. If you are adding additional sites to a single IP address by using host headers, you must assign a host header name.

  10. Click Next.

  11. In the Web Site Home Directory dialog box, do the following:
    Use this | To do this
    Path | Type the location in your Windows file system for your site root directory.
    Allow anonymous access to this Web site | Allow remote users to connect to that site without a user name or password.

  12. Click Next.

  13. In the Web Site Access Permissions dialog box, specify the permissions you want to assign to users who access the Web site home directory, specified in the previous step, and then click Next.

  14. To close the wizard, click Finish.

Notes

  • It is a good idea to install the Domain Name System (DNS) service on a computer on your intranet. If your intranet is small, you can use Hosts or Lmhosts files on all computers in your network. DNS allows users to access your site with text names instead of IP addresses.

  • For security purposes, it is recommended that all drives used with IIS be formatted with NTFS.

See Also

Using Commerce Server and IIS


Setting Up Your Database Servers

This section applies to a four-computer configuration containing a pair of Web servers using Network Load Balancing (NLB) and a pair of SQL Server cluster servers. For more information about the configuration, see Small Site Configuration.

Your database servers are the computers you use to host your Commerce Server databases and application databases, and the Commerce Server Direct Mailer and Predictor resources, if you decide to install them. To separate the business logic tier from the database tier, your database servers should not contain any of your applications or administrative tools. One exception is Direct Mailer, which you can install on your database server in a small site configuration. Before you install Commerce Server 2000, you must ensure that the required software platform exists on your database servers. For more information, see Software Requirements.

Note

  • Commerce Server does not support a mixed SQL Server 7.0 and SQL Server 2000 configuration for the Data Warehouse and OLAP server databases.

Setting Up a Server Cluster

To provide high availability for your SQL Server databases, it is recommended that you store them on server clusters. Servers configured as clusters share common data and work as a single system. Each server can operate independently of other servers in the cluster. So if one server fails, another server takes over its functions.

Before you install a server cluster, the servers in the cluster must be configured with compatible disk drives, network adapters, and disk controllers. For more information about these requirements, consult your hardware vendor.

There are several server clustering techniques, including shared disks and mirrored disks, to consider using, depending on your needs and budget. Also, you can configure your servers as active/active, in which each server runs applications while also serving as a backup for the other server, or active/passive, in which one server runs applications while the other one serves as a backup. Making these decisions requires that you consider the role of server clusters in your site. Before creating server clusters, you need to plan for them carefully. For more information about planning for server clusters, see the Microsoft Windows 2000 Server Deployment Planning Guide.

After you develop a server cluster plan, use the Windows Cluster Service Configuration Wizard to create and configure your server cluster. For more information, see Step-by-Step Guide to Installing Cluster Service.

When you install server clusters, it is important that you install applications in a prescribed order. For information about how to install SQL Server on a server cluster, see the Microsoft Product Support Services Web site.

Note

  • In the initial release of Commerce Server 2000, Commerce Server Direct Mailer does not support installation to a SQL Server virtual cluster. Install Direct Mailer to a physical node of the SQL Server virtual cluster using the name of the physical computer, and use a SQL Server instance that is separate from the virtual instance. Check the Microsoft Commerce Server Web site for an updated solution.


Setting Up Your Active Directory Servers

This section applies to a six-computer configuration containing a pair of Web servers using Network Load Balancing (NLB), a pair of SQL Server cluster servers, and a pair of Microsoft Active Directory domain controllers. For more information about the configuration, see Small Site Configuration.

If you decide to implement Active Directory to store user profile or other data, you must complete several steps, which are described in the following topics.

Note

  • Before you complete any of these steps, it is important that you understand Active Directory and its role in your site plan. For more information about Active Directory, see Active Directory Overview.

This section contains:

  • Creating an Active Directory Domain. Explains how to set up an Active Directory domain controller. Having a separate domain for each site, separate from domains on the corporate network, enhances site security.

  • Adding a Domain Controller to an Existing Domain. Explains how to add a domain controller to an existing domain. While this step is not mandatory, it is highly recommended to ensure availability for any user profile data you store in Active Directory.

  • Enabling Web Servers to Authenticate Users on Other Servers. Explains how to configure Windows to ensure that users can access all Commerce servers.

See Also

Planning for the Profiling System

Planning for Active Directory Integration


Creating an Active Directory Domain

Before you can enable Active Directory authentication for your Commerce Server Web site user profile information, you must set up an Active Directory domain on your site. It is recommended that you dedicate a replicated pair of servers for this purpose.

Use one of these procedures only if you understand Active Directory concepts, and have planned your Active Directory structure. For information about Active Directory, see the Microsoft Windows 2000 Server Deployment Planning Guide.

To set up an Active Directory domain by creating a new domain tree

To set up an Active Directory domain by creating a new child domain in an existing domain tree

To set up an Active Directory domain by creating a new domain tree

  1. Click Start, and then click Run.

  2. In the Run dialog box, in the Open box, type dcpromo, and then click OK.

  3. In the Active Directory Installation Wizard, click Next.

  4. In the Domain Controller Type dialog box, select Domain controller for a new domain, and then click Next.

  5. In the Create Tree or Child Domain dialog box, select the Create a new domain tree option, and then click Next.

  6. In the Create or Join Forest dialog box, do the following:
    Use this | To do this
    Create a new forest of domain trees | Select this option if this is the first domain in your organization, or if you want the new domain tree you are creating to be completely independent of your current forest.
    Place this new domain tree in an existing forest | Select this option if you want the users in the new domain tree to have access to resources in existing domain trees, and vice versa.

  7. If you selected the Create a new forest of domain trees option, in the New Domain Name dialog box, in the Full DNS name for new domain box, type the full Domain Name System (DNS) name for the new domain.

  8. In the NetBIOS Domain Name dialog box, in the Domain NetBIOS name box, type the name that users of earlier versions of Microsoft Windows will use to identify the domain. It is recommended that you accept the default, which is a shortened version of the full DNS name. Click Next.

  9. In the Database and Log Locations dialog box, accept the default settings unless you have a specific reason to change them.

  10. In the Shared System Volume dialog box, accept the defaults setting unless you have a specific reason to change them.

  11. If DNS is not installed on your computer, you will be prompted to install it. Select Yes, install and configure DNS on this computer, and then click Next.

  12. In the Permissions dialog box, select the Permissions compatible only with Windows 2000 servers option, and then click Next.

Caution

  • Allowing backward compatibility can lead to security problems with Commerce Server 2000.
  13. In the Directory Services Restore Mode Administrator Password dialog box, do the following:
    Use this | To do this
    Password | Type the password you want to assign to the Administrator account for the server.
    Confirm password | Type the password again to confirm it.

  14. In the Summary dialog box, review the options you selected to ensure your Active Directory configuration is correct. If it is, click Next, or to reconfigure your selections, click Back.

    The Configuring Active Directory dialog box appears, notifying you that the Active Directory you configured is being installed on your computer.

  15. In the Completing the Active Directory Installation Wizard dialog box, click Finish.

To set up an Active Directory domain by creating a new child domain in an existing domain tree

  1. Click Start, and then click Run.

  2. In the Run dialog box, in the Open box, type dcpromo, and then click OK.

  3. In the Active Directory Installation Wizard, click Next.

  4. In the Domain Controller Type dialog box, select Domain controller for a new domain, and then click Next.

  5. In the Create Tree or Child Domain dialog box, select the Create a new child domain in an existing domain tree option, and then click Next.

  6. In the Child Domain Installation dialog box, do the following:
    Use this | To do this
    Parent domain | Type the parent domain name.
    Child domain | Type the child domain name.

  7. In the NetBIOS Domain Name dialog box, in the Domain NetBIOS name box, type the name that users of earlier versions of Microsoft Windows will use to identify the domain. It is recommended that you accept the default, which is a shortened version of the full DNS name. Click Next.

  8. In the Database and Log Locations dialog box, accept the default settings unless you have a specific reason to change them.

  9. In the Shared System Volume dialog box, accept the default settings unless you have a specific reason to change them.

  10. If DNS is not installed on your computer, you will be prompted to install it. Select Yes, install and configure DNS on this computer, and then click Next.

  11. In the Permissions dialog box, select the Permissions compatible only with Windows 2000 servers option, and then click Next.

Caution

  • Allowing backward compatibility can lead to security problems with Commerce Server 2000.
  12. In the Directory Services Restore Mode Administrator Password dialog box, do the following:
    Use this | To do this
    Password | Type the password you want to assign to the Administrator account for the server.
    Confirm password | Type the password again to confirm it.

    The Configuring Active Directory dialog box appears, notifying you that the Active Directory you configured is being installed on your computer.

  13. In the Completing the Active Directory Installation Wizard dialog box, click Finish.

See Also

Small Site Configuration

Joining Web Servers to an Active Directory Domain


Adding a Domain Controller to an Existing Domain

After you create multiple domain controllers, Active Directory frequently and automatically replicates directory information between them. If a domain controller becomes unavailable, directory information is still available through the other domain controllers.

To add an additional domain controller to an existing domain

  1. Click Start, and then click Run.

  2. In the Run dialog box, in the Open box, type dcpromo, and then click OK.

  3. In the Domain Controller Type dialog box, select Additional domain controller. This creates the domain controller as a replication partner.

  4. In the Network Credentials dialog box, type the user name of a domain administrator, the password, and the name of the domain, and then click Next.

  5. In the Additional Domain Controller dialog box, click Next.

  6. In the Database and Log Location dialog box, accept the defaults, and then click Next.

  7. In the Shared System Volume dialog box, click Next.

  8. In the Directory Services Restore Mode Administrator Password dialog box, leave the boxes blank, and then click Next.

  9. On the Summary dialog box, click Next.

  10. When the Completing Active Directory dialog box appears, click Finish, and then restart Windows.


Enabling Web Servers to Authenticate Users on Other Servers

Commerce Server 2000 requires that a Web server be able to authenticate users to access services located on other servers. You must ensure that Microsoft Windows is configured to allow such access.

Note

  • To enable delegation, you must have sufficient administrative privileges in your Windows 2000 domain.

To enable a Web server to authenticate clients to other servers

  1. Click Start, point to Programs, point to Commerce Server 2000, and then click Commerce Server Manager.

  2. In the Commerce Server Manager console, expand Active Directory Users and Computers, right-click the domain node, and then click Find. Or, if you know which organizational unit the computer is in, in the console tree, right-click the organizational unit, and then click Find.(Or, you can navigate to the computer account you want to change without using the Find command, and then skip to step 9.)

  3. In the Find Users, Contacts, and Groups dialog box, in the Find box, select Computers from the drop-down list.

  4. On the Computers tab, in the Name box, type the name of the computer for which you are searching.

  5. In the In box, select the domain or organizational unit you want to search from the drop-down list, or click Browse to select a folder or domain in which you want to begin your search.

  6. (Optional) In the Owner box, type the name of the person whose computer is in the domain.

  7. (Optional) In the Any box, select the role of the computer from the list. You can search for all computers on the network, computers that are workstations and servers, or computers that are domain controllers.

  8. Click Find Now.

    The name of the computer you want appears in the list at the bottom of the Find Computers dialog box.

  9. Right-click the name of the computer, and then click Properties.

  10. In the <Computer Name> Properties dialog box, select the Trust computer for delegation option, and then click OK.


Installing Your Site

This section applies to a four-computer configuration containing a pair of Web servers using Network Load Balancing (NLB) and a pair of SQL Server cluster servers. For more information about the configuration, see Small Site Configuration.

For information about installing Commerce Server 2000 in a larger scale environment, see the Microsoft Commerce Server 2000 Resource Kit.

This section contains:

  • Example A: Installing on a Four-Computer Clustered Configuration. Describes how to install Commerce Server 2000 and unpack applications on a four-computer configuration.

  • Example B: Installing on a Three-Computer Non-clustered Configuration. Describes how to install Commerce Server 2000 on your Web server, and then deploy your Commerce Server databases onto a different computer.


Example A: Installing on a Four-Computer Clustered Configuration

This topic contains procedures describing how to install Commerce Server 2000 and unpack applications on a four-computer configuration consisting of:

  • Two Web servers in a Network Load Balancing (NLB) cluster. These servers also contain the Commerce Server administration tools.

  • Two SQL Servers configured as a single server cluster. These servers are referred to by their shared cluster name.

To view a figure showing this configuration, see Small Site Configuration.

Step 1: To install Commerce Server on the Web servers

Step 2: To install Commerce Server on the SQL Server cluster

Step 3: To unpack your Web site and applications

Step 1: To install Commerce Server on the Web servers

  1. Insert the Commerce Server 2000 compact disc into your disc drive, and run the Commerce Server 2000 Setup program. Accept the license agreement, type your customer information, and accept the default destination folder.

  2. In the Setup Type dialog box, select Custom, and then click Next.

  3. In the Custom Setup dialog box, select the Administration Tools, Commerce Server Site Packages, and Online Documentation options. Optionally, you can also select Predictor Service, if you plan to use it.

  4. Verify that the Analysis and Data Warehouse and Direct Mailer Service options are not selected (each check box should have an X in it, indicating that you are not selecting it). The following figure shows the Custom Setup dialog box.
    Custom Setup dialog box

    Click the illustration to enlarge or reduce.

  5. Click Next.

  6. In the Administration Database Configuration dialog box, do the following:
    Use this | To do this
    SQL Server Computer | Type the computer name for the database server.
    SQL Server Login Name | Type the SQL Server login for this computer. To create a new database, you must use a login that is a member of one of the following SQL Server roles: sysadmin or dbcreator. To avoid online analytical processing (OLAP) errors, you should avoid special characters (such as #, @, %, and ').
    SQL Server Login Password | Type the SQL Server password for this login name. To avoid OLAP errors, you should avoid special characters (such as #, @, %, and ').

    The Administration database is located on the SQL cluster, and in this step you are pointing this computer to that database. The following figure shows the Administration Database Configuration dialog box.

    Administration Database Configuration dialog box

    Click the illustration to enlarge or reduce.

  7. Click Next.

  8. In the Services Accounts dialog box, do the following:
    Use this | To do this
    Username | Type the Windows user name of the account under which the Commerce Server services will run on this computer.
    Password | Type the password of the Windows account.
    Domain | Type the domain of the Windows account.

    The following figure shows the Services Accounts dialog box.

    Services Accounts dialog box

    Click the illustration to enlarge or reduce.

  9. Click Next.

  10. In the Ready to Install dialog box, click Install.

    Commerce Server Setup installs the administration tools and site packages.

  11. To exit the Setup program, click Finish.

Step 2: To install Commerce Server on the SQL Server cluster

  1. Insert the Commerce Server 2000 compact disc into your disc drive, and run the Commerce Server 2000 Setup program. Accept the license agreement, type your customer information, and accept the default destination folder.

  2. In the Setup Type dialog box, select Custom, and then click Next.

  3. In the Custom Setup dialog box, select the Analysis and Data Warehouse option.

  4. Verify that you have cleared all the other options (each check box should have an X in it, indicating that you are not selecting it). The following figure shows the Custom Setup dialog box.
    Custom Setup, example A, server cluster

    Click the illustration to enlarge or reduce.

Note

  • In the initial release of Commerce Server 2000, Commerce Server Direct Mailer does not support installation to a SQL Server virtual cluster. Install Direct Mailer to a physical node of the SQL Server virtual cluster using the name of the physical computer, and use a SQL Server instance that is separate from the virtual instance. Check the Microsoft Commerce Server Web site for an updated solution.
  5. Click Next.

  6. In the Administration Database Configuration dialog box, do the following:
    Use this | To do this
    SQL Server Computer | Type the cluster name of this server cluster.
    SQL Server Login Name | Type the SQL Server login name that will be used to access the administration database. To avoid OLAP errors, you should avoid special characters (such as #, @, %, and ').
    SQL Server Login Password | Type the password for the SQL Server login. To avoid OLAP errors, you should avoid special characters (such as #, @, %, and ').

    The following figure shows the Administration Database Configuration dialog box.

    Administration Configuration dialog box

    Click the illustration to enlarge or reduce.

  7. Click Next.

  8. In the Services Accounts dialog box, do the following:
    Use this | To do this
    Username | Type the Windows user name of the account under which the Commerce Server services will run on this computer.
    Password | Type the password of the Windows account.
    Domain | Type the domain of the Windows account.

  9. Click Next.

  10. In the Ready to Install dialog box, click Install.

    Commerce Server Setup installs the Analysis and Data Warehouse features onto the SQL Server cluster.

  11. To exit the Setup program, click Finish.

Step 3: To unpack your Web site and applications

  1. On the Web server you want, click Start, point to Programs, point to Microsoft Commerce Server 2000, and then click Commerce Server Manager.

  2. Expand Commerce Server Manager, and then click Commerce Sites.

  3. Right-click Commerce Sites, point to New, and then click Unpack Site.

  4. In the Unpack Site From dialog box, navigate to the folder that contains the package file you want to unpack, select the package file, and then click Open.

    Commerce Server Site Packager is started.

  5. In the Unpack dialog box, select Custom unpack, and then click Next.

    The following figure shows the Unpack dialog box.

    Unpack dialog box

    Click the illustration to enlarge or reduce.

  6. In the Unpack Method dialog box, select Create a new site, and then click Next.

    The following figure shows the Unpack Method dialog box.

    Unpack Method dialog box

    Click the illustration to enlarge or reduce.

  7. In the Site Name dialog box, in the Site Name box, type the name for the site or accept the default name, and then click Next.

    The following figure shows the Site Name dialog box.

    Site Name dialog box

    Click the illustration to enlarge or reduce.

    Notes

    • To avoid unpacking errors, you should avoid special characters (such as #, @, %, and ') in your site name. By default, the database names of a site are prefixed with the site name, and special characters might not be recognized in SQL Server.

    • Do not specify a site name of more than 256 single-byte characters or 128 double-byte characters.

    • Do not name your site "Commerce." This is a reserved online analytical processsing (OLAP) database name. Naming your site "Commerce" could cause the overwriting of your OLAP database the next time you unpack a site.
  8. In the Select Resources dialog box, keep all of the resources in the list on the right, except Direct Mail. To remove Commerce Server Direct Mailer, select Direct Mail, and then click Remove. The following figure shows the Select Resources dialog box.
    Select Resources No DM dialog box

    Click the illustration to enlarge or reduce.

  9. If you are not installing the Predictor resource, select Predictor, and then click Remove.

    Note

    • You must install the CS Authentication and Profiles resources together. They do not work unless both are installed.
  10. In the Global Resource Pointers dialog box, click Next.

    You use the Global Resource Pointers dialog box to map to existing global resources or to create new ones. You also use this dialog box when you have already unpacked global resources onto your computer and you now want to unpack global resource pointers in a site that will use those global resources.

    The following figure shows a sample screen of the Global Resource Pointers dialog box.

    Global Resource Pointers No DM dialog box

    Click the illustration to enlarge or reduce.

    In the Database Connection Strings dialog box, Site Packager lists the databases it will use and the servers on which they exist. The following figure shows how the Database Connection Strings dialog box appears with default settings.

    Database Connection Strings 1, example A

    Click the illustration to enlarge or reduce.

    In the Database Connection Strings dialog box, click New Database. Because you are putting the databases on the database server cluster, you need to create the database.

  11. In the New Database dialog box, do the following:
    Use this | To do this
    SQL Server computer | Type the name of the SQL Server cluster.
    Database name | Type the name you want for the Data Warehouse database.
    SQL user name | To create a new database, you must use a login that is a member of one of the following SQL Server roles: sysadmin or dbcreator. To avoid OLAP errors, you should avoid special characters (such as #, @, %, and ').
    SQL password | Type the SQL Server login password. To avoid OLAP errors, you should avoid special characters (such as #, @, %, and ').

    The following figure shows the New Database dialog box.

    New Database dialog box

    Click the illustration to enlarge or reduce.

  12. Click Create database to create the new database.

    The other data stores (such as catalogs and transactions) will be stored in another database on the database server cluster. You will also need to create these databases.

    The databases are created on the database server cluster.

  13. When you are returned to the Database Connection Strings dialog box, select Global Data Warehouse, and then click Modify.

  14. In the Data Link Properties dialog box, on the Connection tab, in the Select or enter a server name box, type the name of the database server cluster. In the Select the database on the server box, select the name you assigned to the Data Warehouse database that you created, and then click OK.

    Note

    • Make sure the Allow saving password box is selected. If it is not selected, Site Packager will not create the database.

    The following figure shows the Data Link Properties dialog box.

    DataLink Properties dialog box, DW

    Click the illustration to enlarge or reduce.

  15. When you are returned to the Database Connection Strings dialog box, select all of the other databases, and then click Modify.

  16. In the Data Link Properties dialog box, on the Connection tab, in the Select or enter a server name box, type the name of the database server cluster. In the Select the database on the server box, select the name you assigned to the other database that you created, and then click OK.

    Note

    • Make sure the Allow saving password box is selected. If it is not selected, Site Packager will not create the database.

    The following figure shows how the Database Connection Strings dialog box appears after you modify it.

    Database Connection Strings 2, example A

    Click the illustration to enlarge or reduce.

  17. Click Next.

  18. In the Select Applications dialog box, verify that the applications you want to unpack are selected, and then click Next. The following figure shows the Select Applications dialog box.
    Select Applications dialog box

    Click the illustration to enlarge or reduce.

  19. In the Select IIS Web Sites and Virtual Directories dialog box, verify that the IIS Web site and IIS path for each application is correct. To change the IIS Web site for an application, select the application in the list and choose the IIS Web site from the drop-down list.

    To change the name of the virtual directory for an application, select the application in the list. In the IIS virtual directory box, type the name you want.

    Notes

    • To avoid IIS errors, you should not include special characters (such as #, @, %, and ') in your IIS virtual directory names.

    • Site Packager does not support unpacking a site on a remote computer.

    • Site Packager will unpack each application under the home directory of its corresponding IIS Web site. Within the home directory, Site Packager creates a subfolder using the IIS virtual directory name of the application.

    The following figure shows the Select IIS Web Sites and Virtual Directories dialog box.

    Select IIS Web Sites and Virtual Directories dialog box

    Click the illustration to enlarge or reduce.

  20. Click Next.

  21. If the Data Warehouse dialog box appears, do the following:
    Use this | To do this
    Name | Type the name you want to give to the global Data Warehouse resource.
    Server | Type the name of the SQL Analysis (OLAP) computer.
    Database | Type the name of the Analysis (OLAP) database to use.

  22. Click Next.

  23. If the first Profiling System dialog box appears, do the following:
    Use this | To do this
    Profile Schema Definition | Specify the profile schema definition to import.
    Site Terms Definition | Specify the site terms definition to import.
    Expression Definition | Specify the expression definition to import.

  24. Click Next.

  25. If the second Profiling System dialog box appears, do the following:
    Use this | To do this
    Profiling System Connection String | Specify the files to import into the OLEDB data store. Click Modify to specify a different database.
    Schema definition scripts (*.sql, *.vbs) | Specify the schema definition scripts to import.
    Data population scripts (*.sql) | Specify the data population scripts to import.

  26. Click Next.

  27. In the Unpacking is complete! dialog box, review the list of SQL Server databases and IIS applications that were created. To review the list of events in the Site Packager log file, click View Log File.

  28. To close Site Packager, click Finish.

Notes

  • Immediately after you install your site, and any time you make major configuration changes to your Commerce Server deployment, you may want to back up your Administration database with a different name. You can use this backup to roll back any changes that are made later, if necessary.

  • Do not run more than one instance of Site Packager on a computer at a time.

See Also

Using Scripts with Site Packager


Example B: Installing on a Three-Computer Non-clustered Configuration

You use Commerce Server Site Packager to deploy site resources from any Commerce Server 2000 computer into the Administration database. If you have three computers, for example, you could install Commerce Server on your Web server, and then deploy your Commerce Server databases onto a different computer. You could configure them as follows:

  • Computer A. Used for the Administration database and administration tools. You will use this computer to manage Commerce Server.

  • Computer B. Used for the Data Warehouse and other databases.

  • Computer C. Used as the Web server, and contains the Active Server Pages (ASP) for your application.

These instructions assume you have installed Microsoft Windows 2000 Server on all three computers, and Microsoft SQL Server 7.0 or SQL Server 2000 on Computers A and B. If you have not yet done so, see Installing Commerce Server for instructions.

Step 1: Install Commerce Server on Computer A

Step 2: Install Commerce Server on Computer B, selecting only the Data Warehouse

Step 3: Install a Commerce Server Web server on Computer C

Step 4: Unpack your site from Computer A

Step 5: Add the Commerce Server Web server (Computer C) to your application

Step 1: Install Commerce Server on Computer A

  1. Insert the Commerce Server 2000 compact disc into your disc drive, and run the Commerce Server 2000 Setup program. Accept the license agreement, type your customer information, and accept the default destination folder.

  2. In the Setup Type dialog box, select Custom, then click Next.

  3. In the Custom Setup dialog box, under the Runtime Objects folder, verify that the Analysis and Data Warehouse option is not selected (the checkbox should have an X in it, indicating that you are not selecting it). Select the other features you want to install, such as Predictor. The following figure shows the Custom Setup dialog box.
    Custom Setup dialog box

    Click the illustration to enlarge or reduce.

  4. In the Administration Database Configuration dialog box, do the following:
    Use this | To do this
    SQL Server Computer | Type the computer name for the database server (Computer B).
    SQL Server Login Name | Type the SQL Server login for this computer. To create a new database, you must use a login that is a member of one of the following SQL Server roles: sysadmin or dbcreator. To avoid online analytical processing (OLAP) errors, you should avoid special characters (such as #, @, %, and ').
    SQL Server Login Password | Type the SQL Server password for this computer. To avoid OLAP errors, you should avoid special characters (such as #, @, %, and ').

  5. Click Next.

  6. In the Services Accounts dialog box, do the following:
    Use this | To do this
    Username | Type the Windows user name of the account under which the Commerce Server services will run on this computer.
    Password | Type the password of the Windows account.
    Domain | Type the domain of the Windows account.

  7. Click Next.

  8. In the Ready to Install dialog box, click Install.

    Commerce Server Setup installs the features you specified on Computer A, including the administration tools. You can use this computer to manage your Commerce Server installation.

  9. To exit the Setup program, click Finish.

Step 2: Install Commerce Server on Computer B, selecting only the Data Warehouse

  1. Insert the Commerce Server 2000 compact disc into your disc drive, and run the Commerce Server 2000 Setup program. Accept the license agreement, type your customer information, and accept the default destination folder.

  2. In the Setup Type dialog box, select Custom, and then click Next.

  3. In the Custom Setup dialog box, under the Runtime Objects folder, select the Analysis and Data Warehouse option, and then clear the other options, except for Direct Mailer, if you plan to use it. Click Next. The following figure shows the Custom Setup dialog box.
    Custom Setup dialog box

    Click the illustration to enlarge or reduce.

  4. In the Administration Database Configuration dialog box, do the following:
    Use this | To do this
    SQL Server Computer | Type the computer name for the database server (Computer B).
    SQL Server Login Name | Type the SQL Server login for this computer. To create a new database, you must use a login that is a member of one of the following SQL Server roles: sysadmin or dbcreator. To avoid online analytical processing (OLAP) errors, you should avoid special characters (such as #, @, %, and ').
    SQL Server Login Password | Type the SQL Server password for this computer. To avoid OLAP errors, you should avoid special characters (such as #, @, %, and ').

  5. If you are installing Direct Mailer, in the Direct Mailer Database Configuration dialog box, do the following:
    Use this | To do this
    SQL Server Computer | Accept the default (Computer B).
    SQL Server Login Name | Type the SQL Server login for this computer. To create a new database, you must use a login that is a member of one of the following SQL Server roles: sysadmin or dbcreator. To avoid OLAP errors, you should avoid special characters (such as #, @, %, and ').
    SQL Server Login Password | Type the SQL server login password for this server. To avoid OLAP errors, you should avoid special characters (such as #, @, %, and ').

  6. In the Services Accounts dialog box, type the Windows user name and password of the account under which the Commerce Server services will run on this computer, and then click Next.

  7. In the Ready to Install dialog box, click Install.

    Commerce Server Setup installs the Analysis and Data Warehouse features onto Computer B.

  8. To exit the Setup program, click Finish.

Step 3: Install a Commerce Server Web server on Computer C

  1. Insert the Commerce Server 2000 compact disc into your disc drive, and run the Commerce Server 2000 Setup program using the Web Server installation option. Accept the license agreement, type your customer information, and accept the default destination folder.

  2. Click Next.

  3. In the Administration Database Configuration dialog box, do the following:
    Use this | To do this
    SQL Server Computer | Type the computer name for the database server (Computer B).
    SQL Server Login Name | Type the SQL Server login for this computer. To create a new database, you must use a login that is a member of one of the following SQL Server roles: sysadmin or dbcreator. To avoid online analytical processing (OLAP) errors, you should avoid special characters (such as #, @, %, and ').
    SQL Server Login Password | Type the SQL Server password for this computer. To avoid OLAP errors, you should avoid special characters (such as #, @, %, and ').

  4. Click Next.

  5. In the Services Accounts dialog box, type the Windows user name and password of the user granted access to Commerce Server services on this computer. Then click Next.

  6. In the Ready to Install dialog box, click Install.

    Commerce Server Setup installs the Runtime Objects and Commerce Server Site Packages onto Computer C.

  7. To exit the Setup program, click Finish.

Step 4: Unpack your site from Computer A

  1. On Computer A, click Start, point to Programs, point to Microsoft Commerce Server 2000, and then click Commerce Server Manager.

  2. Expand Commerce Server Manager, and then click Commerce Sites.

  3. Right-click Commerce Sites, point to New, and then click Unpack Site.

  4. In the Unpack Site From dialog box, navigate to the folder that contains the package file you want to unpack, select the package file, and then click Open.

    Commerce Server Site Packager is started.

  5. In the Unpack dialog box, select Custom unpack, and then click Next. The following figure shows the Unpack dialog box.
    Unpack dialog box

    Click the illustration to enlarge or reduce.

  6. In the Unpack Method dialog box, select Create a new site, and then click Next. The following figure shows the Unpack Method dialog box.
    Unpack Method dialog box

    Click the illustration to enlarge or reduce.

  7. In the Site Name box, the default name for the site appears. Change the name as needed, and then click Next.

    Notes

    • To avoid unpacking errors, you should avoid special characters (such as #, @, %, and ') in your site name. By default, the database names of the site are prefixed with the site name, and special characters might not be recognized in SQL Server.

    • Do not specify a site name of more than 256 single-byte characters or 128 double-byte characters.

    • Do not name your site "Commerce." This is a reserved OLAP database name. Naming your site "Commerce" could cause the deletion of your OLAP database the next time you unpack a site.
  8. In the Select Resources dialog box, select all of the resources. If you are not installing Commerce Server Direct Mailer, select Direct Mailer, and then click Remove. If you are not installing the Predictor resource, select Predictor, and then click Remove. The following figure shows the Select Resources dialog box.
    Select Resources All dialog box

    Click the illustration to enlarge or reduce.

    Note

    • You must install the CS Authentication and Profiles resources together. They do not work unless both are installed.
  9. In the Global Resource Pointers dialog box, click Next.

    You use this screen to map to existing global resources or to create new ones. You also use this dialog box when you have already unpacked global resources onto your computer and you now want to unpack global resource pointers in a site that will use those global resources.

    In the Database Connection Strings dialog box, Site Packager lists the databases it will use and the servers on which they exist.

    Because you are putting the Data Warehouse on a different computer, you need to create the database. To create a database called Blank_dw for the Data Warehouse on Computer B, click New Database.

  10. In the New Database dialog box, do the following:
    Use this | To do this
    SQL Server computer | Type the name of the SQL Server computer (Computer B).
    Database name | Type Blank_dw or for the Data Warehouse database.
    SQL user name | To create a new database, you must use a login that is a member of one of the following SQL Server roles: sysadmin or dbcreator. To avoid OLAP errors, you should avoid special characters (such as #, @, %, and ').
    SQL password | Type the SQL Server login password. To avoid OLAP errors, you should avoid special characters (such as #, @, %, and ').

    The following figure shows the New Database dialog box.

    New Database dialog box, example B, 1

    Click the illustration to enlarge or reduce.

  11. Click Create Database. The Blank_dw database is created on Computer B.

  12. When you are returned to the Database Connection Strings dialog box, click New Database.

    You are also putting the other Commerce Server databases on Computer B.

  13. To create a separate database called Blank_commerce to group these databases, repeat Step 11 and type Blank_commerce in the Database name box instead. The following figure shows the New Database dialog box with the Blank_commerce database.
    New Database dialog box, example B, 2

    Click the illustration to enlarge or reduce.

  14. Click Create Database. The Blank_commerce database is created on Computer B.

  15. When you are returned to the Database Connection Strings dialog box, select Data Warehouse, and then click Modify.

  16. In the Data Link Properties dialog box, in the Select or enter a server name box, type the name of Computer B. In the Select the database on the server box , select the name (Blank_dw) you assigned to the Data Warehouse that you created on Computer B, and then click OK.

    Note

    • Make sure the Allow saving password box is selected. If it is not selected, Site Packager will not create the database.

    The following figure shows the Data Link Properties dialog box.

    Datalink Properties dialog box, blank_dw

    Click the illustration to enlarge or reduce.

  17. When you are returned to the Database Connection Strings dialog box, select all of the other databases (besides Data Warehouse), and then click Modify.

  18. In the Data Link Properties dialog box, in the Select or enter a server name box, type the name of Computer B. In the Select the database on the server box, select the name (blank_commerce) you assigned to the database, and then click OK.

    Note

    • Make sure the Allow saving password box is selected. If it is not selected, Site Packager will not create the database.

    The following figure shows how the Database Connection Strings dialog box appears after you modify it.

    Database Connection Strings dialog box, example B

    Click the illustration to enlarge or reduce.

  19. Click Next.

  20. In the Select Applications dialog box, verify that the applications you want to unpack are selected, and then click Next. The following figure shows the Select Applications dialog box.
    Select Applications dialog box

    Click the illustration to enlarge or reduce.

  21. In the Select IIS Web Sites and Virtual Directories dialog box, verify that the Internet Information Services (IIS) 5.0 Web site and IIS path for each application is correct. To change the IIS Web site for an application, select the application in the list and choose the IIS Web site from the drop-down list.

    To change the name of the virtual directory for an application, select the application in the list. In the IIS virtual directory box, type the name you want.

    Notes

    • To avoid IIS errors, you should not include special characters (such as #, @, %, and ') in your IIS virtual directory names.

    • Site Packager does not support unpacking a site on a remote computer.

    • Site Packager will unpack each application under the home directory of its corresponding IIS Web site. Within the home directory, Site Packager creates a subfolder using the IIS virtual directory name of the application.

    The following figure shows the Select IIS Web Sites and Virtual Directories dialog box.

    Select IIS Web Sites and Virtual Directories dialog box

    Click the illustration to enlarge or reduce.

  22. In the Data Warehouse dialog box, do the following:
    Use this | To do this
    Name | Type the name you want to give to the global Data Warehouse resource.
    Server | Type the name of the SQL Analysis (OLAP) computer.
    Database | Type the name of the Analysis (OLAP) database to use.
  23. Click Next.

  24. If the first Profiling System dialog box appears, do the following:
    Use this | To do this
    Profile Schema Definition | Specify the profile schema definition to import.
    Site Terms Definition | Specify the site terms definition to import.
    Expression Definition | Specify the expression definition to import.

  25. Click Next.

  26. If the second Profiling System dialog box appears, do the following:
    Use this | To do this
    Profiling System Connection String | Specify the files to import into the OLEDB data store. Click Modify to specify a different database.
    Schema definition scripts (*.sql, *.vbs) | Specify the schema definition scripts to import.
    Data population scripts (*.sql) | Specify the data population scripts to import.

  27. Click Next.

  28. In the Unpacking is complete! dialog box, review the list of SQL Server databases and IIS applications that were created. To review the list of events in the Site Packager log file, click View Log File.

  29. To close Site Packager, click Finish.

Step 5: Add the Commerce Server Web Server (Computer C) to your application

  1. On Computer C, the Web server that you want to add to the application, expand Commerce Server Manager, expand Commerce Sites, and then click the site you want to administer.

  2. Expand Applications, and then click the name of the application to which you want to add the Web server. Right-click that name, point to New, and then click Add Web server.

    The Open dialog box appears containing a list of the existing package files.

  3. In the Open dialog box, select the package file that contains the Web server files you want to add to the Web server, and then click Open.

    Commerce Server Site Packager is started.

  4. The Select IIS Web Sites and Virtual Directories dialog box displays the name of the IIS Web site where the application will be installed and the IIS virtual directory for each Commerce application. This information is read-only; the IIS Web site and virtual directory must be the same across all Web servers in the application. Click Next.

    Site Packager adds your files to the Web server, and then adds the Commerce Web server object to the selected application. When you open Commerce Server Manager, the Commerce Web server object appears under the application.

    Note

    • Site Packager does not support unpacking a Web server on a remote computer.
  5. In the Unpacking is complete! dialog box, review the log file, and then click Finish.

After you add a Web server to an application, the Commerce Web server object appears under the application node in Commerce Server Manager. The Commerce Web server object contains properties required by the Data Warehouse resource in order to import log files: server name, Internet Protocol (IP) address, log file path, and log file period. These properties are automatically populated from IIS when you add a Commerce Web server object to an application. For instructions about configuring these Web server properties, see Configuring a Web Server.

Notes

  • Immediately after you install your site, and any time you make major configuration changes to your Commerce Server deployment, you may want to back up your Administration database with a different name. You can use this backup to roll back any changes that are made later.

  • Do not run more than one instance of Site Packager on a computer at a time.

See Also

Configuring a Web Server


Securing Your Site

After you finish unpacking your site, you need to secure your site to prevent unauthorized access to your Commerce Server and application files.

This section contains:

  • Limiting Access to Your Site. Explains how to use NTFS permissions to limit access to site files.

  • Limiting Access to Commerce Server Services. Explains how to grant access to Commerce Server services for specific Windows accounts.

  • Limiting Access to Business Desk Modules. Explains how to prevent specific users from accessing particular Commerce Server Business Desk modules.

  • Limiting Access to the Administration Database. Explains how to limit access to the Administration database using the Windows Registry Editor.

  • Providing Access to Commerce Server Resources. Explains how to provide access to the SQL Server database that corresponds to Commerce Server resources.

  • Securing Log Files. Describes how to move your log files from your Web servers to a more secure location.

  • Enabling Only the Most Secure Version of Integrated Windows Authentication. Describes how you can configure your Web server to use the strongest version of Integrated Windows authentication.

  • Using the sa SQL Administrative Account. Explains recommendations for not using the "sa" login that SQL Server creates by default.

  • Differentiating Access to Resources. Explains access privileges for different Commerce site users.

  • Changing the Data Warehouse Password. Explains how to change the Data Warehouse password.

See Also

Planning for Security

Commerce Server Security Checklist


Limiting Access to Your Site

Commerce Server Site Packager does not affect Windows access control lists (ACLs). After you unpack a site, you should lock down some of the files and folders on your Commerce Server site by changing permissions on them. You can also limit access to files by setting Web server permissions. For more information, see How Web Server Permissions Are Set.

This topic describes how to use NTFS permissions to limit access to site files. When you limit access to the files and folders on your site, you should consider the following:

  • A Business Desk user must have access to the log file in the Profiles folder before saving changes to a profile definition. A business manager must also have access to the log file in the Profiles folder to be able to save any changes made in the Profile Designer module. The IIS Web server permissions have read access turned off by default when using the Commerce Server Solution Sites, but you can increase security by also denying read access on this folder's NTFS permissions.

  • If you use pipeline logging to debug a pipeline, be aware that sensitive information appears in clear text in the log files. Make sure you secure against read access the Pipelines\Logfiles folder, which contains these pipeline log files.

  • You should use IP address access restrictions to limit permissions on Bdrefresh.asp and RefreshApp.asp so that unauthorized users cannot run these scripts. By default, Bdrefresh.asp and Refreshapp.asp are set to anonymous access, which is required in order for Business Desk users to publish changes to the Web site. To secure these files, grant access to specific Business Desk users by using IP address access restrictions in Internet Information Services (IIS) 5.0. For instructions, see To set IP address access restrictions.

    The Bdrefresh.asp script clears the Business Desk cache. The RefreshApp.asp script clears the Profiles cache. Clearing either of these caches repeatedly could lead to a denial of service for users. These files are located in the root folder of an unpacked Solution Site.

    There are other similar files included with the Commerce Server Solution Sites. For information about other files to protect, see the Solution Sites Web site.

  • If, when you unpack a non-Business Desk application, you use an unpack.vbs script file that you created, make sure you delete or secure the file immediately after unpacking. The file exists in the root directory, and can be accessed by anonymous users. Unauthorized use of this script could lead to denial of service or the breaking of site settings. This file does need to be present, however, if you repackage the site.

    In the Commerce Server Solution Sites, the unpack.vbs file is secured by default.

  • You can set file and folder permissions only on drives formatted to use NTFS.

  • To change permissions, you must be the system administrator or have been granted permission to do so by the system administrator.

  • Groups or users given Full Control for a folder can delete files and subfolders within that folder regardless of the permissions protecting the files and subfolders.

  • If the check boxes under Permissions are shaded, or if the Remove button is unavailable, then the file or folder has inherited permissions from the parent folder.

To set, view, change, or remove file and folder permissions

  1. Click Start, point to Programs, point to Accessories, and then click Windows Explorer.

  2. In the Windows Explorer window, navigate to the file or folder you want, right-click the file or folder, click Properties, and then click the Security tab.

  3. On the Security tab, do one of the following:
    • To change permissions from an existing group or user, in the Name box, select the name of the group or user. In the Permissions box, select Allow or Deny for each permission you want to change.

    • To remove the group or user from the permissions list, in the Name box, select the group or user, and then click Remove.

    • To set up permissions for a new group or user, click Add. In the Select Users, Computers, or Groups dialog box, type the name of the group or user you want to set permissions for using the format domain_name\user_name, and then click OK.
  4. To close the Properties dialog box, click OK.

To set IP address access restrictions

  1. Click Start, point to Programs, point to Administrative Tools, and then click Internet Services Manager.

  2. In Internet Information Services, navigate to Bdrefresh.asp file.

  3. Right-click Bdrefresh.asp, and then click Properties.

  4. In the File Security tab, in the IP address and domain name restrictions section, click Edit.

  5. In the IP Address and Domain Name Restrictions dialog box, click Add to add the computers you want to grant access to Bdresfresh.asp, click Denied Access, and then click OK.

  6. Navigate to Refreshapp.asp, right-click Refreshapp.asp, and then click Properties.

  7. Repeat steps 4 and 5 to secure Refreshapp.asp.


Limiting Access to Commerce Server Services

During Commerce Server Setup, in the Services Account dialog box, you specify the Windows user name and password for the following Commerce Server services: List Manager, Direct Mailer, and Predictor. Setup automatically grants these Windows accounts the Log On as a Service right. The following figure shows the Services Account dialog box.

Services Accounts dialog box

Click the illustration to enlarge or reduce.

In the same dialog box, you specify an account under which Event Logging will be performed. This last account is used in the Commerce Event Logging COM+ package that is created by Setup.

Make sure you specify the proper account for each service. For List Manager, your Commerce Server Business Desk users must be able to read folders from which they import lists and write to folders onto which they export lists. The List Manager service account must have appropriate NTFS permissions on the folders from which users will import and export lists.

Also, Setup does not permit you to set up these services to use the Local System account. Although it is possible to do this manually after Setup, it is not a good idea because doing so might give the services more permissions than they need.


Limiting Access to Business Desk Modules

You can prevent specific users from accessing particular Commerce Server Business Desk modules. You do this by setting access control entries (ACEs) on Business Desk ASP files. Each Business Desk module has a main ASP file that is checked for ACEs before it is added to the Business Desk navigation pane. If the logged-in user running Business Desk does not have Read permission on the main ASP file for that module, the module will not be exposed in the navigation pane for that user.

To limit access to Business Desk modules

  1. In Windows Explorer, navigate to the folder that contains your Business Desk application files.

    This is the folder that hosts your IIS Web site. By default, this folder resides in the Inetpub\wwwroot folder.

  2. Click the folder that contains the module you want to limit access to.

  3. Using the information in the following table, right-click the name of the files that correspond to the module you want to limit access to. Then click Properties.

  4. Click the Security tab.

  5. On the Security tab, you can manage the ACEs contained in the access control list (ACL) of that file.

    The following table shows the files on which you can set ACEs for each Business Desk module.

    To control access to this category/module | Set an ACE on this ASP file
    Analysis/Reports | Analysis\Analysis_reports.asp
    Analysis/Completed Reports | Analysis\Analysis_report_viewer.asp
    Analysis/Segment Viewer | Segviewer\Modellist.asp
    Campaigns/Campaign Manager | Marketing\Cmanager.asp
    Campaigns/List Manager | Marketing\Listmanager.asp
    Campaigns/Campaign Expressions | Marketing\Targetexpr.asp
    Campaigns/Target Group | Marketing\Target_group.asp
    Campaigns/Reference Tables | Marketing\Reftable.asp
    Campaigns/Publish Campaigns | Productionrefresh\refresh.asp
    Catalogs/Catalog Designer | Catalogs\Designer\List_categorydefinitions.asp
    Catalogs/Catalog Editor | Catalogs\Editor\List_catalogs.asp
    Catalogs/Catalog Sets | Catalogsets\Catalogsets_list.asp
    Orders/Basket Manager | Orders\Basket_list.asp
    Orders/Data Codes | Application\Datacodes_list.asp
    Orders/Order Status | Orders\Orderstatus_list.asp
    Orders/Publish Transactions | Productionrefresh\refresh.asp
    Orders/Shipping Methods | Shipping\Shipping_list.asp
    Orders/Tax Rates | Tax\Regionaltax.asp
    Users/Users | Users\Registered.asp
    Users/Organizations | Organizations\Orgs.asp
    Users/Profile Designer | Profiles\Profileselector.asp
    Users/Site Terms Editor | Profiles\Profileeditor.asp
    Users/Publish Profiles | Profiles\Refreshprofilesvcall.asp

Notes

  • If an individual user and the Authenticated Users group have access to a Commerce Server Business Desk module, and you take permission away from the individual user, restart the client computer in order to redraw the navigation bar, so the modules the user has permissions to use are refreshed in the navigation bar.

  • If you include an ACE for the Administrator account, you must also grant permissions to the Everyone group. The exact set of permissions is not significant, but the Everyone group must be present in the list of users and groups. If the Everyone group does not have permissions to a Business Desk module, an administrator will not be able to access that module.

  • If you secure one of the following modules, all three of them are secured by default: Publish Profiles, Publish Campaigns, and Publish Transactions.


Limiting Access to the Administration Database

It is important to lock down the server that hosts the Administration database for your site. When you run Commerce Server Setup, you give users of that computer full control of the Administration database. Although the SQL password for the Administration database login is encrypted in the Windows registry, it is possible for users to gain access to it by using a script that accesses one of these programming objects: SiteConfigReadOnly, SiteConfig, or GlobalConfig. Make sure users cannot gain access to the computer or run scripts on it after you complete Setup. Disable the Guest account and disallow access to everyone without administrative privileges.

You can restrict usage of the SiteConfig and GlobalConfig objects by modifying the access control lists (ACLs) on the registry keys for these object classes. To restrict access to these objects, change the permissions on these objects through the Windows Registry Editor.

To change the permissions on an administrative object

  1. Click Start, and then click Run.

  2. In the Run dialog box, in the Open box, type regedt32.

  3. Click HKEY_LOCAL_MACHINE.

  4. On the View menu, click Find Key.

  5. In the Find dialog box, in the Find what box, type the appropriate key, as shown in the following table.
    To find the key for this object | Type this
    SiteConfig | 31B031AE-8877-4973-BC58-FEE0EF8CE07B
    GlobalConfig | CB438FDD-81EC-45FF-9DBB-9F9FBBF717AF
  6. Clear the Match whole word only check box, and then click Find Next.

    A list of keys appears. The key you requested will be marked as selected with a thin black border. You might have to scroll down the list to see the selected key.

  7. Click the node for the key for which you searched.

  8. In the Security menu, click Permissions.

  9. In the Permissions dialog box, set the appropriate permissions, based on your needs. Limit Read permissions to accounts that need to modify the Administration database.

Note

  • The SiteConfigReadOnly object must be accessible by all user accounts that will access Commerce Server applications. If you want to allow anonymous access, the object must be available to the anonymous account, which is named IUSR_<computername>. The key for the SiteConfigReadOnly object is D1AA04A4-B00D-4D30-88AA-E3070DAE8040.


Providing Access to Commerce Server Resources

For Commerce Server Business Desk users and administrators to access resources, such as the Product Catalog, they must have sufficient permissions to access the SQL Server database that corresponds to the resource. A user should have a SQL Server login name that is linked to a SQL Server user that has the db_owner database role. Or, to provide more granularity, you can assign the user to the db_ddladmin, db_datareader, and db_datawriter roles.

To check the SQL Server roles assigned to a login name for a resource

  1. Click Start, point to Programs, point to Microsoft SQL Server, and then click Enterprise Manager.

  2. In SQL Server Enterprise Manager, expand Microsoft SQL Servers, expand SQL Server Group, and expand the name of the database server containing the resource database you want.

  3. Expand Databases, expand the database corresponding to the resource you want, and then click Users.

  4. In the right pane, double-click the login name.

  5. In the Database User Properties dialog box, make sure the db_owner box is selected, and then click OK.

    Or, make sure the db_ddladmin, db_datareader, and db_datawriter boxes are selected, and then click OK.

Note

  • You can also change these settings by modifying login properties in SQL Server Enterprise Manager. Expand the node for the database server you want, expand Security, and then click Logins to see the list of login names. Double-click a name to modify its database roles.

If the login name you specified does not appear in the list of database users, you can add a new SQL Server user.

To add a new SQL Server user for a resource database

  1. Click Start, point to Programs, point to Microsoft SQL Server, and then click Enterprise Manager.

  2. In SQL Server Enterprise Manager, expand Microsoft SQL Servers, expand SQL Server Group, and expand the name of the database server containing the resource database you want.

  3. Expand Databases, expand the database corresponding to the resource you want, right-click Users, and then click New Database User.

  4. In the Database User Properties dialog box, do the following:
    Use this | To do this
    Login name | Select or type the login name used to access the database.
    User name | Type the SQL Server user name that you want to assign to this login name. The user name assigns the new user permissions to objects in the database.
    Database role membership | Select which roles the new user should have. Select the db_owner box to give the new user access to the resource. Or, select the db_ddladmin, db_datareader, and db_datawriter boxes.

  5. Click OK.


Securing Log Files

It is a good idea to move your log files from your Web servers to a more secure location. When you move these files, do it in a secure way. One way to achieve security is to use separate network lines that run directly from your staging environment to your production environment. This separate line is a good way to update content, and to move log files to secure servers. Another way to safely move log files is through Secure Sockets Layer (SSL) over HTTP or File Transfer Protocol (FTP).

If you use pipeline logging to debug a pipeline, be aware that sensitive information may appear in clear text in the log files. Make sure you secure the folder that contains these pipeline log files (by default, the \Pipeline\Logfiles folder in the application).


Enabling Only the Most Secure Version of Integrated Windows Authentication

If you use Integrated Windows authentication and the client computers connecting to your Web server use Microsoft Windows 2000, or Microsoft Windows NT 4.0 Service Pack 3 or later, you can configure your Web server to use only the strongest version of Integrated Windows authentication, NTLMv2.

You can set a Windows policy to specify only to use the latest version of NTLM. In the Local Security Policy of your Web servers, set the LAN Manger Authentication Level policy to Send NTLMv2 response only\refuse LM & NTLM to use the most secure setting.


Using the sa SQL Administrative Login

It is recommended that you do not use the "sa" login that SQL Server creates by default. You should specify a different administrative login name for your database servers. If you do use the 'sa' login, do not use a blank password for it. Doing so increases security risks for your site.


Differentiating Access to Resources

Commerce Server resources have single connection strings to each database. Therefore, you cannot specify different access privileges for different Commerce site users.


Changing the Data Warehouse Password

If you change the password for your SQL Server computer, you must also change the password in the Commerce Server Data Warehouse and the connection strings for all resources.

To change the Data Warehouse password

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2000, and then click Commerce Server Manager.

  2. In the Commerce Server Manager console, expand Global Resources, right-click the Data Warehouse for which you want to change the password, and then click Properties.

  3. In the Data Warehouse Properties dialog box, click the Connection tab.

  4. On the Connection tab, in the Password box, type the new password, and then click OK.

See Also

Configuring a Global Resource


Backing Up Your Site

After you deploy and configure your site, you should back up all the files on your site so that you can restore it in case of server failure. If your site is small, the easiest way to back up your site is to repackage it using Commerce Server Site Packager. The new package will save many of the configuration settings specific to your current site. Site Packager does not package properties that are specific to the computer you are on. For example, Web server properties and some application properties that are set in Commerce Server Manager are not packaged. For a list of data that is packaged for each resource, see Site Packager Reference Information.

Remember to repackage your site each time you change its configuration. For information about how to package a site, see Packaging a Site.

If your site is large, creating a package file for it may not be practical. In this case, you need to back up each component (applications and databases, for example) using an appropriate method for that component. The following table lists appropriate backup tools for each Commerce Server component type.

To back up this component type | Use this
Application files and Windows registry | Windows Backup or Microsoft Application Center 2000
Databases | SQL Server Backup
Domain information | Active Directory replication between multiple domain controllers

See Also

Backing Up and Restoring Commerce Server

Backing Up and Restoring a SQL Database


Updating Your Site

Deployment is an ongoing process. After your site is operational, you will want to update the content and configuration of your site to address changing needs. This section contains basic information about updating your site. For more detailed information, see the Commerce Server 2000 Resource Kit.

This section contains:

  • Using Your Test Environment for Updates. Explains how to use your test environment before update your production servers.

  • Adding Web Servers. Explains how to install a Commerce Web server.

  • Adding Web Servers Without Site Packager. Explains how to install a Commerce Web server without using Site Packager.

  • Updating Site Content. Explains how to update Commerce Server components.

  • Using SQL Server to Replicate Databases. Explains how to use SQL Server to replicate your Commerce Server databases.

  • Changing the Names of Servers. Explains how to change the names of your servers.


Using Your Test Environment for Updates

Before updating the servers in your production environment, always deploy and test your updates in a separate staging/test environment. This will help ensure that you deploy a fully tested and updated site efficiently.

For example, suppose you update your product catalog. Before you modify the catalogs in your production environment, update the ones in your staging environment first. Test the updated catalogs there. Once you are satisfied that these updates are fully functional, use SQL Server to replicate the updates to your production servers.

See Also

Updating Site Content

Using SQL Server to Replicate Databases


Adding Web Servers

To add Web servers to an existing site, you need to run Commerce Server Setup and Commerce Server Site Packager on the new Web server. Make sure you have installed the prerequisite hardware and software first.

To install a Commerce Server Web server

  1. Insert the Commerce Server 2000 compact disc into your disc drive, and run the Commerce Server 2000 Setup program using the Web Server installation option.

  2. Click Next.

  3. In the Administration Database Configuration dialog box, do the following:
    Use this | To do this
    SQL Server Computer | Type the name of this server.
    SQL Server Login Name | Type the SQL Server login name that will be used to access the Administration database. To avoid online analytical processing (OLAP) errors, you should avoid special characters (such as #, @, %, and ').
    SQL Server Login Password | Type the password for the SQL Server login. To avoid OLAP errors, you should avoid special characters (such as #, @, %, and ').

  4. Click Next.

  5. In the Services Accounts dialog box, do the following:
    Use this | To do this
    Username | Type the Windows user name of the account under which the Commerce Server services will run on this computer.
    Password | Type the password of the Windows account.
    Domain | Type the domain of the Windows account.

  6. Click Next.

  7. In the Ready to Install dialog box, click Install.

    Commerce Server Setup installs the Runtime Objects and Commerce Server Site Packages onto this server.

  8. To exit the Setup program, click Finish.

Now you must unpack the applications you want onto the new Web server. Use the following procedure after you have installed Commerce Server on a new Web server.

To add a new Web server to an application

  1. On the physical Web server that you want to add to the application, expand Commerce Server Manager, expand Commerce Sites, and then expand the site you want to administer.

  2. Expand Applications, right-click the name of the application to which you want to add the Web server, point to New, and then click Add Web server.

  3. In the Add Web Server From dialog box, select the package file that contains the Web server files you want to add to the Web server, and then click Open.

    Commerce Server Site Packager starts.

  4. The Select IIS Web Sites and Virtual Directories dialog box displays the name of the Internet Information Services (IIS) 5.0 Web site where the application will be installed and the IIS virtual directory for each Commerce application. This information is read-only; the IIS Web site and virtual directory must be the same across all Web servers in the application. Click Next.

    Site Packager adds your files to the Web server, and then adds the Commerce Web server object to the selected application. When you open Commerce Server Manager, the Commerce Web server object appears under the application.

  5. In the Unpacking is complete! dialog box, review the log file, and then click Finish.

After you add a Web server to an application, the Commerce Web server object appears under the application node in Commerce Server Manager. The Commerce Web server object contains properties required by the Data Warehouse resource in order to import log files: server name, Internet Protocol (IP) address, log file path, and log file period. These properties are automatically populated from IIS when you add a Commerce Web server object to an application. For information about configuring these Web server properties, see Configuring a Web Server.

Note

  • To add a Web server to an existing application, you must use a package that contains an image of that application. For example, suppose you unpack a site called ShoeStore containing an application called Retail. If you rename the Retail application to Retail2, you must repackage the site with that renamed application and then use the new package to add Web servers to the application.

See Also

Hardware Requirements

Software Requirements

Adding Web Servers Without Site Packager


Adding Web Servers Without Site Packager

You can add Web servers to an application without using Commerce Server Site Packager. First, copy the files of the application to the server and configure the Internet Information Services (IIS) 5.0 application on the new server. You can use Microsoft Application Center 2000 for this. The first time the application is loaded on the new server, the new server will be added as a Web server under the appropriate application in the Commerce Server Administration database. The function that updates the Administration database is JoinWebFarm, which is included in the Commerce Server Solution Sites. It is located in the Global_siteconfig_lib.asp file, which is located in the include folder of unpacked Commerce Server Solution Sites.

After you add the Web server to the application, you must synchronize the following Web server properties in Commerce Server with the properties in IIS:

  • TCP port

  • SSL port

  • Internet Protocol (IP) address

  • Log file path

  • Log file period

To synchronize the properties, either manually update the values in Commerce Server Manager, or click the Synchronize Values button on the Web Servers tab in the Application Properties dialog box. For more information, see Configuring an Application.

When you click Synchronize Values, Commerce Server copies the properties from IIS at the application level and the properties for all the Web server objects below the application. For the properties at the application level (TCP port and SSL port), Commerce Server reads the values for the first Web server. It assumes that the Web servers have all been configured identically, which must be the case for a Web farm to operate correctly.

Because the JoinWebFarm code uses the SiteConfig object, it works only if the user has permissions to use SiteConfig. If you previously denied permission to SiteConfig, you can use the Windows Registry Editor to restore permission for this object. For more information, see Limiting Access to the Administration Database.

Note

  • Application Center 2000 synchronizes files and IIS settings, but does not update the Commerce Server Administration database, which is why an additional script including the JoinWebFarm function must be used. For more information about Application Center 2000, see the Application Center 2000 documentation.


Updating Site Content

When you initially deploy your Web site, you use Commerce Server Site Packager. To update the content of your site, you use a variety of tools depending on the component you are updating. The following table shows where Commerce Server components are located and how you can update them.

To update this type of content | Do this
Web pages (ASP and HTML files) | Use Microsoft Visual Studio, Microsoft Application Center 2000, the Content Deployment tool, or another Web-page publishing tool. For more information, see the Visual Studio or Application Center 2000 documentation.
Component Object Model (COM) applications | Transfer the appropriate dynamic-link libraries (DLLs) to the Web server, and then register them using the command regsvr32 <dll-filename>.
User profile and catalog schemas | Create a script. For a description of these schemas, see Profile Schema and Creating a Catalog Schema.
Catalog data, campaigns, advertisements, and discounts | Create and run a Data Transformation Services (DTS) task. When updating campaigns, advertisements, and discounts, move only tables containing these records. Do not overwrite the performance table. For more information about DTS tasks, see Running the Data Warehouse.
Pipelines | Copy the appropriate pipeline (.pcf) files.

Note

  • Before you update any content on a server, make sure there are no users connected to that server. Otherwise, users may encounter non-functioning links in your Web site.

See Also

Using SQL Server to Replicate Databases.


Using SQL Server to Replicate Databases

To ensure availability and scalability for larger Commerce Server 2000 sites, you might want to replicate your Catalog database. To do this, use SQL Server to replicate your Catalog servers or server clusters inside of a Network Load Balancing (NLB) cluster. For a diagram of this configuration, see Large Site Configuration.

Use SQL Server to replicate your Commerce Server databases. Whether you are using snapshot, transactional, or merge replication, the following stages will help you implement replication.

Stage | Tasks
Configuring replication | Identify the publisher, distributor, and subscribers in your topology. Use SQL Server Enterprise Manager, SQL-DMO, or Transact-SQL system stored procedures and scripts to configure the publisher, create a distribution database, and enable subscribers.
Publishing data and database objects | Create the publication and define the data and database object articles in the publication, and apply any necessary filters to data that will be published.
Subscribing to publications | Create push, pull, or anonymous subscriptions to indicate what publications need to be propagated to individual subscribers and when.
Generating the initial Snapshot | Indicate where to save snapshot files, whether they are compressed, and what scripts to run before or after applying the initial snapshot.
Applying the initial snapshot | Apply the snapshot automatically by synchronizing the subscription using the Distribution Agent or the Merge Agent. The snapshot can be applied from the default snapshot folder or from removable media that can be transported manually to the subscriber before application of the snapshot.
Synchronizing data Synchronizing data occurs when the Snapshot Agent, Distribution Agent, or Merge Agent runs and updates are propagated between publisher and subscribers.

For snapshot replication, a snapshot will be taken and propagated to subscribers. For transactional replication, the Log Reader Agent will store updates in the distribution database and the Distribution Agent will propagate updates to subscribers.

If you are using subscriptions that can be updated with either snapshot replication or transactional replication, data will be propagated from the subscriber to the publisher and to other subscribers.

For merge replication, data is synchronized during the merge process when data changes at all servers are converged. Conflicts, if any, are detected and resolved.

See Also

Updating Site Content


Changing the Names of Servers

It is strongly recommended that server names not be changed after you install Commerce Server 2000. If you must change the NetBIOS name of a server, you should uninstall Commerce Server, change the name, restart the server, make sure the platform is configured correctly, and then reinstall Commerce Server.

Commerce Server names the connection strings between resources based on the server names. If you change a name, the connections between resources might break. You will need to change these connection strings manually in Commerce Server Manager.

The Predictor, Commerce Server Direct Mailer, and Profiles global resources have display names containing the server name on which they were created. If you change the name of the server, you can use Commerce Server Setup to remove and then reinstall Predictor and Direct Mailer. You can use Commerce Server Site Packager to create a newly named Profiles global resource. You then must change the reference property in the Profiles global resource pointer for all sites that were using that Profiles global resource.

When you use Microsoft Application Center 2000 to reload an application onto a renamed Web server, the JoinWebFarm function, called by the Global.asa file during the Application_OnStart event, will create a new Web server node in the Administration database. You must use Commerce Server Manager to delete the old server name from the site.


Using Site Packager

Commerce Server Site Packager is a deployment tool that has two primary uses. You use it to package your Commerce Server 2000 site, including Internet Information Services (IIS) 5.0 settings (metabase), file system, resources from the Administration database, and SQL Server databases into a single file. You also use it to unpack the Commerce Server site (or portions of it) onto other computers.

In most cases, Site Packager is used for the initial deployment of your site. For future deployments, incremental updates, and rollbacks, use other tools such as Microsoft Application Center 2000 or other content management products.

This section contains:

  • About Site Packager. Describes what you can do with Site Packager, what makes up a package, and how global resources are unpacked.

  • Packaging a Site. Explains how to package a site into a package file.

  • Unpacking a Site. Explains how to unpack a site from a package file.

  • Using Scripts with Site Packager. Explains how to use pre- and post-installation scripts with Site Packager.

  • Running Site Packager from the Command Line. Explains how to use Site Packager from the command line.

  • Customizing the Site Packager .ini Files. Describes the .ini file included with Commerce Server Solution Sites, and how you can use these .ini files as templates for creating custom .ini files for your own packages.

  • Site Packager Reference Information. Lists the data and settings that are set up in SQL Server when you unpack a site.


About Site Packager

Commerce Server Site Packager packages and unpacks Web sites and settings so you can easily deploy your applications.

Packages

Unpacking Options

Solution Sites

How Database and Application Names Are Created

How Global Resources Are Unpacked

Where Databases Are Located

How Web Server Permissions Are Set

Packages

A package is a specially formatted Commerce Server file. Each package is identified with a .pup filename extension. A package always contains a single site, which includes the resources, their data, and applications of a Commerce Server site.

In addition to site resources, applications, and the Internet Information Services (IIS) 5.0 settings that are needed to recreate the Web server configurations, Commerce Server Site Packager also includes the property values from the Administration database. For example, when you package the App Default Config resource, all of the current property values are also packaged. When you unpack the App Default Config resource, the property values are unpacked onto the Administration database.

The package includes global resource pointers but not the global resources themselves. Connection strings are packaged without the user name and password fields.

During the application packaging process, Site Packager searches the IIS metabase on your local computer, and finds the physical directory that is the root for that application. It then starts at that root directory and packages all the subdirectories below into a new file with a .pup filename extension. Site Packager preserves certain settings in IIS, such as authorizations and access permissions.

Site Packager does not package properties that are specific to the computer you are on. For example, Web server properties and some application properties that are set in Commerce Server Manager are not packaged. For a list of data that is packaged for each resource, see Site Packager Reference Information.

Unpacking Options

By default, Site Packager unpacks each application into the IIS Default Web Site in a virtual directory that matches the application name. To improve the security of your site, you should create a new IIS Web site instead of using the Default Web Site for the Commerce Server sites you unpack. You can change the name of the virtual directory that contains each application. To change the IIS Web site or virtual directory while unpacking, you must use the Custom mode of Site Packager.

When you unpack another Web server to an application (and create a Web farm), you are not able to change any of the application configuration information during the unpacking process because all Web servers must use the same settings. Site Packager displays the name of the IIS Web site where the application will be installed and the IIS application path for each Commerce Server application.

When you unpack a site and application that already exist in the Administration database, Site Packager assumes you are adding a Web server to the application.

Solution Sites

Solution Sites are packages that contain the resources you need to build a site. After you install Commerce Server, you can unpack one of these Solution Sites, and then use it as a foundation for building your own site.

Commerce Server includes the following Solution Site:

  • Blank. Contains all the Commerce Server resources for building a custom site.

Additional Solution Sites are available on the Commerce Server Web site, such as:

  • Retail. Contains the Commerce Server resources for building a retail site.

  • Supplier. Contains the Commerce Server resources for building an Active Directory-enabled supplier site.

How Database and Application Names Are Created

Commerce Server Site Packager derives the database names and application names from the package.

An IIS application is created for each application in the package. The full path of each application is stored in the package.

How Global Resources Are Unpacked

Two global resources — Predictor and Direct Mailer — are installed by using Commerce Server Setup; all other global resources are installed using Site Packager. Before you unpack a site that requires the global resources Predictor or Direct Mailer, you must install these resources by using Commerce Server Setup. For information about installing a global resource, see Installing and Uninstalling Global Resources.

Where Databases Are Located

Site Packager does not prompt you to specify the locations of database files. Instead it accepts the SQL Server default folders. Make sure there is enough disk space to create the databases on the database servers.

How Web Server Permissions Are Set

IIS Web server permissions can be set up to limit the access of anonymous users to your applications, and can also be used to limit the viewing of source code over the Internet, even for users with Windows permissions (or access control entries).

It is important to understand the distinction between Web server permissions and NTFS permissions. Unlike NTFS, Web server permissions apply to all users accessing your Web sites. NTFS permissions apply only to a specific user or group of users with a valid Windows account. NTFS controls access to physical directories on your server, whereas Web permissions control access to virtual directories on your Web site.

When you package a site, it will pick up the Web server permissions as set in the source site. For example, if you have the Execute Permissions setting set to Scripts and Executables in the root folder of the application on the source computer, the virtual root folder on the destination computer will have the same setting.

For example, the following table describes how the IIS permissions are set in the packages provided by Microsoft.

Folder | Permissions
Root | Set Execute permission to Scripts and Executables.
Pipeline, Include, Template | Deny permission to read, write, and execute.

Note

  • Site Packager does not preserve Windows access control lists (ACLs), which contain NTFS permissions. ACLs describe the groups and individuals who have access to specific objects in Windows 2000. These objects include Microsoft Active Directory objects, local NTFS files and folders, the registry, and printers.

See Also

Using Commerce Server and IIS

Packaging a Site

Unpacking a Site

Site Packager Reference Information

Running Site Packager from the Command Line


Packaging a Site

When you package a site, you save your applications and settings in a single package file.

To package a site

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2000, and then click Commerce Server Site Packager.

  2. In the Welcome to Commerce Server Site Packager dialog box, select the Package an existing site option, and then click Next.

  3. In the Package Site dialog box, do the following:
    Use this | To do this
    Site to package | Select the site you want to package from the list of available sites.
    Package file to create | Type the name of the package file you are creating.

  4. Click Browse.

  5. In the Save As dialog box, navigate to the folder where you want to create the package, provide the file name, and then click Save. When you are returned to the Commerce Site Packager screen, click OK.

  6. In the Profiling System dialog box, do the following:
    Use this | To do this
    Schema definition scripts Specify the schema definition scripts you want to include in the package. Click Browse to specify the location of these scripts.

    Site Packager uses a default schema definition script. If you modify the UserObject table or other profile schema definitions, you must use SQL Server Enterprise Manager to generate a script to use here. For more information, see Packing Extended Profile Schema.
    Data population scripts | Specify the data population scripts you want to include in the package. Click Browse to specify the location of these scripts.

  7. Click OK.

  8. In the Packing is complete! dialog box, to review the list of events in the Site Packager log file, click View Log File.

  9. To close Site Packager, click Finish.

Notes

  • If you package a Commerce Server application whose IIS virtual directory contains child IIS applications, Site Packager will package the folders and files of the child applications. If you do not want the folders and files of the child applications, you will have to delete them after you unpack the parent Commerce Server application.

  • Site Packager does not package files in child virtual directories of the IIS application. If you need to package files in child virtual directories, move the folders and files to child physical folders of the root folder of the IIS application before packaging your site.

  • Before you can package a site that has applications (for example, Retail and RetailBusinessDesk) on separate Web servers, you must add one of the Web servers to the other application. For example, if Retail is installed on Computer A and RetailBizDesk is on Computer B, you can run Site Packager on Computer B to add it as a Web server for Retail. Then you can package the site from Computer B. (Conversely, you could add Computer A to RetailBizDesk, and package the site there.) For more information, see Adding a Web Server to an Application.

See Also

About Site Packager

Unpacking a Site

Running Site Packager from the Command Line


Unpacking a Site

You use Commerce Server Site Packager to unpack a site or a subset of a site onto one or more computers. When running Site Packager, you must have appropriate permissions to copy files to the destination folders.

To unpack a site quickly, accepting most default settings

To unpack a site, specifying all settings yourself

Notes

  • Do not run more than one instance of Site Packager on a computer at a time.

  • To unpack a site onto an Internet Information Services (IIS) 5.0 Web site other than the default, use the Custom mode of Site Packager.

  • If you unpack the Direct Mailer resource after you unpack a Business Desk application and install the Business Desk client, you must restart Internet Information Services (IIS) 5.0 on the Web server hosting the Business Desk application in order for the addition of Direct Mailer to be detected. Business Desk clients must re-connect to the application. For instructions about restarting IIS, see Restarting IIS.

  • Business Desk modules are not automatically removed from the Business Desk application if you choose not to unpack a required resource. For example, if you do not unpack Product Catalog, the Catalogs modules will still appear in Business Desk, but they will not work.

Use the following procedure if you are making this computer a Web server, and you are going to put all of your database files on one SQL Server.

To unpack a site quickly, accepting most default settings

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2000, and then click Commerce Server Site Packager.

  2. In the Commerce Server Site Packager dialog box, select Unpack from a package file, and then click Next.

  3. In the Unpack dialog box, click the Browse button next to the File to unpack box.

  4. In the Open dialog box, navigate to the folder that contains the file you want to unpack, select the file, and then click Open.

  5. When you are returned to the Unpack dialog box, select Quick unpack, and then click Next.

  6. In the Quick Unpack dialog box, do the following:
    Use this | To do this
    Site name | Type the name for the site, if you want to change it. Do not include special characters (such as #, @, %, and ') in the name. Do not name your site "Commerce."
    IIS Web site | Select the name of the IIS Web site where the applications(s) will be installed.
    SQL Server computer | Type the name of the SQL Server that will contain the databases for the site.
    SQL user name | Type the SQL login name for the databases.
    SQL password | Type the SQL login password.

  7. If the Data Warehouse dialog box appears, do the following:
    Use this | To do this
    Name | Type the name you want to give to the global Data Warehouse resource.
    Server | Type the name of the SQL Analysis online analytical processing (OLAP) computer.
    Database | Type the name of the Analysis (OLAP) database to use.

  8. Click Next.

  9. If the first Profiling System dialog box appears, do the following:
    Use this | To do this
    Profile Schema Definition | Specify the profile schema definition to import.
    Site Terms Definition | Specify the site terms definition to import.
    Expression Definition | Specify the expression definition to import.

  10. Click Next.

  11. If the second Profiling System dialog box appears, do the following:
    Use this | To do this
    Profiling System Connection String | Specify the files to import into the OLEDB data store. Click Modify to specify a different database.
    Schema definition scripts (*.sql, *.vbs) | Specify the schema definition scripts to import.
    Data population scripts (*.sql) | Specify the data population scripts to import.

  12. Click Next.

  13. In the Unpacking is complete! dialog box, review the list of SQL Server databases and IIS applications that were created. To review the list of events in the Site Packager log file, click View Log File.

  14. To close Site Packager, click Finish.

Use the following procedure if you are adding this Web server to an existing application, or you want to specify that more than one database server will be used with the site.

To unpack a site, specifying all settings yourself

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2000, and then click Commerce Server Site Packager.

  2. In the Commerce Server Site Packager dialog box, select Unpack from a package file, and then click Next.

  3. In the Unpack dialog box, click the Browse button next to the File to unpack box.

  4. In the Open dialog box, navigate to the folder that contains the file you want to unpack, select the file, and then click Open.

  5. When you are returned to the Unpack dialog box, select Custom unpack, and then click Next.

  6. In the Unpack Method dialog box, select the appropriate option, and then click Next.

  7. In the Site Name box, type the name for the site, and then click Next.

    Notes

    • To avoid unpacking errors, you should avoid special characters (such as #, @, %, and ') in your site name. By default, the database names of the site are prefixed with the site name, and special characters might not be recognized in SQL Server.

    • Do not specify a site name of more than 256 single-byte characters or 128 double-byte characters.

    • Do not name your site "Commerce." This is a reserved OLAP database name. Naming your site "Commerce" could cause the overwriting of your OLAP database the next time you unpack a site.
  8. In the Select Applications or Select Resources dialog box, select the items you want to install, and then click Next.

    Note

    • In the Select Resources dialog box, you must install the CS Authentication and Profiles resources together. They do not work unless both are installed.
  9. In the Global Resource Pointers dialog box, click Next.

    You use this dialog box to map to existing global resources or to create new ones.

  10. In the Database Connection Strings dialog box, Site Packager lists the databases it will create and the servers on which it will create them. Verify that the databases are correct, and then click Next.

  11. In the Select Applications dialog box, verify that the applications you want to unpack are selected, and then click Next.

  12. In the Select IIS Web Sites and Virtual Directories dialog box, verify that the IIS Web sites and application paths are correct, and then click Next.

    Notes

    • To avoid IIS errors, you should not include special characters (such as #, @, %, and ') in your virtual directory names.

    • Site Packager does not support unpacking a site on a remote computer.

    • Site Packager will unpack each application under the home directory of its corresponding IIS Web site. Within the home directory, Site Packager creates a subfolder using the IIS virtual directory name of the application.
  13. If the Data Warehouse dialog box appears, do the following:
    Use this | To do this
    Name | Type the name you want to give to the global Data Warehouse resource.
    Server | Type the name of the SQL Analysis (OLAP) computer.
    Database | Type the name of the Analysis (OLAP) database to use.

  14. Click Next.

  15. If the first Profiling System dialog box appears, do the following:
    Use this | To do this
    Profile Schema Definition | Specify the profile schema definition to import.
    Site Terms Definition | Specify the site terms definition to import.
    Expression Definition | Specify the expression definition to import.

  16. Click Next.

  17. If the second Profiling System dialog box appears, do the following:
    Use this | To do this
    Profiling System Connection String | Specify the files to import into the OLEDB data store. Click Modify to specify a different database.
    Schema definition scripts (*.sql, *.vbs) | Specify the schema definition scripts to import.
    Data population scripts (*.sql) | Specify the data population scripts to import.

  18. Click Next.

  19. In the Unpacking is complete! dialog box, review the list of SQL Server databases and IIS applications that were created. To review the list of events in the Site Packager log file, click View Log File.

  20. To close Site Packager, click Finish.

Notes

  • Immediately after you install your site, and any time you make major configuration changes to your Commerce Server deployment, you may want to back up your Administration database with a different name. You can use this backup to roll back any changes that are made later.

  • If you install Commerce Server databases (other than the Data Warehouse) on a remote computer, it is possible there will be a delay before these databases appear on that computer.

  • If you create and use an unpack.vbs script file when you unpack a non-Commerce Server Business Desk application, make sure you delete or secure the file immediately after unpacking. The file exists in the root directory, and can be accessed by anonymous users. Unauthorized use of this script could lead to denial of service or the breaking of site settings.

See Also

About Site Packager

Packaging a Site

Example A: Installing on a Four-Computer Clustered Configuration

Example B: Installing on a Three-Computer Non-clustered Configuration

Running Site Packager from the Command Line

Troubleshooting Site Packager


Using Scripts with Site Packager

You can use three types of Microsoft Visual Basic scripts with Commerce Server Site Packager.

Pre-packaging scripts

Post-packaging scripts

Application scripts

Packing Extended Profile Schema

Pre-packaging scripts

Site Packager executes a pre-packaging script as soon as the package name is known, before the site is unpacked. Pre-packaging scripts must be named Pre<package name>.vbs, for example, PreRetail.vbs.

A pre-packaging script is provided with one parameter, mode ( /s: ), which indicates whether Site Packager is running in silent mode or normal installation mode. In order for the pre-packaging scripts to run, they must reside in the same folder as the package you are unpacking.

Post-packaging scripts

Site Packager runs a post-packaging script after all unpacking is complete, but before the Unpacking is complete! dialog box appears. Post-packaging scripts must be named Post<package name>.vbs, for example, PostRetail.vbs. A post-packaging script is provided with two parameters:

  • Site name in quotation marks ("MySite")

  • Mode ( /s: ) — silent mode or normal installation mode

Post-packaging scripts must reside in the same folder as the package you are unpacking in order for them to run.

Application scripts

Site Packager can also run application-specific scripts. Application scripts are provided with six parameters:

  • Site name in quotation marks (/n:"MySite")

  • Application name in quotation marks (/r:"MyApp")

  • Server number or the instance number of the IIS Web site that the application was installed to (/i:1)

  • Name of the virtual directory that the application was installed to (/v:"MyRoot")

  • File path in quotation marks where the application files were installed (/d: "C:\inetpub\wwwroot")

  • Mode (/s:) — silent mode or normal installation mode

Application scripts are run for each application after the following events occur:

  • The application has been installed and the files copied.

  • The IIS properties have been set for the application.

  • The application information has been written to the Administration database.

  • Site Packager has notified the Data Warehouse that the application exists.

Note

  • If you create and use an unpack.vbs script file when you unpack a non-Commerce Server Business Desk application, make sure you delete or secure the file immediately after unpacking. The file exists in the root directory, and can be accessed by anonymous users. Unauthorized use of this script could lead to denial of service or the breaking of site settings.

See Also

Running Site Packager from the Command Line

Customizing the Site Packager .ini Files

Packing Extended Profile Schema

If you want to create a package that contains an extended profile schema, you must generate the script before you package your site. The following steps outline how to package an extended profile schema:

  1. Use SQL Server Enterprise Manager to extend the UserObject table, adding your own attributes. For more information, see the SQL Server documentation.

  2. Add the new data members to the data object. For more information, see Adding a New Data Member.

  3. Use SQL Server Enterprise Manager to generate scripts for your extended profile schema. For more information, see the SQL Server documentation.

  4. When you package your site, Site Packager prompts you to specify the location of the schema definition script you generated. If you do not specify your script, Site Packager will package the default script, which will not include your extension.

See Also

UserObject Profile Schema

Packaging a Site


Running Site Packager from the Command Line

You can run Commerce Server Site Packager from the command line interface by using the run-time file, Pup.exe. Site Packager includes a set of command line switches that you use to perform tasks on sites and resources, including packaging, unpacking, and deleting a site or resource. In addition, you can establish unique resource references for custom installation requirements by using Microsoft Visual Basic scripts.

For example, to package a site named BlankSite, you would type the following at the command line:

PuP.exe /p  /s:BlankSite /f:D:\Program Files\Microsoft Commerce Server\PuP Packages\XBlank.pup /i:D:\Program Files\Microsoft Commerce Server\SiteCreate\packBlank.ini

Note

  • When you type the commands to package a site, you must separate the parameters with a blank space. You must also specify the full path and file name of the response file (in the previous example, the response file is packBlank.ini).

The following table lists the command line options you can use with the Pup.exe file.

Parameter | Packaging | Unpacking | Description
/s: | X |  | Specifies the name of the site to package. /s:<name of site>
/f: | X | X | Specifies the path to the package file. /f:<full path to package>
/r | X | X | Displays the Select Resource dialog box.
/i: | X | X | Specifies the .ini file to use during silent operation. /i:<complete path name>
/p | X |  | Packages a site or resource.
/u |  | X | Unpacks a site or resource.
/a: | X | X | Specifies the name of the application. /a:<application name>
/w: |  | X | Specifies the name of the Web server. /w:<Web server name> Use this option to unpack the local computer as a Web server.

For example, to unpack a site named Retail, you would use the following command:

D:\Program Files\Microsoft Commerce Server\PuP.exe /u /f:D:\Program Files\Microsoft Commerce Server\PuP Packages\Retail.pup /i:C:\Commerce\Retail.ini

See Also

Customizing the Site Packager .ini Files


Customizing the Site Packager .ini Files

Commerce Server includes the packBlank.ini file with the BlankSite package. Separate .ini files are provided for the Retail and Supplier Solution Sites, available on the Commerce Server Web site. You can use these .ini files as templates for creating custom .ini files for your own packages. These .ini files are useful for doing automated builds of your packages, for example, in a production environment, in which you want to build every night and then install in the morning.

You can use the same .ini file for both packaging and unpacking. During the packaging or unpacking process, the pieces that are irrelevant to the task are ignored.

Run .ini files from the command line. For instructions and a sample command, see Running Site Packager from the Command Line.

The following is the content of the packBlank.ini file, including comments about each section. An asterisk (*) indicates comments:

[General]

SiteName=BlankSite
Description=Blank site
NumOfResources= 11
NumOfApplications= 2

*The following is a list of the resources to be installed. If you do not want to install a given resource, delete the resource line from the .ini file, and renumber the resources. The order in which the resources are unpacked does not affect the unpacking process. However, all of the resources are unpacked before the applications.

Note

  • When packaging a site, the list of resources in the .ini file is not read. Instead the entire site is packaged.
Resource0=App Default Config
Resource1=Product Catalog
Resource2=Campaigns
Resource3=Site Data Warehouse
Resource4=Transactions
Resource5=Transaction Config
Resource6=Direct Mail
Resource7=Predictor
Resource8=Biz Data Service
Resource9=Group Data Warehouse
Resource10=Site CS Authentication
Application0=B2CSite
Application1=B2CBizDesk
NumOfConnStrs= 6

[App Default Config]

*App Default Config does not include a UseData flag because it contains only configuration information.

[ConnStrs]

*In this section the connection strings for the resources are listed. The connection strings take the following parameters:

ConnStrResourceName

The name of the resource.

ConnStrValue

The connection string value.

ConnStrPropertyName

The property name for the connection string.

The following sample shows the [ConnStrs] section:

ConnStrResourceName0=Product Catalog
ConnStrPropertyName0=connstr_db_Catalog
ConnStrValue0=Provider=SQLOLEDB;Persist Security Info=False;User ID=;Password=;Initial Catalog=BlankSite_commerce;Data Source=SERVERNAME;
ConnStrResourceName1=Campaigns
ConnStrPropertyName1=connstr_db_Campaigns
ConnStrValue1=Provider=SQLOLEDB;Persist Security Info=False;User ID=;Password=;Initial Catalog=BlankSite_commerce;Data Source=SERVERNAME;
ConnStrResourceName2=Transactions
ConnStrPropertyName2=connstr_db_Transactions
ConnStrValue2=Provider=SQLOLEDB;Persist Security Info=False;User ID=;Password=;Initial Catalog=BlankSite_commerce;Data Source=SERVERNAME;
ConnStrResourceName3=TransactionConfig
ConnStrPropertyName3=connstr_db_TransactionConfig
ConnStrValue3=Provider=SQLOLEDB;Persist Security Info=False;User ID=;Password=;Initial Catalog=BlankSite_commerce;Data Source=SERVERNAME;
ConnStrResourceName4=Biz Data Service
ConnStrPropertyName4=connstr_db_bds
ConnStrValue4=Provider=SQLOLEDB;Persist Security Info=False;User ID=;Password=;Initial Catalog=BlankSite_commerce;Data Source=SERVERNAME;
ConnStrResourceName5=Global Data Warehouse
ConnStrPropertyName5=connstr_db_dw
ConnStrValue5=Provider=SQLOLEDB;Persist Security Info=False;User ID=;Password=;Initial Catalog=BlankSite_dw;Data Source=SERVERNAME;

[Product Catalog]

*UseData indicates whether you want to include the data and the schema, or only the schema. 1 means you want to include both the data and schema. UseData does not affect applications, or the Profiles resource, CS Authentication resource, or the Data Warehouse resource.

UseData = 1

[Campaigns]

UseData = 1

[Site Data Warehouse]

*Site Data Warehouse does not use a UseData flag because it includes only configuration information.

[Transactions]

UseData = 1

[Transaction Config]

UseData = 1

[Direct Mail]

*Use GlobalResourceName to assign the global resource to a global resource name that already exists on the computer. If the value of this setting is (Add New Global Resource), then the global resource is added to the site, instead of associated with an existing global resource.

GlobalResourceName=Direct Mail on SERVERNAME

[Predictor]

GlobalResourceName=Predictor on SERVERNAME

[B2CSite]

ASPDir=
VRoot=
Website=
UseData = 1

[B2CBizDesk]

ASPDir=
VRoot=
Website=
UseData = 1

[Biz Data Service]

*This UseData does not affect what is included for the Profiles service. The Profiles service takes only schema; it never takes data.

UseData = 1
GlobalResourceName= (Add new global resource)

[Global Data Warehouse]

*This UseData does not affect what is included for Group Data Warehouse. The Group Data Warehouse takes only schema; it never takes data.

UseData = 1
GlobalResourceName= (Add new global resource)

[Site CS Authentication]

GlobalResourceName= (Add new global resource)


Site Packager Reference Information

This site contains information about what data and settings are included when you package a site.

Resources and Data

The following table lists the resources and the data packaged for each resource when you package a site.

Resource | Data packaged
App Default Config | All property values.
Campaigns | These tables in the Campaigns database: industry_code, customer, event_type, campaign, creative_type, creative_size, creative, creative_property, creative_property_value, campaign_item_types, campaign_item, order_discount, dm_item, ad_item, creative_type_xref, page_group, page_group_xref, target_group, target, target_group_xref, order_discount_expression, order_discount_misc.
CS Authentication | Settings in AuthSetup.ini. When unpacking a site, you can create a new resource or point to an existing one.
Commerce Server Data Warehouse | None. When unpacking a site, you can create a new Data Warehouse resource or point to an existing one.
Commerce Server Direct Mailer | None. Confirms the existence of a Direct Mailer in the site. The Direct Mailer global resource to use is specified during unpacking. When unpacking a site, you can point to a Direct Mailer resource. You must use Commerce Server Setup to create a new one.
Predictor | None. Confirms the existence of a Predictor in the site. The Predictor global resource to use is specified during unpacking. When unpacking a site, you can point to a Predictor resource. You must use Commerce Server Setup to create a new one.
Product Catalog | These tables in the Catalog database: CatalogAttributes, CatalogDefinitions, CatalogDefinitionProperties, CatalogGlobal, CatalogUsedDefinitions, CatalogEnumValues, CatalogStatus, CatalogCustomCatalogs, CatalogCustomPrices, CatalogSet_Info, CatalogSet_Catalogs, CatalogToVendorAssociation, x_ProductsComplete, x_Relationships, x_Hierarchy
Profiles | Schema script and data script. Defaults are commerce_server_root\Profilesql.sql and commerce_server_root\PopulateProfileSql.sql, respectively. Existing databases are not packaged. When unpacking a site, you can create a new resource or point to an existing one.
Transactions | These tables in the Transactions database: TransDimension, TransCategory.
Transactions Config | These tables in the Transactions Config database: Decode, Region, RegionalTax, ShippingConfig, TableShippingRates.

IIS Settings

When you package a site, Site Packager includes many of your IIS settings. It does not pack an IIS Web site (such as Default Web Site), but it does pack the files in the physical root folder of the application and all of its physical child folders and files.

To view IIS settings for an application, folder, or file

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2000, and then click Commerce Server Manager.

  2. In the Commerce Server Manager window, expand Internet Information Services, expand the name of the Web server containing an application, expand the name of the IIS Web site in which the application resides, right-click the name of an application, folder, or file, and then click Properties.

    The Properties dialog box for the application appears.

The following tables list the settings for the Virtual Directory and Directory Security tabs in the Properties dialog box, and indicate which ones are packaged when using Site Packager.

Virtual Directory tab

Field | Whether it is packaged
Script source access | Packaged
Read | Packaged
Write | Packaged
Directory browsing | Packaged
Log visits | Packaged
Index this resource | Packaged
Application name | Not packaged
Starting point | Not packaged
Execute permissions | Packaged
Application protection | This is always set to Medium when unpacking
Application Configuration settings (shown after Configuration is clicked) | Not packaged

Directory Security tab

Field | Whether it is packaged
Anonymous access | Packaged
Anonymous access account | Not packaged
Basic authentication | Packaged
Basic authentication domain | Not packaged
Digest authentication | Packaged
Integrated Windows authentication | Packaged
IP addresses and domain name restrictions | Not packaged
Secure communications (SSL certificates) | Not packaged

Note

  • Nothing in the Documents, HTTP Headers, and Custom Errors tabs is packaged. The unpack.vbs script file for Business Desk adds custom errors for Business Desk after unpacking.

IIS Virtual Directories

If you have virtual directories located within the application, the virtual directory object and the folders and files in the path it points to will not be packaged. If you want to package these folders and files, copy them to a folder in the physical path of the application before packaging them.

NTFS Permissions

NTFS permissions and access control lists on folders and files are not packaged. You can use the unpack.vbs script or post site.vbs script to apply NTFS permissions automatically after unpacking.


Administering Commerce Server

This section describes how to use Commerce Server Manager to administer Microsoft Commerce Server 2000. This section is intended for the system administrator, whose responsibilities include adding and managing resources used by sites, installing and configuring Web servers, monitoring Commerce Server performance, and maintaining Commerce Server databases.

This section contains:

  • Commerce Server Manager Help. Lists common tasks you perform using Commerce Server Manager.

  • Administration Basics. Describes Commerce Server resources, sites, applications, Web servers, and the Administration database. Describes the relationship between Commerce Server and Microsoft Internet Information Services (IIS) 5.0. Explains how to set up a computer to be used for administration purposes only.

  • Managing the Administration Database. Describes the Administration database and how sites interact with it. Explains how to configure the database and manage security.

  • Managing Commerce Resources. Explains how to add and remove global-level resources and site-level resources, and how to start and stop a resource.

  • Managing Commerce Sites. Explains how to add, configure, and delete a site.

  • Managing Commerce Applications and Web Servers. Explains how to add, configure, and delete a Commerce Server application, and how to add and delete a Web server.

  • Maintaining Commerce Server. Explains how to back up and restore Commerce Server files and Commerce Server databases.

  • Managing the CS Authentication Resource. Explains how to use the CS Authentication resource to establish or change the authentication and identification method for your Commerce Server site.

  • Running the Data Warehouse. Explains how to import data into the Data Warehouse and how to customize the import process. Explains how to manage and enrich the data in the Data Warehouse.

  • Running Direct Mailer. Explains how to develop personalized direct mail messages. Explains how to customize Commerce Server Direct Mailer, and how to run, monitor, and delete direct mail jobs.

  • Running the Predictor Resource. Explains how to build new Predictor and Segment models, view models, and monitor the Predictor resource.

  • Running the Profiles Resource. Explains how to add Profile data sources to Commerce Server, how to create profile definitions to collect data from your Web site, and how to create site terms.

  • Using BizTalk Server and Commerce Server. Explains how to set up Commerce Server and BizTalk Server to process purchase orders and exchange catalogs.

  • Monitoring Commerce Server Sites. Explains how to monitor a Commerce Server installation. Describes the Commerce Server counters. Explains how to use the Commerce Server system counters to improve server performance.

  • Optimizing Commerce Server. Explains how to minimize the response time for each request and how to maximize the throughput of Commerce Server.

  • User Interface Reference. Provides the context-sensitive help topics for the Data Warehouse, Data Transformation Services tasks, Predictor resource, and Commerce Server Site Packager.


Commerce Server Manager Help

Following is a list of common tasks performed from Commerce Server Manager.

Area Topics
Resources
  • Installing and Uninstalling Global Resources

  • Adding a Global Resource Pointer to a Site

  • Adding a Resource to a Site
Sites and Applications
  • Using Site Packager

  • Example A: Installing on a Four-Computer Clustered Configuration

  • Example B: Installing on a Three-Computer Non-Clustered Configuration

  • Adding a Site

  • Adding an Application to a Site

  • Adding a Web Server to an Application

  • Configuring the Administration Database

  • Configuring an Application

  • Configuring a Web Server
Predictor Resource
  • Configuring Predictor Resource Properties

  • Rebuilding an Analysis Model
Direct Mailer
  • Configuring Direct Mailer

  • Running Direct Mailer
Data Warehouse
  • Configuring Data Warehouse Resource Properties

  • Configuring Web Log File Import Properties

  • Importing Data into the Data Warehouse
CS Authentication Resource
  • Configuring CS Authentication Resource Properties

  • Managing the CS Authentication Resource
Profiles Resource
  • Configuring the Profiles Resource

  • Adding a New Data Source
App Default Config Resource
  • Configuring App Default Config Resource Properties

  • Configuring Commerce Server to Work with BizTalk Server
Troubleshooting
  • Troubleshooting Commerce Server


Administration Basics

This section describes Microsoft Commerce Server 2000 resources, sites, applications, and Web servers. It describes the Administration database, including how it is created and updated. It also describes the relationship between Commerce Server and Microsoft Internet Information Services (IIS) 5.0. It explains how to set up a computer to be used for administration only.

This section contains:

  • Administration Tools. Lists and describes the tools used to maintain Commerce Server.

  • Using Commerce Server Manager. Describes Commerce Server Manager and explains how to start it.

  • About Resources, Sites, Applications, and Web Servers. Describes resources, sites, applications, and Web servers, which are the Commerce Server objects in the Microsoft Management Console (MMC).

  • About Commerce Server Databases. Describes the Commerce Server database, and the data that each database contains.

  • Setting Database Connection Strings. Lists the Commerce Server connection strings, and explains how to set them.

  • Using Commerce Server and IIS. Describes the Web server properties you can set in both Commerce Server and IIS, and describes how properties are inherited from IIS to Commerce Server.

  • Installing Administration Tools Only. Explains what an administration-only computer is, and how to set up this type of computer.

  • About Data Transformation Services. Lists and describes the Data Transformation Services (DTS) tasks that are included with Commerce Server.


Administration Tools

The following table lists the administration tools used to maintain a Commerce Server 2000 installation.

Use this | To do this
Commerce Server Manager | Manage and configure Commerce Server resources, sites, applications, and Web servers
Commerce Server Site Packager | Deploy sites, resources, applications, and Web servers
SQL Enterprise Manager | Manage Commerce Server databases
IIS snap-in | Manage Web servers
Windows 2000 Active Directory Users and Computers | Manage Windows 2000 user accounts, computer accounts, and security and distribution groups
Windows 2000 Event Viewer | View event logs
Windows 2000 System Monitor | Collect and view real-time computer performance data
Windows 2000 Backup Wizard | Back up the IIS metabase, Windows 2000 Registry settings, and Commerce Server files
Windows 2000 Restore Wizard | Restore the IIS metabase, Windows 2000 Registry settings, and Commerce Server files


Using Commerce Server Manager

Commerce Server Manager is a tool that you use to manage and configure Commerce Server 2000 resources, sites, applications, and Web servers. The Microsoft Management Console (MMC), a Windows-based interface that is included in Microsoft Windows 2000, hosts Commerce Server Manager.

The functionality in Commerce Server Manager is not available through either Web-based or command line administration. Instead, most of this functionality is accessed and manipulated through Component Object Model (COM) objects, so it is possible for you to write a Windows Scripting Host (WSH) script or an Active Server Pages (ASP) page to extend the administration environment.

To access Commerce Server Manager

  • Click Start, point to Programs, point to Administrative Tools, and then click Commerce Server Manager.

See Also

Integrating Custom Resources

Configuring the Administration Database


About Resources, Sites, Applications, and Web Servers

Resources, sites, applications, and Web servers are Commerce Server 2000 objects in Commerce Server Manager that you use to manage your Commerce Server installation. This section describes each object and how the objects interact.

  • Resources

  • Sites

  • Applications

  • Web Servers

The following figure shows the Commerce Server Manager console and identifies its parts.

Click the illustration to enlarge or reduce.


Resources

A resource is an entity that provides functionality to the applications in a Commerce Server site.

A resource is comprised of one or more Component Object Model (COM) objects that are used on the Web pages of an application to access the resource functionality. Resources include properties that are stored in the Administration database. These properties can be accessed and changed using Commerce Server Manager (and changed programmatically through the Config objects).

There are two types of resources: global resources and site resources. Third parties can develop custom global resources and site resources to work with Commerce Server. For more information, see Integrating Custom Resources.

Global Resources

Site Resources

Global Resources

Global resources are available for use by all sites.

Some global resources are created by Commerce Server Setup; others are created when you unpack a site using Commerce Server Site Packager. Only resources with global-level properties appear in Commerce Server Manager under Global Resources. Every site that uses a global resource also uses the properties that you assign to that global resource.

The following table lists and describes the global resources included with Commerce Server.

Global resource | Description | Installed by
Commerce Server Direct Mailer (also a Windows 2000 service) | Sends personalized or non-personalized mailings to large groups of recipients. | Commerce Server Setup
Predictor (also a Windows 2000 service) | Adds predictive capabilities to your Web site, and builds complex analysis models that you can use to identify population segments and user trends. | Commerce Server Setup
Data Warehouse | Imports and manages Web site data from Web log files, Commerce Server databases, and other data sources. | Commerce Server Site Packager
CS Authentication | Configures the authentication and identification methods for your Commerce Server site. | Commerce Server Site Packager
Profiles | Creates data sources for storing profile data, and creates and stores profile definitions and properties. | Commerce Server Site Packager

Site Resources

Site resources provide functionality to a specific site.

In Commerce Server Manager, global resource pointers and site resources are listed under the site. You configure the properties of a site resource at the site level. You configure global resource pointers to point to the global resource at the global level.

A resource can have all of its properties at the site level, or all of its properties at the global level, but it cannot have properties in both places.

The following table lists and describes the site resources included with Commerce Server.

Site resource | Description
App Default Config | Stores properties that you use to configure a site, such as currency locale and symbols, billing and payment options, privacy options, unit of measure for weight, and options for integrating with BizTalk Server.
Campaigns | Connects to the database that stores data about campaigns (ads, discounts, and direct mail).
Product Catalog | Connects to the database that stores catalog schema and product data.
Transactions | Connects to the database that stores data for baskets and orders.
Transactions Config | Connects to the database that stores data for shipping methods and rates, tax rates, state and region codes, and order status codes.

See Also

Integrating Custom Resources

Example A: Installing on a Four-Computer Clustered Configuration

Example B: Installing on a Three-Computer Non-Clustered Configuration

Managing Commerce Resources


Sites

A site is a collection of Active Server Page (ASP)-based applications that use Commerce Server COM objects, which in turn use and modify resources. A site provides a means of administering the applications in the site together.

A site typically includes at least two applications: one that users browse to view your online store, and one that business managers use to access Commerce Server Business Desk. In addition, a site may include other applications. For example, a site might include www.alpineskihouse.com, www.alpineskihouse.com/equipment, www.alpineskihouse.com/clothing, and www.alpineskihouse.com/BusinessDesk. All of these applications can be distributed across many servers.

Sites use both global resources, which are shared across multiple sites, and site resources that are defined explicitly for the site.

From a site node in Commerce Server Manager, you can package a site, and add and delete resources.

See Also

Using Site Packager

Example A: Installing on a Four-Computer Clustered Configuration

Example B: Installing on a Three-Computer Non-Clustered Configuration

Securing Your Site

Backing Up Your Site


Applications

A Commerce Server 2000 application is a Web site. It is a logical representation of an application in Internet Information Services (IIS) 5.0; it appears in both the Commerce Server Manager and IIS console trees. In the IIS console, an application is either at the home directory level of the Web site or at a subdirectory level of the Web site. For more information and a figure that shows the relationships among objects in the Commerce Server Manager and IIS consoles, see Using Commerce Server and IIS.

An application represents the Web address that a Web client accesses. When you add an application to Commerce Server, the Administration database is updated with the configuration data for the application. When you add a Web server to the application, the ASP files are installed on the Web server computer.

When a Commerce Server site is unpacked, it typically installs two applications: one for the Web site that users access to browse and purchase products, and one for the Commerce Server Business Desk used to manage that site. An application can use only the resources of the site it is belongs to.

An application includes its own Web servers, which in turn serve the ASP page content for the Web site. An application may include multiple Web servers; it always includes at least one Web server. You can set up an application at the root level of an IIS Web site or at a virtual directory any number of levels below the root.

You can perform the following functions from the IIS and Commerce Server Manager consoles:

  • From the application node in the IIS snap-in, you can set all properties available at the virtual directory level, including virtual directory properties, default documents, directory security, Hypertext Transfer Protocol (HTTP) headers, and custom errors. You can also configure Microsoft FrontPage Server Extensions and rename or delete the application.

  • From the application node in Commerce Server Manager, you can set the nonsecure and secure host name and IIS application path, enable HTTPS, enable Autocookie, enable an Authentication filter, and configure settings common to all Web servers in the application.

For detailed information about properties that are inherited from IIS to Commerce Server, see Using Commerce Server and IIS.

See Also

Commerce Server Security

Using Site Packager

Example A: Installing on a Four-Computer Clustered Configuration

Example B: Installing on a Three-Computer Non-Clustered Configuration

Securing Your Site

Managing Commerce Applications and Web Servers


Web Servers

In Commerce Server, a Web server is a computer with Internet Information Services (IIS) 5.0 installed. To use a Web server with Commerce Server 2000, you must install Commerce Server on the same computer as IIS.

In Commerce Server, a Web server is associated with one or more applications; different applications can share the same Web server. The Web server contains the Active Server Pages (ASP) files and subfolders for the application. One application may have several Web servers that, taken together, form a Web farm.

To add ASP files to a Web server, you use the Commerce Server Site Packager to unpack the Web server. The Commerce Web server object is added to the application when unpacking is complete. In Commerce Server Manager, a Web server object is exposed under the associated application.

The Web server object contains properties needed by the Data Warehouse to import log files. When a Web server is added, the following properties in IIS are automatically populated the Commerce Server Administration database.

Property | Description
Server name | The name of the computer on which IIS is installed.
IP Address | The Internet Protocol (IP) address for the IIS Web site of the application.
Log file path | The path to which the IIS Web site of the application is to write events, for example, C:\Winnt\System32\LogFiles\Log1.
Log file period | The length of time the IIS Web site of the application will retain the log file before it overwrites the data.

From the Web server node in Commerce Server Manager, you can view or change these properties. If you change the properties in Commerce Server Manager, you must manually change them in IIS. If you change the properties in IIS, you can use the Synchronize Values button in Commerce Server Manager to copy the new values from IIS to Commerce Server.

Commerce Server supports Web servers that are not running IIS and do not include Commerce Server components. This enables you to make the Web server log files available to the Data Warehouse for import. For more information, see Adding a Non-Commerce Application and Web Server.

It is possible that different applications might share a Web server. Each application has a unique URL; a single IIS Web site can serve unique URLs. For example, the same IIS Web site could serve both www.microsoft.com and www.microsoft.com/commerceserver.

If you are running a Web farm, you need to replicate your Web servers. It is recommended that you use Microsoft Application Center 2000 or another product to perform content replication.

See Also

Setting Up Your Web Servers

Adding a Web Server to an Application

Adding Another Web Server

Adding a Non-Commerce Application and Web Server

Configuring a Web Server

Running the Data Warehouse


About Commerce Server Databases

The following table lists the databases that are typically used in a Commerce Server site. Depending on the features and configuration you choose for your site, you may have additional databases, or fewer databases.

You specify the connection strings for these databases during Setup and the unpacking process. However, you can change the connection strings using Commerce Server Manager.

Database and name | Description
Commerce Server <site name>_commerce | Data for catalogs, campaigns, transactions, profiles, and events.
Administration MSCS_Admin | Configuration data used by Commerce Server.
Data Warehouse <site name>_dw | Day-to-day operational data about users who visit your site: user profile data, transaction data, and click-history data. This data is imported from Web logs and other Commerce Server databases using Commerce Server Data Transformation Services (DTS) tasks.
Direct Mailer | Data for mailing lists, messages, and events.

See Also

Maintaining Commerce Server

Database Table Reference

Working with the Data Warehouse


Setting Database Connection Strings

Commerce Server connection strings, including the login user names and passwords, are stored in the Administration database.

Note

  • All Commerce Server connection strings use Microsoft SQL Server security. However, the connection string for the Data Warehouse resource to the online analytical processing (OLAP) server database only supports Microsoft Windows NT Authentication.

Commerce Server uses connection strings for the following databases:

  • Administration database and Direct Mailer database. During Setup, you enter the login user names and passwords for the Administration database and Direct Mailer database. You can change these at a later date using Commerce Server Manager.

  • Databases used by resources. When you unpack a site using Commerce Server Site Packager, for some resources you are prompted for a connection string to the appropriate database. The following table lists the connection strings for each resource.
    Resource | Connection string
    Product Catalog | Catalog Database
    Campaigns | Campaigns Database
    Transactions | Transactions Database
    Transaction Config | Transactions Config Database
    Profiles | s_BizDataStoreConnectionString, s_CommerceProviderConnectionString, s_ProfileServiceConnectionString
    Data Warehouse | The connection string is not named in the user interface because Data Warehouse has its own snap-in extension.

  • Other databases. You also specify connection strings in the following cases:
    Feature | Connection string
    App Default Config resource: Integrating with BizTalk Server | Set the connection string to the BizTalk Interchange Manager database, which stores messages sent from Commerce Server.
    List Manager: Importing and exporting lists | In the List Manager module in Commerce Server Business Desk, set the connection string for the SQL Server database table you are importing or exporting.
    Migration ProfileBuilder Tool | After you modify Migration ProfileBuilder, create a Data Source Name (DSN) for the Commerce Server Profiles data store.
    Profiles resource: Adding data sources | Use the data source picker (and for the Lightweight Directory Access Protocol (LDAP) , the LDAP connection string dialog) to enter the connection strings for the databases and LDAP sources you are mapping data source partitions to.
    Predictor resource | Enter the connection string for an external database, not for the Data Warehouse.

If you need to change a connection string for a database, use Commerce Server Manager.

To change the connection string for the Administration database

To change the connection string for a global resource

To change the connection string for a site resource

To change the connection string for the Administration database

  1. Right-click Commerce Server Manager, and then click Properties. The Commerce Server Manager Properties dialog box appears.

  2. In the Administration Database tab, click Modify. The Data Link Properties dialog box appears.

  3. After making the necessary changes in the Data Link Properties dialog box, click OK.

    For information about how to complete the Data Link Properties dialog box, click Help in the Data Link Properties dialog box to open the Microsoft Data Link Help file.

Note

  • After you change a property value in Commerce Server Manager, you must unload the IIS applications in the site from memory on each Web server in order for the change to take effect. For instructions, see Unloading an Application from Memory.

To change the connection string for a global resource

Because the Data Warehouse global resource has its own snap-in extension with a different user interface, this procedure does not apply. For instructions about changing the Data Warehouse connection string, see Configuring the Data Warehouse Resource.

  1. Expand Commerce Server Manager, and then expand Global Resources.

  2. Right-click the global resource to be configured, and then click Properties.

  3. Select the Connection Strings tab to configure the connection strings for the global resource, select a connection string, and then click Modify. The Data Link Properties dialog box appears.

  4. After making the necessary changes in the Data Link Properties dialog box, click OK.

Note

  • After you change a property value in Commerce Server Manager, you must unload the IIS applications in the site from memory on each Web server in order for the change to take effect. For instructions, see Unloading an Application from Memory.

To change the connection string for a site resource

  1. Expand Commerce Server Manager, expand Commerce Sites, and then expand the site you want to administer.

  2. Expand Site Resources, right-click the site resource to be configured, and then click Properties.

  3. In the Properties dialog box, select the Connection Strings tab, select a connection string, and then click Modify. The Data Link Properties dialog box appears.

  4. After making the necessary changes in the Data Link Properties dialog box, click OK.

Note

  • After you change a property value in Commerce Server Manager, you must unload the IIS applications in the site from memory on each Web server in order for the change to take effect. For instructions, see Unloading an Application from Memory.

See Also

Connection Strings for the Data Warehouse

Connection Strings for the Profiling System

Code to Connect to the Expression Store

Code to Retrieve the Database Connection String

Code to Connect to the Profile Store


Using Commerce Server and IIS

The system administrator, who is responsible for the day-to-day administration of Commerce Server 2000, is typically also responsible for administering Internet Information Services (IIS) 5.0.

Although Commerce Server depends on IIS, the relationship between IIS and Commerce Server objects is not strictly hierarchical. The total set of properties that affect a Commerce Server site includes properties that are:

  • Set at the IIS level only.

  • Set within Commerce Server only, independent from IIS.

  • Inherited from IIS.

You use the IIS snap-in to manage Web site access permissions and security, performance, directories and paths, the identification of Web site names, and Internet Protocol (IP) addresses and ports.

You use Commerce Server Manager to perform the following tasks:

  • Manage global and site Commerce Server resources, configure Commerce Server-specific properties, configure database connection strings for resources, and add and remove Web servers from an application.

  • At the Commerce Server application level, specify the IIS application path, IIS Web site, non-secure and secure host names, and IP port and secure IP port. You can also configure properties to enable Hypertext Transfer Protocol (HTTP), enable Autocookie mode, and select an authentication filter. These properties apply to all of the Web servers used by the application.

    When you change port properties using Commerce Server Manager, the properties are not automatically changed in IIS; you must manually change them in IIS. When you change the port properties in IIS, you must also change them in Commerce Server. The following port properties in IIS are the ones actually used:

    At the application level

    • Transmission Control Protocol (TCP) port

    • Secure Sockets Layer (SSL) port

    At each Web server

    • Internet Protocol (IP) address

    • Log file path

    • Log file period

    Web server properties are inherited from IIS and stored in the Administration database for ease of access. If you change the properties in IIS, you need to synchronize the Commerce Server Administration database with IIS either by manually updating the new values in Commerce Server Manager, or by clicking the Synchronize Values button on the Web Servers tab in the Application Properties dialog box. For more information, see Configuring an Application.

    When you click Synchronize values, Commerce Server copies the properties from IIS at the application level and the properties for all the Web server objects below the application. For the properties at the application level (TCP port and SSL port), Commerce Server reads the values for the first Web server. It assumes that the Web servers have all been configured identically, which must be the case for a Web farm to operate correctly.

  • At the Commerce Server Web server level, view and change properties for the Internet Protocol (IP) address, log file path, and log file period.

    The following figure shows the objects on the IIS and Commerce Server Manager console trees, and the relationships of these objects.

    A figure illustrating the relationships between objects in IIS and Commerce Server Manager

    Click the illustration to enlarge or reduce.

See Also

Configuring an Application

Adding a Non-Commerce Application and Web Server

Integrating Custom Resources

Using Site Packager


About Data Transformation Services (DTS)

Commerce Server includes several Data Transformation Services (DTS) tasks that you use to import data into the Data Warehouse. DTS is a feature of Microsoft SQL Server. It provides the functionality to import, export, and transform data between Microsoft SQL Server and any OLE DB, Open Database Connectivity (ODBC), or text file format. For example, importing catalog data from the Catalog database to the Data Warehouse is a DTS task. After you import data into the Data Warehouse, business managers can use the Analysis modules in Commerce Server Business Desk to analyze the data.

For detailed information about using the Commerce Server DTS tasks, see Running the Data Warehouse.

The following table lists the DTS tasks included with Commerce Server.

Commerce Server 2000 DTS tasks | Description
Web server log import | Defines and imports Web log files. You use this task to set Web log file properties that determine the data that is imported from a Web log file, and how individual users and visits are distinguished.
Configuration synchronization | Synchronizes the Data Warehouse with Commerce Server Business Desk after you make changes to the configuration settings. This task must be performed before every import task.
Transaction data import | Defines and imports transaction data. You use this task to select the type of transaction data you want to import into the Data Warehouse.
Data deletion | Deletes detailed log file data and summarized data from the Data Warehouse. You delete log file data to reduce the size of the Data Warehouse. You delete all data, detailed and summarized, if you have imported test data and want to empty the Data Warehouse before importing valid data.
Product catalog import | Imports catalog data. Catalog reports using imported catalog data contain more descriptive product information than those using transaction data.
User profile data import | Imports user profile data. User profile data is defined with user profiles that are created in the Profiles resource, and is used to collect personal information from users who register on your Web site.
IP resolution | Resolves Internet Protocol (IP) addresses from the imported user data. IP resolution converts IP addresses, imported from your log files, into domain names. For example, the IP address 198.105.232.4 becomes www.microsoft.com. This helps readers more readily understand the data contained in your reports.
Campaign data import | Imports data about marketing campaigns. You use campaign data to analyze the success of your marketing campaigns.
Report preparation | Populates OLAP cubes with the import data, prepares the data for report generation, and cleans up after a delete. This task must be performed after every import and delete task.

For more information about DTS tasks, see SQL Server Books Online.

See Also

Running the Data Warehouse


Installing Administration Tools Only

After you have installed Commerce Server 2000 on at least one computer, you can also set up an administration-only console on a separate computer. An administration-only computer includes only Commerce Server Manager, and it connects to the existing Administration database.

You may want to use an administration-only computer if:

  • You want to use your existing computer with minimal installation. An administration-only computer has fewer software and configuration requirements than those for a full Commerce Server installation. It can run Microsoft Windows 2000 Professional rather than Microsoft Windows 2000 Server.

  • You want the option of administering Commerce Server from different locations. Administration-only computers must be in the same domain or trusted domain as Commerce Server.

An administration-only computer must meet the following requirements:

  • Microsoft Windows 2000 Professional, Server, or Advanced Server installed

  • 20 MB of hard disk space available

  • Connectivity to the existing Administration database

To install Administration tools only

To enable administration through a proxy server or firewall

To install Administration tools only

  1. Insert the Commerce Server 2000 compact disc into your disc drive, and run the Commerce Server 2000 Setup program. Accept the license agreement, type your customer information, and accept the default destination folder.

  2. In the Setup Type dialog box, select Custom, and then click Next.

  3. In the Custom Setup dialog box, select the Administration Tools option, and then select Not installed for the other options. Click Next.

  4. In the Administration Database Configuration dialog box, type the name of the computer on which you want to store the administration database in the SQL Server computer box. Type the SQL Server login user name and password to connect to the Administration database. Then click Next.

  5. In the Services Accounts dialog box, type the Windows user name and password of the Event Logging account, and then click Next.

  6. In the Ready to Install dialog box, click Install.

    Commerce Server Setup installs the administration tools on this computer. You can use this computer to manage your Commerce Server installation.

  7. Click Finish to exit the Setup program.

Commerce Server Manager is installed on your computer.

To enable administration through a proxy server or firewall

  • Open port 1433 between SQL Server and the Administration-only computer.

By default, SQL Server listens on port 1433. For instructions about changing the port number, see SQL Server Books Online.

Note

  • Although you can use Commerce Server Manager through a proxy or firewall, you cannot use Internet Services Manager through a proxy or firewall. To add IIS administration capability to an administration-only computer located on the far side of a firewall, you can use the browser-based IIS or Microsoft Terminal Services. For more information about using IIS, see the IIS 5.0 documentation. For information about using Terminal Services, see "Client Services" in the Windows 2000 documentation.

See Also

Installing Commerce Server


Managing the Administration Database

Your Commerce Server 2000 site may consist of multiple computers, however, the configuration data for the resources for all computers is stored centrally in a single SQL Server Administration database named MSCS_Admin. This database is created automatically when you first install Commerce Server. During Setup, you must specify the SQL Server computer for the Administration database.

When you install Commerce Server on additional computers, you point the computers to the Administration database during Setup. By setting up all the computers to point to this central database, you can manage all the Commerce Server computers from a central console.

Note

  • A single Administration database can be used by all Commerce Server computers. Alternatively, each computer can use its own Administration database.

The following table shows the typical location of the Administration database in different environments.

Type of environment | Typical location of Administration database
Single server containing Commerce Server, Microsoft SQL Server, and all Web components | On the single server
One or more Web servers and one database server | On the SQL Server computer
Multi-tier, multi-server environment | On one of the SQL Server computers (for optimal performance, separate from the Data Warehouse)

This section contains:

  • Configuring the Administration Database

  • Interaction Between Sites and the Administration Database

  • Managing Security on the Administration Database


Configuring the Administration Database

When you install Commerce Server 2000, Setup automatically configures your server with the connection string for the Administration database. However, you may need to change the connection string, if, for example, the SQL Server login user name or password for the Administration database is changed.

Note

  • When Commerce Server Manager cannot connect to the Administration database, the root node for Commerce Server Manager appears in the scope pane in the Microsoft Management Console (MMC), but the rest of the Commerce Server hierarchy does not appear. To provide the correct connection string, you must configure Commerce Server Manager.

To configure Commerce Server Manager

  1. Right-click Commerce Server Manager, and then click Properties. The Commerce Server Manager Properties dialog box appears.

  2. In the Administration Database tab, click Modify. The Data Link Properties dialog box appears.

  3. After making the necessary changes in the Data Link Properties dialog box, click OK.

    Note

    • For information about how to complete the Data Link Properties dialog box, click Help in the Data Link Properties dialog box to open the Microsoft Data Link Help file.

See Also

Setting Up Your Database Servers

Securing Your Site

Troubleshooting Commerce Server


Interaction Between Sites and the Administration Database

The Administration database is accessed by three COM objects: SiteConfig, GlobalConfig, and SiteConfigReadOnly. The following figure shows how these Config objects facilitate communication between sites and the Administration database.

A figure illustrating how Config Objects update the Administration database
Applications
<computername>
/RetailBusinessDesk
<computername>/Retail
Applications
Applications
Web Pages
Web Pages
Config Objects
Site 2
Site 1
Administration Database:
SCS_Admin
Site 2
Site 1

The Config objects write data to the Administration database. They also get data from the database that is then used by the applications. For information about programming with the Config objects, see Programmer's Reference.

See Also

Setting Up Your Server Platforms

Securing Your Site

Managing Security on the Administration Database


Managing Security on the Administration Database

The Administration database connection string uses a Microsoft SQL Server login user name and password.

During Commerce Server installation, Setup prompts you for an existing SQL Server login name and password that Setup uses to create the Administration database on the SQL server or to connect to the database if it already exists.

After the Administration database is created, you can use Microsoft SQL Server Enterprise Manager to change the SQL Server login and password for the Administration database. If you want to use a different SQL Server login to connect to the Administration database from the Commerce Server computer, you must use Commerce Server Manager to change the connection string to the database.

For security purposes, do not use the "sa" login for access to the Administration database. Instead, use SQL Server Enterprise Manager to create a new login and user for the Administration database.

To change the SQL Server login user name and password for the Administration database

  1. Right-click Commerce Server Manager, and then click Properties. The Commerce Server Manager Properties dialog box appears.

  2. In the Administration Database tab, click Modify. The Data Link Properties dialog box appears.

  3. After making the necessary changes in the Data Link Properties dialog box, click OK.

    Note

    • For information about how to complete the Data Link Properties dialog box, click Help in the Data Link Properties dialog box to open the Microsoft Data Link Help file.

See Also

Securing Your Site

Maintaining Commerce Server


Managing Commerce Resources

There are two types of resources: global resources and site resources. Third parties can develop custom global resources and site resources to work with Commerce Server. Use the procedures in this section to install, add, and configure Commerce Server resources.

This section contains:

  • Installing and Uninstalling Global Resources. Explains how to install and uninstall a global resource.

  • Adding a Global Resource Pointer to a Site. Explains how to add a global resource pointer to a site.

  • Adding a Resource to a Site. Explains how to add a resource to a site.

  • Configuring a Global Resource. Explains how to configure a global resource.

  • Configuring a Site Resource. Explains how to configure a site resource.

  • Configuring App Default Config Resource Properties. Explains how to configure the App Default Config resource.

  • Changing a Service Account or Password. Explains how to change an account or password for Predictor, Direct Mailer, Event Logging, and List Manager.

  • Deleting a Resource from a Site. Explains how to delete a resource from a site.


Installing and Uninstalling Global Resources

You use the Microsoft Commerce Server 2000 Setup program to install and uninstall Predictor and Direct Mailer, two of the global resources in Commerce Server. Other global resources are created during the unpacking process.

After you install Predictor and Direct Mailer, you must unpack these resources in order for a site to use them. When you unpack an application, you set the global resource pointers for the site to Predictor and Direct Mailer. For instructions about adding and deleting global resource pointers from a site, see Adding a Global Resource Pointer to a Site and Deleting a Resource from a Site.

For more information about installing and deploying Predictor and Direct Mailer, see Deploying Your Site.

Note

  • In the initial release of Commerce Server 2000, you cannot install Direct Mailer to a SQL Server virtual cluster. Install Direct Mailer to a physical node of the SQL Server virtual cluster using the name of the physical computer, and use a SQL Server instance that is separate from the virtual instance.

To install Predictor or Direct Mailer

  1. Insert the Commerce Server 2000 CD, and run the Commerce Server 2000 Setup program. Accept the license agreement, type your customer information, and choose the destination folder.

  2. In the Setup Type dialog box, select Custom (or Modify if you have already installed Commerce Server on this computer), and then click Next.

  3. In the Custom Setup dialog box, under the Run-time Objects folder, select the Predictor Service or Direct Mailer Service option, and then select Not installed for the other options. Click Next.

  4. In the Direct Mailer Database Configuration dialog box, type the name of this computer in the SQL Server Computer box. Type the SQL server login user name and password to use when creating the Direct Mailer database. Then click Next.

  5. In the Services Accounts dialog box, type the Windows user name and password of the account under which the services will run. Then click Next.

    Note

    • Use a permanent account. If this account is disabled at a later date, or if the password is changed, Commerce Server will stop working. For instructions about changing a service account or password, see Changing a Service Account or Password.
  6. In the Ready to Install dialog box, click Install.

    Commerce Server Setup installs Predictor and/or Direct Mailer onto the computer.

  7. Click Finish to exit the Setup program.

To uninstall Predictor or Direct Mailer

  1. Insert the Commerce Server 2000 compact disc into your disc drive, and run the Commerce Server 2000 Setup program. Accept the license agreement, type your customer information, and accept the default destination folder.

  2. In the Setup Type dialog box, select Modify, and then click Next.

  3. In the Custom Setup dialog box, verify that the feature you want to remove, Predictor Service or Direct Mailer Service, is not selected (the checkbox should have an X in it, indicating that you are not selecting it). Click Next.

  4. In the Ready to Install dialog box, click Install.

    Commerce Server Setup removes Predictor and/or Direct Mailer from the computer.

  5. Click Finish to exit the Setup program.

See Also

Deploying Your Site

Adding a Global Resource Pointer to a Site

Deleting a Resource from a Site

Installing Commerce Server

Uninstalling Commerce Server


Adding a Global Resource Pointer to a Site

After you have used the Commerce Server 2000 Setup program to install a global resource, you can add a pointer to the resource to any site in your Commerce Server Administration database. To add a global resource pointer to a site, you unpack the global resource pointer from a Commerce Server Site Packager file.

For example, after you install Predictor and Direct Mailer, you unpack a site that includes the Predictor and Direct Mailer resources. When you unpack the site, you set the global resource pointers for the site to Predictor and Direct Mailer.

Notes

  • Before performing this procedure, you must create a package file, or use one of the Solution Site packages that contains the global resource pointer you want to add to the site. For instructions about creating a package, see Using Site Packager.

  • If you unpack the Direct Mailer resource after you unpack a Commerce Server Business Desk application and install a Business Desk client, you must restart Internet Information Services (IIS) 5.0 on the Web server hosting the Business Desk application in order for the addition of Direct Mailer to be detected. Business Desk clients must re-connect to the application. For instructions about restarting IIS, see Restarting IIS.

To add a global resource pointer to a site

  1. Expand Commerce Server Manager, expand Commerce Sites, and then expand the site you want to administer.

  2. Click Site Resources, right-click Site Resources, point to New, and then click Add Resource.

    The Open dialog box appears.

  3. Select the package that contains the global resource pointer you want to add to the site, and then click Open.

    The Commerce Server Site Packager is started.

  4. In the Select Resources dialog box, select the global resource you want from the Available resources box, and then click Add. The resource appears in the Resources to unpack box. Click Next.

  5. In the Global Resource Pointers dialog box, verify that the resource points to the appropriate global resource. You can create some types of new global resources from this screen. To do so, select Create New Global Resource when mapping the global resource pointer.

  6. In the Database Connection Strings dialog box, Site Packager lists the databases it will create and the servers on which it will create them.

  7. If you need to create a new database for your global resource, click New Database.

    In the SQL Server computer box, type the name of the computer that will contain the database. In the Database name box, type the name you want for the database. In the remaining boxes type a SQL Server login user name and password, and then click Create database.

  8. When you are returned to the Database Connection Strings dialog box, select a connection string, and then click Modify.

  9. In the Data Link Properties dialog box, make the necessary changes, and then click OK.

    Note

    • For information about how to complete the Data Link Properties dialog box, click Help in the Data Link Properties dialog box to open the Microsoft Data Link Help file.
  10. Click Next.

  11. In the Unpacking is complete dialog box, review the log file of the unpacking process, and then click Finish.

The global resource pointer appears under the site in Commerce Server Manager.

See Also

Administration Basics

Using Site Packager

Example A: Installing on a Four-Computer Clustered Configuration

Example B: Installing on a Three-Computer Non-Clustered Configuration

Deleting a Resource from a Site

Installing Commerce Server


Adding a Resource to a Site

To add a resource to a site, you unpack the resource from a package file.

Note

  • Before performing this procedure, you must create a package file, or use a Solution Sites package, that contains the resource you want to add to the site. For instructions about packaging a resource and creating a package file, see Using Site Packager.

  • If you unpack the Direct Mailer resource after you unpack a Commerce Server Business Desk application and install a Business Desk client, you must restart Internet Information Services (IIS) 5.0 on the Web server hosting the Business Desk application in order for the addition of Direct Mailer to be detected. Business Desk clients must re-connect to the application. For instructions about restarting IIS, see Restarting IIS.

To add a site resource

  1. Expand Commerce Server Manager, expand Commerce Sites, and then expand the site you want to administer.

  2. Click Site Resources, right-click Site Resources, point to New, and then click Add Resource.

    The Open dialog box appears containing a list of existing Site packages.

  3. Select the package that contains the resource you want to add to the site, and then click Open.

    The Commerce Server Site Packager is started.

  4. In the Select Resources dialog box, select the resource you want from the Available resources box, and then click Add. The resource appears in the Resources to unpack box. Click Next.

  5. In the Global Resource Pointers dialog box, verify that the resource points to the server containing the appropriate global resource. You can create some types of new global resources from this screen. To do so, select Create New Global Resource when mapping the global resource pointer.

    Site Packager lists the connection string properties of new global resources you are adding. It will not list the connection string properties if the resource you are adding is not a global resource pointer.

  6. In the Database Connection Strings dialog box, Site Packager lists the databases it will create and the servers on which it will create them.

  7. If you need to create a new database for your global resource, click New Database.

    In the SQL Server computer box, type the name of the computer that will contain the database. In the Database name box, type the name you want for the database. In the remaining boxes type the SQL Server login user name and password, and then click Create database.

  8. When you are returned to the Database Connection Strings dialog box, select a connection string, and then click Modify.

  9. In the Data Link Properties dialog box, make the necessary changes, and then click OK.

    Note

    • For information about how to complete the Data Link Properties dialog box, click Help in the Data Link Properties dialog box to open the Microsoft Data Link Help file.
  10. Click Next.

  11. In the Unpacking is complete dialog box, review the log file of the unpacking process, and then click Finish.

The resource appears under the site in Commerce Server Manager.

See Also

Resources

Using Site Packager

Example A: Installing on a Four-Computer Clustered Configuration

Example B: Installing on a Three-Computer Non-Clustered Configuration

Configuring a Site Resource

Deleting a Resource from a Site


Configuring a Global Resource

After a global resource is installed, you can change the properties and the database connection strings used by the global resource at any time.

Note

  • When you change the properties or the database connection string for a global resource by using Commerce Server Manager, changes may not be reflected immediately in Commerce Server Business Desk or in the Web pages of the applications using the global resource. To refresh these changes, use the Internet Information Services (IIS) 5.0 snap-in to unload IIS applications on the Web servers used by the applications. For instructions, see Unloading an Application from Memory.

To configure a global resource

  1. Expand Commerce Server Manager, and then expand Global Resources.

  2. Right-click the global resource to be configured, and then click Properties.

  3. In the <global resource> Properties dialog box, select the Properties tab to configure the properties for the global resource.

  4. For each property you want to configure, select the property, and then type the value in the Selected Property Value box.

  5. Select the Connection Strings tab to configure the connection strings for the global resource, and then click Modify. The Data Link Properties dialog box appears.

    Note

    • For information about how to complete the Data Link Properties dialog box, click Help in the Data Link Properties dialog box to open the Microsoft Data Link Help file.
  6. After making the necessary changes in the Data Link Properties dialog box, click OK.

The global resource you selected is now configured.

Note

  • After you change a property value in Commerce Server Manager, you must unload the IIS applications in the site from memory on each Web server in order for the change to take effect. For instructions, see Unloading an Application from Memory.

See Also

Resources

Configuring a Site Resource

Unloading an Application from Memory


Configuring a Site Resource

After a site resource is added to a site, you can change the properties used by the site resource at any time. All site resources used by a site expose an object at the site level.

Note

  • Global resources that are used by a site expose an object at the site level (a global resource pointer); however, the only property that the object exposes is a pointer to the associated global resource. For information about configuring global resources, see Configuring a Global Resource.

To configure a site resource

  1. Expand Commerce Server Manager, expand Commerce Sites, and then expand the site you want to administer.

  2. Expand Site Resources, right-click the site resource to be configured, and then click Properties.

  3. In the Properties dialog box, select the property you want to configure, and then type the value in the Selected Property Value box.

  4. When you are finished configuring the properties for the site resource, click OK.

Note

  • After you change a property value in Commerce Server Manager, you must unload the IIS applications in the site from memory on each Web server in order for the change to take effect. For instructions, see Unloading an Application from Memory.

See Also

Resources

Configuring a Global Resource


Configuring App Default Config Resource Properties

The App Default Config resource has properties that affect the functionality of your site and Commerce Server Business Desk. For example, you use the App Default Config properties to specify the currencies you support, and to specify payment optionswhen you set up Commerce Server to integrate with Microsoft BizTalk Server 2000.

For information about configuring App Default Config to use BizTalk Server, see Configuring Commerce Server to Work with BizTalk Server. For information about localizing a site, see Modifying Your Site for an International Audience.

To configure the App Default Config resource

  1. Expand Commerce Server Manager, expand Commerce Sites, and then expand the site you want to administer.

  2. Right-click App Default Config, and then click Properties.

  3. In the Properties tab, do the following:
    Use this | To do this
    Add item redirect options | Specify the site functionality that occurs after a user adds an item to the basket. Type 1 to continue displaying the current product page; type 0 to redirect to the basket page.
    Address Book Options Specify whether the site supports an address book feature.

    Type 0 to disable the address book.

    Type 1 to make the address book read-only. If you have a predefined address book, you may want to choose this option.

    Type 2 to make the address book read/write, so that users can add and change addresses.
    AuthManager Auth Ticket Timeout | Type the number of minutes after which the ticket times out. This property is used only if you are developing your site based on a Commerce Server Solution Site.
    BizTalk Catalog Doc Type | Type the document definition name that is required by BizTalk Server for catalogs (for example, CatalogTransferDoc).
    BizTalk Options | Type 1 to enable integration with BizTalk Server to exchange documents; type 0 to disable integration.
    BizTalk PO Doc Type | Type the document definition name that is required by BizTalk Server for purchase orders (for example, PurchaseOrder).
    BizTalk Source Org Qualifier | Type the alias qualifier for this site in BizTalk Server (for example, MyCompany).
    BizTalk Source Org Qualifier Value | Type the alias value for this site in BizTalk Server (for example, Sender).
    BizTalk Submit type | Type 1 to submit documents to BizTalk Server asynchronously.
    Cookie Path Correction Options | Type 1 to enable application-based correction; type 2 to enable filter-based correction.
    Currency: Alternate currency code | Type the ISO 4217 code for the alternate currency.
    Currency: Alternate currency conversion rate | Type the rate used to convert between the base and alternate currency.
    Currency: Alternate currency locale | Type the locale for the alternate currency (1031 = German, 1033 = English, 1034 = Spanish, 1036 = French, 1041 = Japanese).
    Currency: Alternate currency options | Type 1 to display two currencies simultaneously; type 0 to disable this feature.
    Currency: Alternate currency symbol | If you are using an alternate currency, enter its symbol.
    Currency: Base currency code | Type the ISO 4217 code for the base currency.
    Currency: Base currency locale | Type the locale for the base currency (1031 = German, 1033 = English, 1034 = Spanish, 1036 = French, 1041 = Japanese).
    Currency: Base currency symbol | Type the symbol for the base currency.
    Currency display order options | If you use an alternate currency, type 0 to display the base currency first; type 1 to display the alternate currency first.
    Delegated admin options Type 1 to enable Partner Services; type 0 to disable it.

    To create a delegated administrator, in the Users module in Commerce Server Business Desk, you must create a user with the Partner service role flag set to "Administrator," and then associate the user with a specific organization.

    Delegated administrators have a Partner Services link on their site. Partner Services enables them to perform certain tasks for their organization, such as managing users and reviewing orders.
    Form login options Type one of the following to specify when users are required to log in to your site:

    0 = Disable login. Users can enter the site only as a guest.

    1 = Required when a user enters the site.

    2 = Optional when a user enters the site.

    5 = Required at the time of purchase.

    6 = Optional any time.

    7 = Require IIS authentication.

    This property is used only if you are developing your site based on a Commerce Server Solution Site.
    Host Name Correction Options | Type 1 to enable host name correction; type 0 to disable this feature.
    Page encoding charset | Specify the document encoding character set for the site, for example, Windows - 1252.
    Payment options | Type 1 if users will pay for their orders using a credit card; type 4 if users will have their accounts billed; type 5 to support both options.
    Site default locale | Type the locale for this site (1031 = German, 1033 = English, 1034 = Spanish, 1036 = French, 1041 = Japanese).
    Site privacy options Type 1 to profile anonymous users; type 2 to profile and track anonymous user visits.

    This property is used only if you are developing your site based on a Commerce Server Solution Site.
    Site registration options | Type 1 to enable self-registration; type 2 to disable this feature. This property is used only if you are developing your site based on a Commerce Server Solution Site.
    Site ticket options | Type 1 to place the user ticket in the URL; type 2 to place the user ticket in the cookie. This property is used only if you are developing your site based on a Commerce Server Solution Site.
    SMTP server name | Type the computer name of the Simple Mail Transfer Protocol (SMTP) server.
    Unit of Measure for Weight | The unit of measure for calculating product shipping costs.

  4. In the Connection Strings tab, click Modify to specify the connection string to the BizTalk Interchange Manager database, which stores messages sent from Commerce Server.

  5. Click OK.

Notes

  • After you change a property value in Commerce Server Manager, you must unload the IIS applications in the site from memory on each Web server in order for the change to take effect. For instructions, see Unloading an Application from Memory.

  • For information about how the Solution Sites use the App Default Config authentication properties, see the Commerce Server 2000 Resource Kit.

See Also

Resources

Using BizTalk Server and Commerce Server

Managing the CS Authentication Resource

Integrating with BizTalk Server

Configuring Commerce Server to Work with BizTalk Server

Modifying Your Site for an International Audience


Changing a Service Account or Password

When you install Commerce Server, you specify Windows user names and passwords for the Commerce Server services: List Manager, Direct Mailer, Predictor, and a Windows account to use for Event Logging. If the password for one of these Windows accounts is changed or you want to change one of the Windows accounts being used, you need to specify this change in the Windows Services console. You must update the account and password there for each of the three services.

To change the account for Event Logging, you need to use the Component Services snap-in.

To change a service account or password

To change a service account or password for Event Logging

To change a service account or password

  1. Click Start, point to Programs, point to Administrative Tools, and then click Services.

  2. On the Services window, right-click the Commerce Server service for which you want to change the account name or password, and then click Properties.

  3. Click the Log On tab.

  4. On the Log On tab, do the following:
    Use this

            To do this

    This account Type the user name of the Windows account you want to use to authenticate this service. You must type the name in the following form:

    domain_name\user_name
    Password | Type the password for this user account.
    Confirm password | Retype the password for this user account.

  5. Click OK.

To change the account or password for Event Logging

  1. Click Start, point to Programs, point to Administrative Tools, and then click Component Services.

  2. Expand Component Services, expand Computers, expand My Computer, and then expand COM+ Application.

  3. Right-click Commerce Event Logging, and then click Properties.

  4. In the Identity tab, type the user name and password, and then click OK.


Deleting a Resource from a Site

If no applications are using a resource, you can delete the resource from your site.

The following table lists the results of deleting a resource from a site.

Resource | What does delete do?
App Default Config | Deletes the resource from the Administration database.
Profiles | Deletes the resource from the Administration database. Data in the Profiles database is not deleted.
Campaigns | Runs Schema_drop.sql, which deletes stored procedures, triggers, and drop tables. It also deletes the resource from the Administration database.
CS Authentication | Deletes the site reference to a CS Authentication global resource from the Administration database.
Data Warehouse | Deletes the site reference to a Data Warehouse global resource from the Administration database.
Commerce Server Direct Mailer | Deletes the site reference to a Direct Mailer global resource from the Administration database.
Predictor | Deletes the site reference to a Predictor global resource from the Administration database.
Product Catalog | Deletes the resource from the Administration database.
Transactions | Deletes the resource from the Administration database.
Transactions Config | Deletes the resource from the Administration database.

To delete a resource from a site

  1. Expand Commerce Server Manager, expand Commerce Sites, and then expand the site you want to administer.

  2. Right-click the resource to be deleted, and then click Delete.

Data for the resource is deleted from the Administration database. In Commerce Server Manager, the resource object no longer appears under the site. If you deleted a global resource pointer, the global resource it was pointing to is still available to other sites that are using it.

See Also

Resources

Adding a Resource to a Site


Managing Commerce Sites

The Commerce Sites container, as it appears in Commerce Server Manager, is created when you run Setup. Site instances are created for each site from a package and appear as subfolders within the container. You add sites and site resources by using Commerce Server Manager and Commerce Server Site Packager.

This section contains:

  • Adding a Site. Explains how to add a site to Commerce Server.

  • Deleting a Site. Explains how to delete a site from Commerce Server.


Adding a Site

After you have installed Microsoft Commerce Server 2000 on one computer, you can add a site to it.

Note

  • Before performing this procedure, you must create a package file that contains the site you want to add or use one of the Solution Site packages. For instructions about packaging a site, see Using Site Packager.

The following instructions assume that the user who is logged on has the appropriate permissions to copy files to the destination folders.

To add a site

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2000, and then click Commerce Site Packager.

    The Commerce Server Site Packager screen appears.

  2. Select Unpack from a package file, and then click Next.

  3. In the Unpack dialog box, click the Browse button next to the File to unpack box. The Open screen appears.

  4. In the Open dialog box, navigate to the folder that contains the file you want to unpack, select the file, and then click Open.

  5. When you are returned to the Unpack dialog box, select Quick unpack if you are going to put all of your database files on one SQL server. If you choose this option, click Next, and skip to step 13.

    Or select Custom unpack to customize all options for unpacking. Click Next.

  6. In the Unpack Method dialog box, select Create a new site, and then click Next.

  7. In the Site Name dialog box, type the name for the site, and then click Next.

  8. In the Select Resources dialog box, select the items you want to install, and then click Next.

  9. In the Global Resource Pointers dialog box, click Next.

    You use this screen to map to existing global resources or create new ones. You also use this dialog box when you have already unpacked global resources onto your computer and you now want to unpack global resource pointers in a site that will use those global resources.

  10. In the Database Connection Strings dialog box, Site Packager lists the databases it will create and the servers on which it will create them. Verify the databases, and then click Next.

  11. In the Select Applications dialog box, verify that the applications you want to unpack are selected, and then click Next.

  12. In the Select IIS Web Sites and Virtual Directories dialog box, verify that the IIS application paths and virtual directories are correct, and then click Next.

  13. If the Data Warehouse dialog box appears, click OK.

  14. If the first Profiling System dialog box appears, click Next, then click OK on the second Profiling System dialog box.

  15. In the Unpacking is complete dialog box, review the list of SQL databases and IIS applications that were created. To review the list of events in the Pup.log file, click View Log File.

  16. To close Site Packager, click Finish.

See Also

Administration Basics

Using Site Packager

Example A: Installing on a Four-Computer Clustered Configuration

Example B: Installing on a Three-Computer Non-Clustered Configuration

Backing Up Your Site

Troubleshooting Site Packager


Deleting a Site

When you delete a site, the site configuration data is deleted from the Administration database. After you delete a site, you cannot undo the deletion.

To delete a site

To delete the databases used by the site

To delete the OLAP databases for the site

To delete the virtual directories for the site

To delete the site folders and files

To delete the Direct Mailer jobs

To delete a site

  1. Expand Commerce Server Manager, and then expand Commerce Sites.

  2. Right-click the site to be deleted, and then click Delete.

To delete the databases used by the site

  1. Click Start, point to Programs, point to Microsoft SQL Server or Microsoft SQL Server 7.0 (depending on your installed database), and then click Enterprise Manager.

    Note

    • In SQL Server Enterprise Manager, make sure that SQL Server is running (the icon in the Enterprise Manager window displays a green light). If it is not running, right-click the name of the SQL Server computer, and then click Start.
  2. Expand the nodes to the following path: \Microsoft SQL Servers\SQL Server Group\SQL Server Name\Databases.

  3. Right click the database you want to delete, click All Tasks, and then click Detach Database. In the Detach Database dialog box, click Clear, and then click OK. Repeat this step for all of the databases you want to delete.

    By detaching the databases first, you can sever the connection strings you have to them.

  4. Right-click the databases used by the site, and then click Delete.

To delete the OLAP databases for the site

  1. Click Start, point to Programs, point to Microsoft SQL Server, point to Analysis Services, and then click Analysis Manager.

  2. Expand the nodes to the following path: \Analysis Servers\SQL Server Name.

  3. Right-click the database you want to delete, and then click Delete.

  4. Click Yes to confirm folder deletion for each database you want to delete.

  5. Repeat Steps 3 and 4 for each database you want to delete.

To delete the virtual directories for the site

  1. Click Start, point to Administrative Tools, and then click Internet Services Manager.

  2. Expand the nodes to the following path: \<computer name>\<IIS Web site name>.

  3. Right-click the virtual directories you want to delete (for example, Retail or Supplier), and then click Delete.

  4. Click Yes for each virtual directory you want to delete.

  5. Repeat Steps 3 and 4 for each virtual directory you want to delete.

To delete the site folders and files

  1. Using Windows Explorer, go to the directory (for example, C:\Inetpub\wwwroot) where the site files are installed.

  2. Right-click the folder you want to delete, and then click Delete.

  3. Click Yes for each folder you want to delete.

  4. Repeat Steps 2 and 3 for each folder you want to delete.

To delete the Direct Mailer jobs

  1. Click Start, point to Programs, point to Microsoft SQL Server or Microsoft SQL Server 7.0 (depending on your installed database), and then click Enterprise Manager.

  2. Expand the nodes to the following path: \Microsoft SQL Servers\SQL Server Group\SQL Server Name\Management\SQL Server Agent\Jobs.

  3. The Direct Mailer jobs appear in the right pane of the SQL Server Enterprise Manager.

  4. Select the Direct Mailer job(s) you want to delete, and then click the Delete button on the toolbar.

See Also

Uninstalling Commerce Server

Deleting a Resource from a Site

Deleting an Application from a Site

Removing a Web Server from an Application


Managing Commerce Applications and Web Servers

The topics in this section explain how to add and manage applications and Web servers. Before performing these procedures, you must install Commerce Server and unpack a site.

This section contains:

  • Adding an Application to a Site. Explains how to add an application to a site.

  • Configuring an Application. Explains how to configure an application.

  • Adding a Web Server to an Application. Explains how to add a Web server to an application.

  • Adding Another Web Server. Explains how to add additional Web servers to an application.

  • Configuring a Web Server. Explains how to configure a Web server.

  • Renaming an Application. Describes how applications are named in Commerce Server, and explains how to rename an application.

  • Unloading an Application from Memory. Explains how to unload an application from memory.

  • Deleting an Application from a Site. Explains how to delete an application from a site.

  • Removing a Web Server from an Application. Explains how to remove a Web server from an application.

  • Automatically Adding a Web Server. Explains how a Web server is added to an application automatically.

  • Adding a Non-Commerce Application and Web Server. Explains how to add a non-commerce application and Web server.


Adding an Application to a Site

An application is a Web site. An application represents the Web address that a Web client accesses. When you add an application to Commerce Server, the Administration database is updated with the configuration data for the application. When you add a Web server to the application, the Active Server Pages (ASP) files are installed on the Web server computer.

When a Commerce Server site is unpacked, it typically installs two applications: one for the Web site that users access, and one for the Commerce Server Business Desk used to manage that site. An application can use only the resources of the Commerce site it belongs to.

An application includes its own Web servers, which in turn serve the ASP page content for the Web site. An application may include multiple Web servers; it always includes at least one Web server. You can set up an application at the root level of an IIS Web site or at a virtual directory any number of levels below the root.

Note

  • Before performing this procedure, you must create a package file that contains the application you want to add to the site, or use one of the Solution Sites. For instructions about creating a package file, see Using Site Packager.

To add an application to a site

  1. Expand Commerce Server Manager, expand Commerce Sites, and then expand the site you want to administer.

  2. Click Applications, right-click Applications, point to New, and then click Add Application.

    The Add Application From dialog box appears.

  3. Select the package containing the applications you want to add to the site, and then click Open.

    Commerce Server Site Packager is started.

  4. In the Select Applications dialog box, verify that the applications you want to unpack are selected, and then click Next.

  5. In the Select IIS Web Sites and Virtual Directories dialog box, verify that the IIS application paths and virtual directories are correct, and then click Next.

  6. In the Unpacking is complete dialog box, review the list of SQL databases and IIS applications that were created. To review the list of events that occurred while Site Packager ran, click View Log File.

  7. To close Site Packager, click Finish.

After you add the application, you must change the non-secured (or secured) host name of your application to the domain name set up on the Domain Name System (DNS) server, for example, www.microsoft.com. For more information, see Renaming an Application.

See Also

Renaming an Application

Applications

Using Site Packager

Example A: Installing on a Four-Computer Clustered Configuration

Example B: Installing on a Three-Computer Non-Clustered Configuration


Configuring an Application

When you configure an application, you specify properties that apply to all the Web servers used by the application.

When you add a Web server to an application, some properties are automatically populated from Internet Information Services (IIS) 5.0 and stored in the Administration database. If the IIS properties change, then you need to synchronize the Administration database with the IIS metabase by manually updating the new properties in Commerce Server Manager or by clicking the Synchronize Values button on the Web Servers tab in the Properties dialog box of the application.

Important

  • When you click the Synchronize Values button, Commerce Server synchronizes the properties at the application level and the properties for all the Web server objects below the application. For the properties at the application level (Transmission Control Protocol (TCP) port and Secure Sockets Layer (SSL) port), Commerce Server reads the values of the first Web server. It assumes that all the Web servers are configured the same, which is a requirement for servers in a Web farm.

For information about changing the non-secured (or secured) host name of your application to the domain name set up on the Domain Name System (DNS) server (for example, www.microsoft.com), see Renaming an Application.

To configure an application

  1. Expand Commerce Server Manager, expand Commerce Sites, and then click the site you want to administer.

  2. Expand Applications, right-click the application you want to configure, and then click Properties.

  3. In the <application> Properties dialog box, on the General tab, do the following:
    Use this | To do this
    Nonsecure host name Type the DNS domain name to use for non-secured links in your applications.

    Caution

    • If you are using a port number other than 80, you must append that number to the end of the nonsecure host name (for example, www.microsoft.com:81). To view the port number you are using, see the TCP port box on the Web Servers tab.
    IIS application path | Type the path to the IIS application.
    Enable HTTPS | Select this property to enable links to a secure HTTP host (SSL) in your applications.
    Secure host name Type the DNS domain name to use for secured links in your applications.

    Caution

    • If you are using a port number other than 443, you must append that number to the end of the secure host name (for example, www.microsoft.com:441). To view the port number you are using, see the SSL port box on the Web Servers tab.
    Autocookie | Select this property to generate cookies for anonymous users. This property is set during the unpacking process. For more information about configuring authentication on your site, see Managing the CS Authentication Resource.
    Authentication filter Select the type of authentication filter you want to use from the drop-down list:
    • No filter

    • Windows Authentication

    • Custom Authentication

    For more information about configuring authentication on your site, see Managing the CS Authentication Resource.
    Set cookie path to Application | Select this option if you want to share cookies among the applications in a site.
    Number of shared domain levels | Specify how many domain levels applications need in common in order to share a cookie. For example, for premier.microsoft.com and msn.microsoft.com to share the microsoft.com cookie, set the value to 2.

  4. In the Web Servers tab, click Synchronize Values to copy the following properties from IIS to the Commerce Server Administration database.

    Important

    • When you click Synchronize Values, Commerce Server synchronizes the properties at the application level and the properties for all the Web server objects below the application. For the properties at the application level (TCP port and SSL port), Commerce Server reads the values of the first Web server. It assumes that all the Web servers are configured the same, which is a requirement for servers in a Web farm.

    Or, do the following:

    Use this | To do this
    IIS Web site | Type the name of the IIS Web site (for example, Default Web Site).
    TCP port | The default value is 80. If you have a value other than 80 here, you must type that value in the Nonsecure host name box on the General tab (for example, www.microsoft.com:81).
    SSL port | The default value is 443. If you have a value other than 443 here, you must type that value in the Secure host name box on the General tab (for example, www.microsoft.com:441).
    Local domain | Type the name of the local domain (for example, microsoft.com).

  5. Click OK.

Note

  • After you change a property value in Commerce Server Manager, you must unload the IIS applications in the site from memory on each Web server in order for the change to take effect. For instructions, see Unloading an Application from Memory.

See Also

Administration Basics

Configuring a Web Server

Managing the CS Authentication Resource

Renaming an Application


Adding a Web Server to an Application

When you add a Web server to an application, you are adding the .asp, .htm, .gif, and other files for the application to the Web server computer. The Web server computer must already have Internet Information Services (IIS) 5.0 and Commerce Server installed on it.

To add a Web server to an application, you can use Commerce Server Site Packager. After you add a Web server to an application, the Commerce Web server object appears under the application node in Commerce Server Manager. The Web server object contains the properties needed by the Data Warehouse in order to import log files: server name, Internet Protocol (IP) address, log file path, and log file period. These properties are automatically populated from IIS when you add a Commerce Web server object to an application.

You can also add a new Web server to an application without using Site Packager. Instead you can use Application Center Server to deploy the Commerce Server files to the Web server, or you can manually copy Commerce Server files to the Web server. For more information about adding Web servers to Commerce Server without using Site Packager, see Adding Web Servers Without Site Packager.

Notes

  • Make sure you have permissions on the computer you are unpacking onto.

  • Before performing this procedure, you must create a package file that contains the ASP files for the application, or use one of the Solution Sites. For instructions about creating a package file, see Using Site Packager.

To add a Web server to an application

  1. On the Web server computer that you want to add to the application, expand Commerce Server Manager, expand Commerce Sites, and then expand the site you want to administer.

  2. Expand Applications, click the name of the application to which you want to add the Web server, and then right-click the application. Point to New, and then click Add Web server.

    The Add Web Server From dialog box appears containing a list of Commerce Server Site Packager files (that is, files with a .pup extension).

  3. In the Add Web Server From dialog box, navigate to the folder that contains the file you want to unpack, select the file, and then click Open.

    Site Packager is started.

  4. In the Select IIS Web Sites and Virtual Directories dialog box, verify that the IIS application paths and virtual directories are correct, and then click Next.

    Site Packager adds the files to the Web server, and then adds the Commerce Web server object to the selected application. When you open Commerce Server Manager, the Commerce Web server object appears under the application.

  5. In the Unpacking is complete dialog box, review the list of SQL databases and IIS applications that were created. To review the list of events in the Pup.log file, click View Log File.

  6. To close Site Packager, click Finish.

See Also

Administration Basics

Configuring a Web Server

Adding Another Web Server


Adding Another Web Server

When you add another Web server to an application, you are not able to change any of the configuration information for the application during the unpacking process because all Web servers must have the same configuration. Commerce Server Site Packager displays the name of the Internet Information Services (IIS) 5.0 Web site where the application will be installed and the IIS application path for each Commerce application.

When you choose to unpack an application that already exists in the site in the Administration database, Commerce Server Site Packager assumes you are adding a Web server to that application.

See Also

Example A: Installing on a Four-Computer Clustered Configuration

Example B: Installing on a Three-Computer Non-clustered Configuration

Adding a Web Server to an Application


Configuring a Web Server

In Commerce Server Manager, the Commerce Web server objects contain properties needed by the Data Warehouse in order to import log files. When you add a Web server to an application, these properties are automatically populated from Internet Information Services (IIS) 5.0 and stored in the Administration database.

To configure a Web server

  1. Expand Commerce Server Manager, expand Commerce Sites, and then click the site you want to administer.

  2. Expand Applications, then expand the application that contains the Web server you want to configure. Right-click the Web server object and then click Properties.

  3. In the Properties dialog box, do the following:
    Use this | To do this
    Server name | Type the name of the computer on which the Web server is installed. Change the name only if you have renamed your server.
    IP Address | This box displays the Internet Protocol (IP) address for the Web server. This value is initially read from IIS.
    Log file path | Type the log file path to which the IIS Web site writes events, for example, C:\Winnt\System32\LogFiles\Log1. This value is initially read from IIS.
    Log file period | Select the log file period from the drop-down list. The log file period indicates how long the IIS Web site writes to a log file before it creates a new file. This value is initially read from IIS.

  4. Click OK.

See Also

Web Servers

Configuring an Application

Adding a Non-Commerce Application and Web Server


Renaming an Application

You must change the non-secured (or secured) host name of your application to the domain name set up on the Domain Name System (DNS) server, for example, www.microsoft.com. Commerce Server does not automatically read the domain name from DNS; instead, Commerce Server uses the computer name as the default domain name. You must provide the domain name to Commerce Server using the following procedure.

When you first unpack a site, your applications are named with the computer name (for example, Server1) and the Internet Information Services (IIS) 5.0 application paths that you specified during the unpacking process (for example, /msn). For example, the application name might be Server1/msn.

For each application in your site, you must rename the application with your domain name. For the application www.microsoft.com/msn, the domain name is www.microsoft.com and the IIS application path is /msn.

To rename an application

  1. Expand Commerce Server Manager, expand Commerce Sites, and then click the site you want to administer.

  2. Expand Applications, right-click the application you want to rename, and then click Properties.

  3. In the <site> Properties dialog box, on the General tab, do the following:
    Use this To do this
    Nonsecure host name Type the domain name, the same way it appears in your DNS server (for example, you might change it to "www.microsoft.com").

    Caution

    • If you are using a port number other than 80, you must append that number to the end of the nonsecure host name (for example, www.microsoft.com:81). To view the port number you are using, see the TCP port box in the Web Servers tab.
    IIS application path Type the path to the IIS application. For example, for the application www.microsoft.com/msn, the path would be /msn.

    Caution

    • If you change this property, you must change the location of the files on the Web server(s) to correspond to it. You must also configure IIS with the new application.

  4. Click OK.

Note

  • After you change a property value in Commerce Server Manager, you must unload the IIS applications in the site from memory on each Web server in order for the change to take effect. For instructions, see Unloading an Application from Memory.

See Also

Administration Basics


Unloading an Application from Memory

In Commerce Server, each site is an application under Internet Information Services (IIS) 5.0. After you change the value of a property in Commerce Server Manager, you must unload the IIS applications from memory on each Web server in order for the change to take effect. The caches created by the Commerce Server global.asa are released; when the next user visits your site, the resource properties are read again and loaded into the cache.

Unloading an application from memory is different from restarting IIS or using the IISReset command. You can unload an application without stopping the Web server.

You must unload an application from memory after performing any of the following tasks:

  • Configure a global resource

  • Configure a site resource

  • Configure App Default Config

  • Configure an applicaton

  • Rename an application

When you make changes to the CS Authentication resource, however, you must restart IIS. For instructions, see Restarting IIS.

To unload an application from memory

  1. In Internet Information Services snap-in, select the root of the IIS Web site, or the Starting Point directory of the application.

  2. Right-click the directory (for example, Default Web Site), click Properties, and then click the Home Directory tab.

    Note

    • If the Unload button is not available, you are not in the starting point directory for the application or the application is already unloaded.
  3. Click Unload.

    The following message may appear: "Unloading this application will unload all applications in the application pool. Are you sure you want to continue?"

  4. Click Yes if the message was displayed.

The application is unloaded from memory. The next time a user visits your Web site, the new property values are read when the application is loaded into memory.

See Also

Restarting IIS

Configuring a Global Resource

Configuring a Site Resource

Configuring App Default Config Resrouce Properties

Configuring an Application

Renaming an Application


Restarting IIS

When you make changes to the properties used by the CS Authentication resource, you must stop and then restart Internet Information Services (IIS) 5.0. Because CS Authentication is a global resource, all sites using it must be unloaded from memory.

You must restart IIS when you perform any of the following tasks in the CS Authentication resource:

  • Configure CS Authentication resource properties

  • Enable cookie sharing across domains/applications

  • Enable AuthFilter

  • Disable AuthFilter

Note

  • Do not use the IISReset command to restart IIS. Although IISReset will stop and then restart IIS, under certain conditions it does not stop and then start Inetinfo.exe (W3SVC service). For example, if the W3SVC service has been configured for manual start instead of automatic, it will not be restarted.

To reset IIS

  1. Click Start, and then click Run.

  2. In the Open box, type net stop iisadmin.

  3. At the prompt, "Do you want to continue this operation?" type Y.

    The Internet Information Services are stopped.

  4. Click Start, and then click Run.

  5. In the Open box, type net start w3svc.

    The Internet Information Services are started.

See Also

Unloading an Application from Memory

Configuring CS Authentication Resource Properties

Enabling Cookie Sharing Across Domains/Applications

Enabling AuthFilter for the Retail Solution Site

Enabling AuthFitler for the Supplier Solution Site

Disabling AuthFilter


Deleting an Application from a Site

When you delete an application from a site, the application data in the Administration database is deleted. None of the Web server files are deleted, and none of the Internet Information Services (IIS) 5.0 settings are deleted.

Before you delete an application from a site, you must first remove any Commerce Web servers associated with the application. For instructions about removing a Web server, see Removing a Web Server from an Application.

To delete an application from a site

  1. Expand Commerce Server Manager, expand Commerce Sites, and then expand the site you want to administer.

  2. Expand Applications, click the application you want to delete, right-click it, and then click Delete.

The application configuration data is deleted from the Administration database.

See Also

Removing a Web Server from an Application

Deleting a Resource from a Site

Deleting a Site


Removing a Web Server from an Application

When you remove a Web server from an application, you are removing the Commerce Web server object from the Administration database. You are not removing Internet Information Services (IIS) 5.0 settings or Web server files.

If you remove the Web server used by Commerce Server Business Desk, users will not be able to manage the site.

After you remove the last Web server from an application, the application still appears in Commerce Server Manager.

To remove a Web Server from an application

  1. Expand Commerce Server Manager, expand Commerce Sites, and then expand the site you want to administer.

  2. Expand Applications, expand the application from which you want to remove the Commerce Web server object, right-click the Web server object, and then click Delete.

The Commerce Web server object is removed from the application; the Web server no longer appears under the application. If necessary, you can add the same Web server, or a different one, to the application.

See Also

Web Servers

Adding a Web Server to an Application

Uninstalling Commerce Server


Automatically Adding a Web Server

You can create a new Web server by using Microsoft Application Center 2000 to deploy the Commerce Server files to the Web server, or by manually copying Commerce Server files to the Web server instead of using Commerce Server Site Packager. Commerce Server Solution Sites include code in global.asa that enables a Web server to be added to an application automatically.

When the Commerce Server application first starts on the new Web server (for example, a user connects to the Web server or gets load-balanced to it), and global.asa starts, the Web server is added automatically to the Administration database. The Web server reads from the Administration database the properties it needs for the site.

After it is added, the Web server is shown in the Commerce Server Manager so you can manage it.


Adding a Non-Commerce Application and Web Server

You can use Commerce Server Manager to add an application and a Web server that do not use Commerce Server components. The purpose of adding a non-Commerce application and Web server is so you can make the Web server log files available to the Data Warehouse for import.

To add a non-Commerce application to a site

  1. Expand Commerce Server Manager, expand Commerce Sites, and then expand the site you want to administer.

  2. Click Applications, right-click Applications, and then click Add Non-Commerce Application.

  3. In the New Non-Commerce Application dialog box, on the General tab, do the following:
    Use this | To do this
    Web servers in this application are running IIS | Select this check box if the servers in the non-Commerce application are running Internet Information Services (IIS) 5.0. You cannot have both IIS and non-IIS servers in a non-Commerce application.
    Nonsecure host name Type the Domain Name System (DNS) domain name that non-secured links in the application use.

    Caution

    • If you are using a port number other than 80, you must append that number to the end of the server name (for example, www.microsoft.com:81). To view the port number you are using, see the TCP port box in the Web Servers tab.
    IIS application path or Application path | Type the path to the application.
    Enable HTTPS | Select this property if secured links are used in the application.
    Secure host name Type the DNS domain name that secured links in the application use.

    Caution

    • If you are using a port number other than 443, you must append that number to the end of the server name (for example, www.microsoft.com:441). To view the port number you are using, see the SSL port box in the Web Servers tab.

  4. In the Web Servers tab, do the following:
    Use this | To do this
    IIS Web site | Type the name of the IIS Web site (for example, Default Web Site).
    TCP port | Type the Transmission Control Protocol (TCP) port (typically 80). If you have a value other than 80 here, you must type that value in the Nonsecure host name box on the General tab (for example, www.microsoft.com:81).
    SSL port | Type the Secure Sockets Layer (SSL) port (typically 443). If you have a value other than 443 here, you must type that value in the Secure host name box on the General tab (for example, www.microsoft.com:441).
    Local domain | Type the name of the local domain (for example, microsoft.com).

  5. Click OK.

To add a non-Commerce Web server to an application

  1. Expand Commerce Server Manager, expand Commerce Sites, and then expand the site you want to administer.

  2. Expand Applications, click the name of the non-Commerce application to which you want to add the Web server, right-click it, point to New, and then click Add Non-Commerce Web Server.

  3. In the Properties dialog box, do the following:
    Use this | To do this
    Server name | Type the name of the computer that hosts the non-Commerce Web server.
    IP Address | Type the Internet Protocol (IP) address for the non-Commerce Web server.
    Log file path | Type the log file path to which the non-Commerce Web server writes events, for example, C:\Winnt\System32\LogFiles\Log1.
    Log file period | Select the log file period from the drop-down list. The log file period indicates how long the non-Commerce Web server writes to a log file before creating a new one.

  4. Click OK.

See Also

Managing the CS Authentication Resource

Cookies and Authentication


Maintaining Commerce Server

This section contains:

  • Backing Up and Restoring Commerce Server. Explains how to back up and restore a Commerce Server installation.

  • Backing Up and Restoring an SQL Database. Describes backup and restore strategies and the restrictions on backup operations.

  • Minimizing Backup and Recovery Times in Mission-Critical Environments. Describes how to minimize backup and recovery time and explains how to restore a database backup.


Backing Up and Restoring Commerce Server

It is recommended that you back up your Commerce Server configuration every time it changes so that you can easily return it to a previous state should you experience a hardware or software catastrophe.

To back up your Commerce Server installation

  1. Back up your SQL Server databases using SQL Enterprise Manager.

  2. Back up your Internet Information Services (IIS) 5.0 metabase using Microsoft Windows 2000 Backup Wizard.

  3. Back up your Registry using Backup Wizard.

  4. Back up your Commerce Server files using Backup Wizard.

  5. Package your Commerce Server site using Commerce Server Site Packager.

To restore your Commerce Server installation

  1. Restore your IIS metabase using Backup Wizard.

  2. Restore your Registry using Windows 2000 Restore Wizard.

  3. Restore your Commerce Server files using Restore Wizard.

  4. Unpack your Commerce Server site and/or resources using Commerce Server Site Packager.

See Also

Using Site Packager

Backing Up Your Site

Backing Up and Restoring an SQL Database

Minimizing Backup and Recovery Times in Mission-Critical Environments


Backing Up and Restoring a SQL Database

When you create a database backup, the backup operation copies only the data in the database to the backup file; it does not copy out unused space in the database. Because the database backup contains only the actual data in the database—no empty space—the database backup is likely to be smaller than the database itself. An estimate of the size of the database backup can be determined using the sp_spaceused system-stored procedure; the reserved value indicates the estimated size.

Microsoft SQL Server does not truncate the transaction log when backing up the database. Therefore, when you are creating database backups, it is recommended that you set the transaction log to be truncated automatically every time a checkpoint occurs in the database by setting the trunc. log on chkpt. database option to TRUE. This prevents the transaction log from becoming full, which would require the transaction log to be truncated manually.

If you are producing only database backups, the backup interval should be long enough to keep the backup overhead from affecting production work, yet short enough to prevent the loss of significant amounts of data. Databases that do not contain critical data and have few modifications can be backed up on a weekly or biweekly basis. Data that is more critical or more volatile may need to be backed up daily, or even more frequently. Some databases that are usually read-only may need to be backed up only after a periodic refresh with new data.

It is also prudent to have more than one backup of the database. It is recommended that you maintain a rotating series of backup media, so that you have two or more versions of the database you can restore. This allows you to address situations in which a user may make some incorrect modifications that are not detected for some time, or to fall back to an earlier backup if backup media is damaged.

Backup Restrictions

Using SQL Server, backup operations can occur while the database is online and in use. However, the following operations are not allowed during a database backup operation:

  • Creating or deleting database files

  • Creating indexes

  • Performing non-logged operations

  • Shrinking either the database (automatically or manually) or the database files

If a backup operation is started when one of these operations is in progress, the backup operation terminates. If a backup operation is in progress and one of these operations is attempted, the operation fails and the backup operation continues.

Restoring a Database Backup

Restoring a database backup returns the database to the same state it was in when the backup was created. When you restore a database, SQL Server recreates the database and all of its associated files automatically by performing these steps:

  • All of the data from the backup is copied into the database; the rest of the database is created as empty space.

  • Any incomplete transactions in the database backup (transactions that were not complete when the backup operation completed originally) are rolled back (undone) to ensure that the database remains consistent.

This process ensures that the restored database is a copy of the database as it existed when the backup operation completed, except that all incomplete transactions have been rolled back. This is required to restore the integrity of the database.

Additionally, to prevent overwriting a database unintentionally, the restore operation can perform a safety check automatically. The restore operation fails if:

  • The database named in the restore operation already exists on the server and the database name does not match the database name recorded in the backup set.

  • The database named in the restore operation already exists on the server, but it is not the same database as the database contained in the database backup. For example, the database names are the same, but each database was created differently.

  • One or more files need to be created automatically by the restore operation (regardless of whether the database already exists), but files with the same file name as those that need to be created already exist.

These safety checks can be disabled if the intention is to overwrite another database.

Interrupted Backup and Restore Operations

If a backup or restore operation is interrupted (for example, due to a power loss on the server), it is possible to restart the backup or restore operation from the point it was interrupted. This can be useful if large databases are restored onto other servers as an automated process. If the automated process fails near the end of the restore operation (if, for example, there is a power failure), a system administrator can restart the restore operation from where it left off, rather than restoring the whole database from the beginning.

See Also

Minimizing Backup and Recovery Times in Mission-Critical Environments

Backing Up Your Site


Minimizing Backup and Recovery Times in Mission-Critical Environments

Mission-critical environments often require that the database be available continuously, or for extended periods of time with minimal downtime. Therefore, the duration of unexpected situations, such as a hardware failure, that require the database to be restored need to be kept as short as possible. Additionally, mission-critical databases are often large, requiring longer periods of time to back up and restore. Microsoft SQL Server offers several methods for increasing the speed of backup and restore operations, thereby minimizing the effect on users during both operations.

  • Using multiple backup devices simultaneously allows backups to be written to all devices at the same time. Similarly, the backup can be restored from multiple devices at the same time.

  • Using a combination of database, differential database, and transaction log backups to minimize the number of backups that need to be applied to bring the database to the point of failure.

  • Using file and file group backups and transaction log backups, allowing only those files that contain the relevant data to be backed up or restored, rather than backing up the entire database.

To create a backup of a SQL database

  1. In SQL Server Enterprise Manager, expand a server group, and then expand a server.

  2. Expand Databases, right-click the database you want to back up, point to All Tasks, and then click Backup Database.

  3. On the General tab, in the Name box, type the backup set name.

  4. Optionally, in Description, enter a description for the backup set.

  5. Under Backup, select Database - complete.

  6. Under Destination, click Add to add an existing backup device or to create a new backup device.

    Or, click Remove to remove a backup device from the list of backup devices to be used.

  7. In the SQL Server Backup dialog box, under Overwrite, do the following:
    Use this | To do this
    Append to media | Append the backup to any existing backups on the backup device.
    Overwrite existing media | Overwrite any existing backups on the backup device.
    Schedule | Optionally, select to schedule the backup operation for later or periodic execution.

  8. Optionally, click the Options tab and select from these backup options:
    • Verify backup upon completion. Causes the backup to be verified when backed up.

    • Eject tape after backup. Causes the tape to be ejected when the backup operation has completed. Available only with tape devices.

    • Check media set name and backup set expiration. Causes the backup media to be checked to prevent accidental overwrites. In Media set name, enter the name of the media that should be used for the backup operation. Leave blank when specifying only the backup set expiration.
  9. If you are using the backup media for the first time, or if you want to change an existing media label, under Media set labels, select Initialize and label media, and enter the media set name and media set description. (The media can only be initialized and labeled when overwriting the media.)

See Also

Backing Up Your Site


Managing the CS Authentication Resource

You use the Commerce Server CS Authentication resource to establish or change the authentication and identification method for your Microsoft Commerce Server 2000 site. The site developer can establish the authentication method, package the site, and then you can unpack it. After you unpack the site, you can then view or modify settings for that authentication method with the CS Authentication resource.

This section contains:

  • About the CS Authentication Resource. Describes the modes supported by the CS Authentication resource. Describes the AuthManager object, and the AuthFilter.

  • Configuring CS Authentication Resource Properties. Explains how to configure the Authentication resource and describes the site properties you can set for a Commerce Server site.

  • Enabling Windows Authentication. Explains how to enable the Windows Authentication mode.

  • Enabling Custom Authentication. Explains how to enable the Custom Authentication mode.

  • Enabling Autocookie Generation. Explains how to enable the Autocookie mode.

  • Enabling Cookie Sharing Across Domains/Applications. Explains how to enable cookie sharing across domains, and how to enable cookie sharing across applications.

  • Setting the Security Mode on the Domain Controller. Explains how to set the security mode on the domain controller.

  • Disabling AuthFilter. Describes the No Filter mode for the CS Authentication resource and explains how to disable the AuthFilter.

  • Enabling AuthFilter for the Retail Solution Site. Explains how to enable the AuthFilter for the Retail Solution Site.

  • Enabling AuthFilter for the Supplier Solution Site. Explains how to enable the AuthFilter for the Supplier Solution Site.

  • Login.asp Code for the Retail Solution Site. Provides the code for the Login.asp for the Retail Solution Site.

  • Login.asp Code for the Supplier Solution Site. Provides the code for the Login.asp for the Supplier Solution Site.

  • Using Windows Authentication with Proxy Account in Web Farm. Explains how to modify your Login.asp code to support a proxy account in a Web farm.

  • Generating a New Encryption Key. Explains how to generate a new encryption key for encrypting and decrypting cookie data.


About the CS Authentication Resource

The CS Authentication resource is a Commerce Server resource with global-level properties, and is managed through Commerce Server Manager. You use CS Authentication resource to configure authentication modes and to determine how cookies will be implemented on your site. For example, using the CS Authentication resource you can enable autocookie generation, set cookies to be shared among applications on the same site, or determine how long the persistent cookie is valid.

You set CS Authentication properties in two places:

  • At the global level, you set properties in the CS Authentication global resource. These properties are used by all Commerce Server sites.

  • At the application level (right-click the application in Commerce Server Manager), you set authentication properties that are used only by the one application.

For each site, CS Authentication includes a global resource pointer. No properties are set at the site level. Two or more sites can share the same global CS Authentication resource.

If you are developing a site using a Commerce Server Solution Site, you also set authentication properties in the App Default Config resource. These properties are not used by CS Authentication. For information about configuring the App Default Config properties, see Configuring App Default Config Resource Properties.

Authentication Components

Authentication Modes

Multi-Domain, Single Login Capability

Authentication Components

Commerce Server provides two tools to manage user authentication and identification: the AuthManager object and the AuthFilter.

  • AuthManager. A Component Object Model (COM) object that exposes methods for identifying users and controlling access to dynamically generated content. For example, a site developer could invoke the GetUserID method of AuthManager to identify a user based on a cookie or a query string. For more information, see Configuring CS Authentication Resource Properties.

  • AuthFilter. An ISAPI filter that is used at the IIS Commerce Server application level. It can be applied to all users visiting the application. You configure AuthFilter at the application level. For more information, see Configuring an Application.

Authentication Modes

When you use AuthFilter, you can choose the following authentication modes:

  • No Filter mode. AuthFilter is not enabled.

  • Windows Authentication. AuthFilter uses Windows Authentication to control access to the site. It checks the user login and password against Active Directory (or a local Security Access Manager account). When you use Windows Authentication, you can require login access for only certain Active Server Pages (ASP) pages and directories that you specify. To use Windows Authentication, see Enabling Windows Authentication.

  • Custom Authentication. AuthFilter checks the user login and password (MSCSAuth ticket) against a SQL Server database or other type of database. Login access is required for every ASP page and directory in the Commerce Server site. AuthFilter checks against the virtual directory for the Commerce Server site, and it checks the Commerce Server Administration database to determine whether Custom Authentication is enabled for that site. If the MSCSAuth ticket is not valid, AuthFilter requires the user to enter login information.

    When you use Custom Authentication, login access is required for every ASP page and directory in the Commerce Server site. To use Custom Authentication, see Enabling Custom Authentication.

  • Autocookie mode. You can automatically generate cookies, which store tickets, for guest users. (When an anonymous user gets an MSCSProfile ticket, the user becomes a guest user.) MSCSProfile tickets enable you to collect profile data about how guest users navigate and use your site.

    If you select Autocookie mode and No Filter mode, then there are no registered users.

    If you are using Autocookie and either Windows Authentication mode or Custom Authentication mode, known as mixed mode, then when guest users register, their persistent cookies can be updated, and you do not lose the profile data gathered when the user was a guest. To use Autocookie mode, see Enabling Autocookie Generation.

If you enable mixed mode, AuthFilter generates the following tickets:

  • The first time the user logs in to the site, it generates an MSCSProfile ticket.

  • If the user is authenticated, it generates the MSCSAuth ticket, which will contain the user ID. You can use the MSCSAuth ticket for access control.

  • If the user is not authenticated (no MSCSAuth ticket), the MSCSProfile ticket will indicate that the user is anonymous.

Multi-Domain, Single Login Capability

The CS Authentication resource provides multi-domain, single login capability. To provide multi-domain, single login, you need to share cookies between domains with their domain property. This works only if the domains have a common sub-domain name. For example, premier.microsoft.com and msn.microsoft.com can share cookies with the microsoft.com domain name.

However, two domains such as microsoft.com and microsoft.uk cannot support single-login capability; they cannot share cookies because the subdomain name is not common. In this scenario, the user will be required to login again when switching domains. For more information about Passport integration, see Integrating with Passport.

To use multi-domain single login, you set two authentication properties at the site level: Set cookie path to application and Number of shared domain levels. You must set Number of shared domain levels to at least two, and use domains that share the same top level name, for example, msn.microsoft.com and premier.microsoft.com. For information about setting these authentication properties, see Configuring an Application.

See Also

Planning for Security

Working with Site Security and Filters

Enabling Windows Authentication

Enabling Custom Authentication

Enabling Autocookie Generation

Site Security Objects

AuthManager Object


Configuring CS Authentication Resource Properties

You can view and edit CS Authentication properties for the global CS Authentication resource.

Note

  • Many authentication properties are set at the site level. For information about configuring site level authentication properties, see Configuring an Application.

  • The following authentication properties are set in the App Default Config resource: Site ticket options, Site privacy options, Form login options, AuthManager Auth Ticket Timeout. These properties apply if you are developing a site using the Commerce Server Solutions Sites. For information about configuring these App Default Config properties, see Configuring App Default Config Resource Properties.

To configure the CS Authentication resource properties

  1. Expand Commerce Server Manager, and then open Global Resources.

  2. Right-click CS Authentication resource, and then click Properties.

  3. In the Properties box, select the property for which you want to set a value.

  4. In the Selected Property Value box, type the new value, and then click OK.

The following table lists the CS Authentication properties you can set at the global resource level for a Commerce Server site.

Property | Description
Login Form Name of the form to be used for logging on users. You can specify one of the following:
  • Relative path to the Login.asp page. Uses http://<server> and AuthFilter Helper Folder.

  • Full path to the Login.asp page.

If you use Secure Sockets Layer (SSL), you must specify the full path to the Login.asp page, for example:

http://www.microsoft.com/authfilter/login.asp.
Login Retries | The number of times users are prompted to type their user name and password before a message instructing them to call customer service is displayed.
Password-Cache Size | The maximum number of users whose credentials can be stored in the AuthFilter User-Password-Cache. This property is only used with Windows Authentication mode.
Password-Cache TTL | The length of time in minutes that the authentication credentials are stored in the Password-Cache. This property is only used with Windows Authentication mode.
TimeWindow for Valid Ticket | The default length of time in which the credentials generated by the AuthManager object is valid.
AuthProfile-Name | Name of the profile object to use when the data source for the Profiling System is partitioned. If using default schema, this value must be Profile Definitions.UserObject.
AuthFilter Helper Folder | Name of the folder that the AuthFilter uses to store helper files. You must keep all files related to the AuthFilter in this one folder. The default subfolder is \AuthFiles. All the AuthFilter files must always have Anonymous Access enabled.
Error Form Name of the form to be used when an access denied error occurs. You can specify one of the following:
  • Relative path to the form. Uses http://<server> and AuthFilter Helper Folder.

  • Full path to the form.
Help Form Name of the form that contains help information for logging in. You can specify one of the following:
  • Relative path to the form. Uses http://<server> and AuthFilter Helper Folder.

  • Full path to the form.
Internal Error Form Name of the error form to display when there is an internal error. You can specify one of the following:
  • Relative path to the form. Uses http://<server> and AuthFilter Helper Folder.

  • Full path to the form.
No-Cookie form Name of the form to display when the browser does not have cookies enabled or does not support cookies. You can specify one of the following:
  • Relative path to the form. Uses http://<server> and AuthFilter Helper Folder.

  • Full path to the form.
AutoCookie Form Name of the form to be redirected to when Autocookies are enabled. You can specify one of the following:
  • Relative path to the form. Uses http://<server> and AuthFilter Helper Folder.

  • Full path to the form.
Profile Cookie Expiration Date | End date after which the cookie is no longer valid.
Enable Encryption | To enable encryption of cookie data, set this property at the Commerce site level. For instructions, see Configuring an Application.
Encryption Key for Cookie Data | The encryption key used for encrypting or decrypting cookie data. To generate a new encryption key, see Generating a New Encryption Key.

Notes

  • You must keep all files related to the AuthFilter in one folder, specified in Auth Filter Helper Folder property. The default subfolder is \AuthFiles. All the AuthFilter files must always have Anonymous Access enabled.

  • After you change a global CS Authentication property, and if you are using AuthFilter, you must restart Internet Information Services (IIS) 5.0. For instructions, see Restarting IIS.

  • After you change an authentication property at the application level, and if you are using AuthManager, you must use API Refresh() or restart IIS to get the updated property values.

See Also

Working with Site Security and Filters

Configuring App Default Config Resource Properties

Site Security Objects

AuthManager Object


Enabling Windows Authentication

When you select the Windows Authentication mode, the AuthFilter will look up the access rights for the user in Active Directory. When a user logs in to a site running in this mode, the AuthFilter retrieves the user name and password from the Hypertext Transfer Protocol (HTTP) request and stores it in a cache. It also sets a cookie that is valid only for the duration of the user session. The cookie can then be checked by other pages the user visits during the session. In Windows Authentication mode, Active Control List (ACL) determines access to any resource on the Web site.

Windows Authentication supports a Web farm scenario with a single login, and it supports using proxy accounts. For more information about single login, see Cookies and Authentication.

Note

  • The following instructions assume you have set the security mode on your domain controller to log on locally. If you have not yet done so, see Setting the Security Mode on the Domain Controller.

To enable the Windows Authentication mode

  1. Expand Commerce Server Manager, expand Commerce Sites, and then click the site you want to administer.

  2. Expand Applications, right-click the name of the application that you want to work with, and then click Properties.

  3. In the Properties dialog box, in the General tab, in the Authentication filter box, select Windows Authentication, and then click OK.

AuthFilter will pass the credentials to Internet Information Services (IIS) 5.0, and IIS validates the user login and password against an Active Directory data store.

Note

  • After you change a property value in Commerce Server Manager, you must unload the application from memory on each Web server in order for the change to take effect. For instructions, see Unloading an Application from Memory.

See Also

Working with Site Security and Filters

Enabling Custom Authentication

Enabling Autocookie Generation

Enabling Cookie Sharing Across Domains/Applications

Site Security Objects

AuthManager Object


Enabling Custom Authentication

If you need to implement Custom Authentication, you can still use the AuthFilter to integrate it into your site. If you select Custom Authentication, the AuthFilter will check for a valid MSCSAuth ticket. If the valid MSCSAuth ticket is not found, the user is redirected to a login page, where you can do your own Custom Authentication by validating credentials and setting MSCSAuth ticket upon success.

For example, you could use the Profiling System to retrieve access rights from the user profile when the user logs in. The Profiling System retrieves user information from a data source. This data source could be a Microsoft SQL Server database, the Windows 2000 Active Directory, or another OLE DB-compliant data source or a valid LDAP version 3 store.

To enable the Custom Authentication mode

  1. Expand Commerce Server Manager, expand Commerce Sites, and then click the site you want to administer.

  2. Expand Applications, right-click the name of the application that you want to work with, and then click Properties.

  3. In the Properties dialog box, in the General tab, in the Authentication filter box, select Custom Authentication, and then click OK.

AuthFilter will redirect the user request to the Login.asp page, which will validate the user login and password against a SQL Server database or other type of data store.

Note

  • After you change a property value in Commerce Server Manager, you must unload the application from memory on each Web server in order for the change to take effect. For instructions, see Unloading an Application from Memory.

See Also

Working with Site Security and Filters

Enabling Cookie Sharing Across Domains/Applications

Enabling Windows Authentication

Enabling Autocookie Generation

Site Security Objects

AuthManager Object


Enabling Autocookie Generation

When you enable the Autocookie mode, the AuthFilter automatically generates a persistent cookie (MSCSProfile ticket) to treat the user as an anonymous user. When you choose Autocookie mode, the AuthFilter will always check to see whether the browser has this anonymous cookie. If the anonymous cookie is not in the browser, then the filter redirects the user to the AutoCookie Form.

Autocookie mode enables Commerce Server 2000 to keep track of anonymous users. If users with anonymous cookies register, Commerce Server can update their persistent cookies, and all the profile data gathered while users are anonymous is not lost. However, whether Commerce Server updates the persistent cookies depends on how you have developed your application.

To enable the Autocookie mode

  1. Expand Commerce Server Manager, expand Commerce Sites, and then click the site you want to administer.

  2. Expand Applications, right-click the name of the application that you want to work with, and then click Properties.

  3. In the Properties dialog box, in the General tab, select Autocookie, and then click OK.

AuthFilter will automatically generate persistent cookies for anonymous users.

Note

  • After you change a property value in Commerce Server Manager, you must unload the application from memory on each Web server in order for the change to take effect. For instructions, see Unloading an Application from Memory.

See Also

Working with Site Security and Filters

Enabling Windows Authentication

Enabling Custom Authentication

Enabling Cookie Sharing Across Domains/Applications

Site Security Objects

AuthManager Object


Enabling Cookie Sharing Across Domains/Applications

You can share cookies across domains. In order to do this, your domains must have a common sub-domain name. For example, msdn.microsoft.com and premier.microsoft.com can share cookies with the domain property set to .microsoft.com. You cannot set the domain to .com.

If you do not want to share cookies across domains, you can instead share them across applications. To do this, you set the path property on the cookie to the application. For example, you would set the path to /retail to share the cookie across all applications in the retail site. To share cookies between applications that do not have the same virtual directory, you must set the path to the root (/).

To enable cookie sharing across domains

  1. Expand Commerce Server Manager, expand Commerce Sites, and then click the site you want to administer.

  2. Expand Applications, right-click the application you want to configure, and then click Properties.

  3. In the Number of shared domain levels box, specify how many domain levels must be in common in order to share a cookie. For example, for premier.microsoft.com and msn.microsoft.com to share the microsoft.com cookie, set the value to 2.

  4. Click OK.

  5. Restart IIS. For instructions, see Restarting IIS.

Note

  • If you are using encryption, verify that the encryption key is the same on both domains. For information about generating a new encryption key, see Generating a New Encryption Key.

To enable cookie sharing across applications in the same site

  1. Expand Commerce Server Manager, expand Commerce Sites, and then click the site you want to administer.

  2. Expand Applications, right-click the application you want to configure, and then click Properties.

  3. Clear the Set cookie path to application box, and then click OK.

  4. Restart IIS. For instructions, see Restarting IIS.

See Also

Cookies and Authentication

Working with Site Security and Filters

Configuring an Application

Site Security Objects

AuthManager Object


Setting the Security Mode on the Domain Controller

You must enable Domain\Users to use Windows Authentication mode on any Commerce Server site. You must also enable Domain\Users for the Supplier Solution Site on which you want to use Basic Authentication (not Integrated Authentication).

To set the security mode on the domain controller

  1. Click Start, point to Programs, point to Administrative Tools, and then click Domain Controller Security Policy.

  2. In the Security Settings tab, click Local Policies, click User Rights Assignment, and then click Log on Locally.

  3. In the Security dialog box, add Domain\Users to this policy, and then click OK.

See Also

Enabling AuthFilter for the Supplier Solution Site


Disabling AuthFilter

If you do not want the AuthFilter to be applied to your site at the site level, you must select No Filter mode in the Commerce Authentication Filter section of the General Properties tab for an application. You must also remove Autocookie generation for the site.

When you select the No Filter mode for the CS Authentication resource, the AuthFilter is not applied to the Web site. However, if you select No Filter and Autocookie generation is enabled, the AuthFilter is applied to the site.

In No Filter mode, the site developer can apply authentication to individual Active Server Pages (ASP) by invoking methods exposed by the AuthManager object. AuthManager is a Component Object Model (COM) object that exposes methods for identifying users and controlling access to dynamically generated content. For example, a site developer could invoke the GetUserID method of AuthManager to identify a user based on a cookie or a query string.

The Solution Sites for Commerce Server 2000 by default use the No Filter mode and have implemented an authentication scheme based on AuthManager. If you want to change the sites to take advantage of the AuthFilter, you will need to make some changes to the Login.asp and other helper pages for the sites. For more information, see Enabling AuthFilter for the Retail Solution Site and Enabling AuthFilter for the Supplier Solution Site.

To disable AuthFilter

  1. Expand Commerce Server Manager, expand Commerce Sites, and then click the site you want to administer.

  2. Expand Applications, right-click the application you want to configure, and then click Properties.

  3. In the Properties dialog box, in the General tab, in the Authentication Filter box, select No Filter.

  4. Clear the Autocookie box if it is checked, and then click OK.

Notes

  • After you change a property value in Commerce Server Manager, you must restart Internet Information Services (IIS) 5.0 in order for the change to take effect. For instructions, see Restarting IIS.

  • If you disable AuthFilter for a site by choosing No Filter mode, you must manually configure the security settings that you need on the site. To manually configure the security settings, use IIS, select the security settings that you want for that site, and then restart IIS. For instructions, see Restarting IIS.

See Also

Working with Site Security and Filters

Enabling AuthFilter for the Retail Solution Site

Enabling AuthFilter for the Supplier Solution Site

Unloading an Application from Memory


Enabling AuthFilter for the Retail Solution Site

These instructions explain how to enable the AuthFilter on the Retail Solution Site.

To enable AuthFilter on the Retail Solution site

Important Information about Using AuthFilter

To enable AuthFilter on the Retail Solution Site

  1. Use Commerce Server Site Packager to unpack the Retail Solution Site.

  2. Expand Commerce Server Manager, expand Commerce Sites, and then click the site you want to administer.

  3. Expand Applications, right-click the name of the application that you want to work with, and then click Properties.

  4. In the Properties dialog box, in the General tab, in the Authentication filter box, select either Windows Authentication or Custom Authentication, and then click OK.

  5. Use a text editor to open Authfiles\Login.asp for the Retail site.

  6. In Login.asp, verify that you have the included files that are in Retail\Login\Login.asp and the code matches with the example. To verify the code in the example, see Login.asp Code for the Retail Solution Site.

  7. Save and close the updated Login.asp page.

  8. Use the Users module in Commerce Server Business Desk to create a new user for the Retail site. For information, see Adding a User.

  9. Use Internet Explorer to navigate to http://<computername>/Retail.

At the login page, type the user name and password if you are a registered user, or choose to register by clicking on the link at the bottom of the page.

The Login.asp page sets the MSCSAuth ticket for the registered user, retrieves the profile for the user, and populates the Web page using the profile information it retrieved.

If the the profile could not be found, the Login.asp page is displayed again with an error message, and presents the same two options to log in as before. If the user name or password is not valid, then the Login.asp is displayed again, but without an error message. To add a registration or new user page to your Web site using AuthFilter, follow the instructions for the Login.asp page.

Notes

  • You must add your own registration page from which you can create accounts on Active Directory.

  • If you decide to enable AuthFilter after you disabled it, you must manually reset Internet Services Manager (IIS) 5.0 security settings.

  • After you change a property value in Commerce Server Manager, you must unload the application from memory on each Web server in order for the change to take effect. For instructions, see Unloading an Application from Memory.

Important Information about Using AuthFilter

  • If you unpack a site to the virtual directory on IIS with AuthFilter enabled, you must uncheck the application level property, Set cookie path to application. This property represents the path property set on cookies. By default the Flag is enabled to set this to the virtual directory of the site (for example, /retail). By unchecking the box, the root (/) is set as the path property for your cookies. You must restart IIS after updating this property. For instructions, see Restarting IIS.

  • Verify that you use Anonymous Access for all include, .gif, or helper files that are used by Login.asp.

  • For Windows Authentication, the default login page uses the GET action in Login-Submit. The POST action is also supported with Login.asp. For information about supporting the POST action, see the comments in Login.asp and follow those instructions.

  • There is a known security issue if you are using GET with Login.asp. It is recommended that you tell users who visit your site to set their browser to automatically clear the browser history after they log off or have them clear the browser history manually.

  • In Windows Authentication, the following server variables are not set: AUTH_USER and AUTH_TYPE. The server variable LOGON_USER is set to the User ID which is used for logging in.

  • To use Secure Sockets Layer (SSL), you must set the s_Login_Form property in CS Authentication to the full path. For instructions, see Configuring CS Authentication Resource.

See Also

Working with Site Security and Filters

Adding a User

Login.asp Code for the Retail Solution Sitel

Login.asp Code for the Supplier Solution Site

Unloading an Application from Memory

Configuring CS Authentication Resource


Enabling AuthFilter for the Supplier Solution Site

These instructions explain how to enable the AuthFilter on the Supplier Solution Site.

For the Supplier Solution Site and for using AuthFilter in Windows Authentication mode, you need to set the security mode on your domain controller to log on locally. If you have not yet done so, see Setting the Security Mode on the Domain Controller.

Only Basic Authentication should be enabled on the Supplier Solution Site. Do not change any other security settings.

The AuthFiles subfolder and all pages in it should have anonymous access enabled.

If your domain controller and Web server are installed on different computers in the same domain, then AuthFilter must have an anonymous account on the Web server in order to execute the method ProfileService.GetUserProfileByKey() on the Login page successfully for any profile/user.

By default, an anonymous user account is IUSR_<servername>. In Internet Services Manager, IUSR_<servername> does not have enough permissions to execute this successfully in this scenario. In addition, if your Web server is different from your domain-controller server, you must add a user account from that domain as the anonymous account. To do this you first create on the domain a user account that has access to read the user properties from Active Directory. Then on the Web server, use IIS Manager to set up the same user account as the anonymous account for the AuthFiles subfolder and all the files in that subfolder.

To enable AuthFilter on the Supplier Solution Site

Important Information about Using AuthFilter

To enable AuthFilter on the Supplier Solution Site

  1. Use Commerce Server Site Packager to unpack the Supplier Solution Site.

  2. Expand Commerce Server Manager, expand Commerce Sites, and then click the site you want to administer.

  3. Expand Applications, right-click the name of the application that you want to work with, and then click Properties.

  4. In the Properties dialog box, in the General tab, in the Authentication filter box, select either Windows Authentication or Custom Authentication, and then click OK.

  5. Expand Internet Information Services, right-click the Supplier site, and then click Properties.

  6. In the Properties dialog box, in the Directory Security tab, in the Anonymous access and authentication control section, click Edit.

  7. In the Authentication Methods dialog box, clear the Integrated Windows authentication box.

    Note

    • Only Basic Authentication should be enabled on the Supplier Solution Site. Do not change any other security settings.
  8. Use a text editor to open Authfiles\Login.asp for the Supplier site.

  9. If you are using a Web farm, or if you require proxy account support, in Login.asp, update the code so it matches the code shown in the topic, Login.asp Code for Supplier Solution Site.

    Important

    • If this is a single server that requires no support for proxy account, you do not need to update the Login.asp.
  10. For Windows Authentication, change the GetUserInfo() method in \SupplierAD\include\Std_access_lib.asp to the following:
Sub GetUserInfo()
    Dim sAuthUser, mscsUser
    Dim aName

    If dictConfig.i_DelegatedAdminOptions = DELEGATED_ADMIN_SUPPORTED Then
       sAuthUser = LoginName(Request.ServerVariables("LOGON_USER"))
        End If
        Rem Integrated Windows and basic auth take precedence over HTML form auth
        If sAuthUser <> "" Then
            m_UserAccessType = IIS_AUTH ' BASIC_AUTH
            m_UserType = AUTH_USER
            Set mscsUser = GetUserProfileByLoginName(sAuthUser)
            If mscsUser Is Nothing Then
               m_UserID = ""
            Else
               m_UserID = mscsUser.Fields(GetQualifiedName(GENERAL_INFO_GROUP, USER_ID)).Value
            End If
        Else
            If mscsAuthMgr.IsAuthenticated() Then
              sAuthUser = mscsAuthMgr.GetUserID(AUTH_TICKET)
              Set mscsUser = GetUserProfileByLoginName(sAuthUser)
                If mscsUser Is Nothing Then
                   m_UserID = ""
                Else
                  m_UserID = mscsUser.Fields(GetQualifiedName(GENERAL_INFO_GROUP, USER_ID)).Value
                End If
              m_UserAccessType = TICKET_AUTH
              m_UserType = AUTH_USER
            Else
                If Not IsNull(mscsAuthMgr.GetUserID(GUEST_TICKET)) Then
                   m_UserID = mscsAuthMgr.GetUserID(GUEST_TICKET)
                   m_UserAccessType = GUEST_VISIT
                   m_UserType = GUEST_USER
                Else
                   m_UserID = ""
                   m_UserAccessType = ANON_VISIT
                   m_UserType = ANON_USER
                End If
            End If
        End If
End Sub

  Function LoginName(ByVal sUserName)
    Dim aName

    If (sUserName = "") Then
      Exit Function
    End IF
    aName = Split (sUserName, "\")
    LoginName = aName(UBound(aName))
  End Function
  11. For Windows Authentication, in the PrepareLoginSection method in \SupplierAD\template\menu.asp, change code in a Request.ServerVariables string that is referring to the "AUTH_USER" server variable to instead refer to the "LOGON_USER" server variable. For example:

    Incorrect: sAuthUser = Request.ServerVariables("AUTH_USER")

    Correct: sAuthUser = Request.ServerVariables("LOGON_USER")

  12. Save and close the updated Login.asp and menu.asp pages.

  13. Use Business Desk to create a new user for the Supplier site.

    Important

    • Create an Organization before adding any users or creating new users for it.
  14. Use Internet Explorer to navigate to http://<computername>/SupplierAD.

  15. At the login page, type the user name using DomainName\userID or User Principal Name (UPN) format. (You can add logic to Login.asp to add these to the userID/name). Type the password if you are a registered user, or choose to register by clicking the link at the bottom of the page. (You need to add your own registration page on which you can create accounts on Active Directory.)

The Login.asp page sets the MSCSAuth ticket for the registered user, retrieves the profile for the user, checks credentials if required, and the request populates the default Web page using the profile information it retrieved.

If the user name or password is not valid or if the profile could not be found, the Login.asp page is displayed again with an error message, and presents the same two options to log in as before.

Important Information about Using AuthFilter

  • If you unpack a site to the virtual directory on IIS with AuthFilter enabled, you must uncheck the application level property, Set cookie path to application. This property represents the path property set on cookies. By default the Flag is enabled to set this to the virtual directory of the site (for example, /retail). By unchecking the box the root (/) is set as the path property for your cookies. You must restart IIS after updating this property. For instructions, see Restarting IIS.

  • Verify that you use Anonymous Access for all include, .gif, or helper files that are used by Login.asp.

  • For Windows Authentication, the default login page uses the GET action in Login-Submit. The POST action is also supported with Login.asp. For information about supporting the POST action, see the comments in Login.asp and follow those instructions.

  • There is a known security issue if you are using GET with Login.asp. It is recommended that you tell users who visit your site to set their browser to automatically clear the browser history after they log off or have them clear the browser history manually.

  • In Windows Authentication, the following server variables are not set: AUTH_USER and AUTH_TYPE. The server variable LOGON_USER is set to the User ID, which is used for logging in.

  • To use Secure Sockets Layer (SSL), you must set the s_Login_Form property in CS Authentication to the full path. For instructions, see Configuring CS Authentication Resource.

See Also

Working with Site Security and Filters

Login.asp Code for Supplier Solution Site


Login.asp Code for the Retail Solution Site

Following is the code for the Login.asp for the Retail Solution Site. If you choose to use AuthFilter for the Retail site, you must use this code for your site Login.asp. For more information, see Enabling AuthFilter for the Retail Solution Site.

<!-- #INCLUDE FILE="../include/header.asp" -->
<!-- #INCLUDE FILE="../include/const.asp" -->
<!-- #INCLUDE FILE="../include/html_lib.asp" -->
<!-- #INCLUDE FILE="../include/form_lib.asp" -->
<!-- #INCLUDE FILE="../include/std_access_lib.asp" -->
<!-- #INCLUDE FILE="../include/std_profile_lib.asp" -->
<!-- #INCLUDE FILE="../include/std_cookie_lib.asp" -->
<!-- #INCLUDE FILE="../include/std_url_lib.asp" -->
<!-- #INCLUDE FILE="../include/std_util_lib.asp" -->
<!-- #INCLUDE FILE="../include/setupenv.asp" -->
<!-- #INCLUDE FILE="../template/no_menu.asp" -->

<%
REM sample file for using with AuthFilter
REM This file handles Login for user
%>

<%

   Sub Main()
   End Sub

   Dim strSelect, strUsername, strPassword, strPWD, retAsp
   dim objAuth
   Dim strAuthErr, strSiteName, sUserID

   set objAuth = Server.CreateObject("Commerce.AuthManager")
   strSiteName = CStr(Application("MSCSCommerceSiteName"))
   objAuth.Initialize(strSiteName)

   'Get the hidden variable to determine if this is the first run of the page
   strSelect = Request.Querystring("realSubmit")

   'If users pressed the submit button
   if strSelect = "fromButton" then
      'authenticate the user
      strUsername = Request.Querystring("txtUsername")
      strPassword = Request.Querystring("txtPassword")

         if (strUsername = "") or (strPassword = "") then
            Response.Redirect "Login.asp"
         end If

         Set mscsUserProfile = GetUserProfileByLoginName(strUsername)
         if (mscsUserProfile is nothing) then
            Response.Redirect "Login.asp"
         end if

         if (mscsUserProfile.Fields("GeneralInfo.user_security_password").Value = strPassword) then
            sUserID = mscsUserProfile.Fields(GetQualifiedName(GENERAL_INFO_GROUP, FIELD_USER_ID)).Value
            ' for Custom/NT Auth
            objAuth.SetAuthTicket sUserID, 1, 90

            ' Go to the Original requested ASP which is stored in cookie MSCSFirstRequestedURL"
            retAsp = Request.Cookies("MSCSFirstRequestedURL")
            if (retAsp = "" Or IsNUll(retAsp)) then
            retAsp = objAuth.GetURL("default.asp", True, False)
            end if
            Response.Redirect retAsp
         else
            Response.Redirect "Login.asp"
         end if
   else
      PrintLogin
   End if
%>

<%Sub PrintLogin() %>
<HTML>
<HEAD>
<TITLE>Login</TITLE>
</HEAD>
<BODY>
<FORM NAME="frmLogin" ACTION="Login.asp" METHOD="GET">
<br>
<br>
<br>
<H2 ID=L_LoginForm_HTMLText>CS2K-LoginForm</H2><ID Id=L_EnterCredential_ErrorMessage>
To access authenticated content, please enter your UserID & Password</ID>
<br>
<br>
<br>

<H3 ID=L_UserName_HTMLText>Username:<INPUT TYPE="text" NAME="txtUsername" SIZE=32 MAXLENGTH=32><br><ID ID=L_UserPassword_HTMLText>
Password :</ID><INPUT TYPE="password" NAME="txtPassword" SIZE=32 MAXLENGTH=32></H3><br>
<br>

<INPUT type=HIDDEN name="realSubmit" value="fromButton">
<p align="left">
   <input type="submit" name="action" id=L_Submit_Button value="Submit">
   <input type="reset" name="action" id=L_Reset_Button value="Reset">
</p>
</FORM>

<H4>
<br>
<br>
<%
REM SOLUTION SITES: Retail
REM    need to add own registration file under '\AuthFiles\' sub-Dir Or Copy ..\Retail\login\newuser.asp to '\AuthFiles\newuser.asp'
REM    in global.asa update: dictPages.NewUser = "AuthFiles/newuser.asp"
REM
%>
<A HRef="newuser.asp" ID=L_RegisterIf_HTMLText>Register if you are a new user
   (solution sites: need to add own registration file under '\AuthFiles\' sub-Dir Or Copy ..\Retail\login\newuser.asp & update NewUser-File in Global.asa)</A>
<br>
</H4>

</BODY>
</HTML>
<%end sub%>

See Also

Working with Site Security and Filters

Enabling AuthFilter for the Retail Solution Site


Login.asp Code for the Supplier Solution Site

Following is the code for the Login.asp for the Supplier Solution Site. If you choose to use AuthFilter for the Supplier site, you must use this code for your site Login.asp. For more information, see Enabling AuthFilter for the Supplier Solution Site.

<!-- #INCLUDE FILE="../include/header.asp" -->
<!-- #INCLUDE FILE="../include/const.asp" -->
<!-- #INCLUDE FILE="../include/html_lib.asp" -->
<!-- #INCLUDE FILE="../include/form_lib.asp" -->
<!-- #INCLUDE FILE="../include/std_access_lib.asp" -->
<!-- #INCLUDE FILE="../include/std_profile_lib.asp" -->
<!-- #INCLUDE FILE="../include/std_cookie_lib.asp" -->
<!-- #INCLUDE FILE="../include/std_url_lib.asp" -->
<!-- #INCLUDE FILE="../include/std_util_lib.asp" -->
<!-- #INCLUDE FILE="../include/setupenv.asp" -->
<!-- #INCLUDE FILE="../template/no_menu.asp" -->

<%
REM sample file for using with AuthFilter
REM This file handles Login for user
%>

<%

   Sub Main()
   End Sub

   Dim strSelect, strUserName, strPassword, strPasswordTest, strPWD, strRetAsp, sAuthUser
   dim objAuth, objMSCSProfileObj
   Dim strAuthErr, strSiteName, sUserID

   ' AuthManager : Create & Initialize
   set objAuth = Server.CreateObject("Commerce.AuthManager")
   strSiteName = CStr(Application("MSCSCommerceSiteName"))  ' Get SiteName
   objAuth.Initialize(strSiteName)

   'Get the hidden variable to determine if this is the first run of the page
   strSelect = Request.Querystring("realSubmit")

   'If users pressed the submit button
   if strSelect = "fromButton" then

      'authenticate the user
      strUserName = Request.Querystring("txtUsername")
      strPassword = Request.Querystring("txtPassword")

         if (strUserName = "") or (strPassword = "") then
            Response.Redirect "Login.asp"
         end If

''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
         ' $PROXY-ACCOUNT: start
         '   To get Proxy-Account
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
         ' For Proxy-Account usage: you may need to update 'strUserName' && 'strPassword', which you may get from Profile
         '   Or some other similar way ...
         ' if password-available:   if (objMSCSProfileObj.Fields("GeneralInfo.user_security_password").Value = strPassword) then
         ' sUserID = objMSCSProfileObj.Fields(GetQualifiedName(GENERAL_INFO_GROUP, FIELD_USER_ID)).Value
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
         ' $PROXY-ACCOUNT: end
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''

''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
         ' $PASSWORD: start
         '   To get Clear-Text-Password:
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
         sAuthUser = LoginName(strUserName)   ' as per profile-schema we need to filter DomainName here. 'strUserName' is in format: Domain\UserLoginID
         Set objMSCSProfileObj = GetUserProfileByLoginName(sAuthUser)
         if (objMSCSProfileObj is nothing) then
            Response.Redirect "Login.asp"
         end if
         ' if password-available: in clear-text for Proxy-Account
         ' strPasswordTest = objMSCSProfileObj.Fields.Item("GeneralInfo").Value.Item("user_security_password") ' objMSCSProfileObj.Fields("GeneralInfo.user_security_password").Value
         Set objMSCSProfileObj = Nothing

''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
         ' End Of getting Clear-Text password
         ' $PASSWORD: End
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
            ' for Custom/NT Auth
            ' if password-available: in clear-text for Proxy-Account
            ' if (strPasswordTest = strPassword) then
            objAuth.SetAuthTicket strUserName, 1, 90
            ' Else
            '   Response.Redirect "Login.asp"
            ' EndIF

            ' Go to the Original requested ASP which is stored in cookie "MSCSFirstRequestedURL" & the following is required for a POST in Login instead of GET(by default)
            strRetAsp = Request.Cookies("MSCSFirstRequestedURL")   'retAsp = "..\default.asp"    '  (or) use: Request.Cookies("MSCSFirstRequestedURL") &  First requested URL (even if there is no QueryString this URL ciontains '?' at the end
            strRetAsp = strRetAsp + "&proxyuser="               ' make sure the QS-separator '?' is added by filter
            strRetAsp = strRetAsp + strUserName
            strRetAsp = strRetAsp + "&proxypwd="            ' Password
            strRetAsp = strRetAsp + strPassword

            if (strRetAsp = "" Or IsNUll(strRetAsp)) then
               strRetAsp = objAuth.GetURL("default.asp", True, False, Array("proxyuser", "proxypwd"), Array(strUserName, strPassword))
            end if

            ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
            ' Distributed-Denial-Of-Service Attack (DDoS)
            ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
            ' this is to avoid DDos Attacks with known User login ID
            ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
            ' Set objGenID =  Server.CreateObject("Commerce.GenID") '$PERF: store one in Application scope in GLOBAL.ASA, Application("MSCSAuthGenID")
            ' strGUID = objGenID.GenGUIDString
            '
            ' objAuth.SetProperty 2, "guid", strGUID ' after setting Ticket
            ' strRetAsp = strRetAsp + "&guid="
            ' strRetAsp = strRetAsp + strGUID
            ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''

            Response.Redirect strRetAsp
   else
      if objAuth.IsAuthenticated(30) Then      ' for Web-Farm scenario <valid-Auth-Ticket Exist, but not cached in Filter>
         strUserName = objAuth.GetUserID(2)   ' Get LoginID <only in case of AD-Site>
         if (strUserName = "") or (IsNull(strUserName)) then
            Response.Redirect "Login.asp"
         end If
         sAuthUser = LoginName(strUserName)   ' as per profile-schema we need to filter DomainName here. 'strUserName' is in format: Domain\UserLoginID

''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
         ' $PROXY-ACCOUNT: start
         '   To get Proxy-Account
         ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
         ' For Proxy-Account usage: you may need to update 'strUserName' && 'strPassword', which you may get from Profile
         '   Or some other similar way ...
         ' if password-available:   if (objMSCSProfileObj.Fields("GeneralInfo.user_security_password").Value = strPassword) then
         ' sUserID = objMSCSProfileObj.Fields(GetQualifiedName(GENERAL_INFO_GROUP, FIELD_USER_ID)).Value
 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
         ' $PROXY-ACCOUNT: end
         ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''

''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
         ' $PASSWORD: start
         '   To get Clear-Text-Password:
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
         Set objMSCSProfileObj = GetUserProfileByLoginName(sAuthUser)   ' Helper method from SupplierAD solution-site
         if (objMSCSProfileObj is nothing) then
            Response.Redirect "Login.asp"
         end if
         ' if password-available: in clear-text <same for proxy-account-scenario>
         strPassword = objMSCSProfileObj.Fields.Item("GeneralInfo").Value.Item("user_security_password") ' objMSCSProfileObj.Fields("GeneralInfo.user_security_password").Value
         'strPassword = "password"   ' if PWD not avalable & for test purposes only
         Set objMSCSProfileObj = Nothing
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
         ' End Of getting Clear-Text password
         ' $PASSWORD: End
''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''

         strRetAsp = Request.Cookies("MSCSFirstRequestedURL") '  (or) use: "../default.asp"
         strRetAsp = strRetAsp + "&proxyuser="               ' make sure the QS-separator '?' is added by filter
         strRetAsp = strRetAsp + strUserName
         strRetAsp = strRetAsp + "&proxypwd="               ' Password
         strRetAsp = strRetAsp + strPassword

            ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
            ' Distributed-Denial-Of-Service Attack (DDoS)
            ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
            ' this is to avoid DDos Attacks with known User login ID
            ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
            ' strGUID = objAuth.GetProperty(2, "guid")   ' if this exists, you need to pass this also on Query string
            '
            ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
            ' If Not IsNull(strGUID) Then
            '    strRetAsp = strRetAsp + "&guid="
            '    strRetAsp = strRetAsp + strGUID
            ' End If
            ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''

         Response.Redirect strRetAsp
      Else
         PrintLogin
      End If
   End if

   Set objAuth = Nothing
%>

<%Sub PrintLogin() %>
<HTML>
<HEAD>
<TITLE>Login</TITLE>
</HEAD>
<BODY>
<FORM NAME="frmLogin" ACTION="Login.asp" METHOD="GET">
<br>
<br>
<br>
<H2 ID=L_LoginForm_HTMLText>CS2K-LoginForm</H2><ID Id=L_EnterCredential_ErrorMessage>
To access authenticated content, please enter your UserID & Password</ID>
<br>
<br>
<br>

<H3 ID=L_UserName_HTMLText>Username:<INPUT TYPE="text" NAME="txtUsername" SIZE=32 MAXLENGTH=32><br><ID ID=L_UserPassword_HTMLText>
Password :</ID><INPUT TYPE="password" NAME="txtPassword" SIZE=32 MAXLENGTH=32></H3><br>
<br>

<INPUT type=HIDDEN name="realSubmit" value="fromButton">
<p align="left">
   <input type="submit" name="action" id=L_Submit_Button value="Submit">
   <input type="reset" name="action" id=L_Reset_Button value="Reset">
</p>
</FORM>

<H2>
<br>
<br>
<A HRef="register.asp" ID=L_RegisterIf_HTMLText>Register if you are a new user (need to add this registration file)</A>
<br>
</H2>

</BODY>
</HTML>
<%end sub%>

See Also

Working with Site Security and Filters

Enabling AuthFilter for the Supplier Solution Site


Using Windows Authentication with Proxy Account in Web Farm

You can use AuthFilter and Windows Authentication with the Supplier Solution Site in a Web farm scenario. You need to use the GUID property as explained in the Digital Denial of Service (DDoS) attack scenario in Login.asp Code for the Supplier Solution Site.

You also need use the GUID property with the first-time-login path and the Web farm login path. The code that is in bold in the following sample indicates the changes you need to make to the Login,asp file.

' after setting AuthTicket
     objAuth.SetAuthTicket strUserID, True, 90
  objAuth.SetProperty 2, "guid", strGUID

' at the redirect in both the FirstTime and WebFarm paths:
      strRetAsp = Request.Cookies("MSCSFirstRequestedURL")
      strRetAsp = strRetAsp + "proxyuser="
      strRetAsp = strRetAsp + "MyDomain\User1"
      strRetAsp = strRetAsp + "&proxypwd="
      strRetAsp = strRetAsp + "password"
   strRetAsp = strRetAsp + "&guid="
   strRetAsp = strRetAsp + strGUID

The strGUID variable is a GUID/UniqueID generated (for example, by the GUIDGen objectd) or guid-from profile.

See Also

Working with Site Security and Filters


Generating a New Encryption Key

The CS Authentication resource uses an encryption key for encrypting and decrypting cookie data. By default, when you unpack a site, the encryption key in the package is used (assuming one exists). The encryption key is stored in the AuthSetup.ini file in the package. If there is no key, a new key is generated by Commerce Server Site Packager, using AuthManager::GenerateEncryptionKey().

Every time you unpack a site, a new encryption key is created. If you package your own encryption key with the CS Authentication resource, then you will have the same key every time you unpack that custom package. If you want a new or separate key every time you unpack that site, after you unpack the site you must use the Generate New Encryption Key button in Commerce Server Manager.

Do not change the encryption key while a site is active. If you updated an encryption key while a site is active, existing MSCSAuth tickets would no longer be valid and users would have to log on again. A ticket that is encrypted with one key can only be decrypted with the same key.

Note

  • Before you update an existing encryption key, you must create a back up of the encryption key. Commerce Server does not create a back up for you. After you create the new key, the old one cannot be retrieved.

To generate a new encryption key

  1. Expand Commerce Server Manager, expand Commerce Sites, and then click the site you want to administer.

  2. Expand Applications, right-click the application you want to configure, and then click Properties.

  3. At the bottom of the dialog box, click Generate New Encryption Key.

  4. At the confirmation dialog box, click OK.

See Also

Working with Site Security and Filters


Running the Data Warehouse

You use the Commerce Server Data Warehouse to import, transform, and store Web site data. You import data into your Data Warehouse from Web log files, Commerce Server databases, and other data sources that you specify. After the data is imported, you can analyze it by running reports from Commerce Server Business Desk, or by viewing population segments.

The Data Warehouse database is added to Microsoft SQL Server when you unpack a site. You use Commerce Server Data Transformation Services (DTS) tasks and SQL Server packages to import and manage the data.

This section contains:

  • Workflow for Importing Data. Illustrates the workflow for loading and transforming data.

  • About the Data Warehouse. Describes the Data Warehouse and the types of data it contains.

  • Data Warehouse Components. Describes the components of the Data Warehouse.

  • Configuring the Data Warehouse Resource. Explains how to configure the Data Warehouse resource.

  • Configuring Web Log Files for Import. Explains how to configure your default Web site properties for importing.

  • Synchronizing Site Configuration with the Data Warehouse. Explains how to synchronize site configuration with the Data Warehouse so that any changes you make to the application are propagated to the Data Warehouse.

  • Configuring Web Log File Import Properties. Explains how to control and customize the way in which Web log file data is imported into the Data Warehouse.

  • Importing Data into the Data Warehouse. Explains how to import Web log file, catalog, campaign, transaction, and user profile data into the Data Warehouse.

  • Performing Internet Protocol Resolution. Explains how to resolve Internet Protocol (IP) addresses, and describes what occurs when you perform IP resolution.

  • Preparing to Create Reports. Explains how to use the Report preparation task, and describes its role in loading data used in reports into the OLAP cubes.

  • Deleting Data from the Data Warehouse. Explains how to delete data imported from Web log files from the Data Warehouse.

  • Extending the Data Warehouse. Lists resources for extending the Data Warehouse.


Workflow for Importing Data

The following figure shows a sample scenario for importing data into the Data Warehouse.

Workflow for importing data into the Data Warehouse
Web Log file Transaction User profile Product catalog Campaign
Import data
Data available
for analysis
Report preparation
Configure
Web Log files
Synchronize site configuration
with the
Data Warehouse


About the Data Warehouse

You use the Commerce Server Data Warehouse to import, transform, and store Web site data. You use the data stored in the Data Warehouse to analyze user activity on your Web site. Commerce Server 2000 provides several business analytic features, such as reports, in Commerce Server Business Desk. These reports show data from the Data Warehouse formatted in various ways to answer specific business questions about your Web site.

You can perform the following tasks using the Data Warehouse:

  • Import Web log file, user profile, transaction, campaign, and catalog data from your Commerce Server 2000 site. You can also import data from other data stores, such as non-Commerce Web Servers.

  • Resolve Internet Protocol (IP) addresses imported for client hosts that have connected to your site.

  • Prepare the data in your Data Warehouse for analysis by populating the online analytical processing (OLAP) cubes, which organize the data for retrieval during report execution.

  • Delete imported log file data to reduce the amount of storage space within the SQL Server database required by Commerce Server.

  • Delete all data from the Data Warehouse to remove existing test or archived data.

SQL Server Packages

Commerce Server and the Data Warehouse

SQL Server Packages

You use the Commerce Server Data Transformation Services (DTS) tasks, which are loaded into SQL Server when you unpack a site with SQL Server DTS packages to import, transform, and store data in the Data Warehouse. You can work with the Data Warehouse directly in SQL Server or in Commerce Server Manager.

You perform Data Warehouse operations by adding Commerce Server DTS tasks to a SQL Server DTS package, and then executing the package. You can perform one Data Warehouse task at a time by opening a package, adding a task to it, and then executing the package. You can also add several tasks to a package, add workflow instructions about the order in which the tasks will be run, and then run the package to perform all of the tasks in the same process, in the order you indicated.

Additionally, you can save packages with tasks and workflow instructions, and the package will be available when you want to run it. You can schedule a package to run with the SQL Server Scheduler. For more information about DTS packages, tasks, and the SQL Server Scheduler, see SQL Server Books Online.

Commerce Server and the Data Warehouse

Commerce Server uses the data in the Data Warehouse in the following ways:

  • You use the Analysis modules in Business Desk to run reports that answer business questions about your Web site by analyzing the data in the Data Warehouse. You can also view Segment models, created using the Predictor resource, in the Segment Viewer. For more information about running reports and viewing Segment models in the Analysis modules, see Business Desk Analysis.

  • You use the Predictor resource in Commerce Server Manager to create Prediction models that predict user behavior, and Segment models that analyze user behavior using the data in the Data Warehouse. For more information about the Predictor resource, see Running the Predictor Resource.

  • You use the List Manager module in Business Desk to manage lists that you create from Analysis reports and Segment models with the data in the Data Warehouse. For more information about campaigns and the List Manager module, see Business Desk Campaigns.

  • You use the Profiles resource in Commerce Server Manager to define the data your Web site will collect from users, and to select which pieces of information will be imported into the Data Warehouse. For more information about the Profiles resource, see Running the Profiles Resource.

  • You use the Users modules in Business Desk to update user information collected on your Web site, define the data your Web site will collect from users, and select the pieces of information that will be imported into the Data Warehouse. For more information about the Users modules, see Business Desk Users.

See Also

Importing Data into the Data Warehouse


Data Warehouse Components

The Data Warehouse uses Data Transformation Services (DTS) tasks, import processes, and online analytical processing (OLAP) cubes to import, transform, and store the data from your site.

This section contains:

  • DTS Tasks

  • Import Processes

  • Data Warehouse Storage Engine

  • OLAP Cubes


DTS Tasks

You use Commerce Server Data Transformation Services (DTS) tasks to import and change data in the Data Warehouse. The Commerce Server tasks are loaded into SQL Server when you unpack a site. You add the Commerce Server tasks to a SQL Server package and then run that package to make changes to the Data Warehouse.

Commerce Server provides the following tasks for the Data Warehouse.

Web Server Log import. Defines and imports Web log files. You use this task to set properties for the Web log file that determine the data that is imported from a Web log file, and how individual users and visits are distinguished.

Data deletion. Deletes detailed log file data and summarized data from the Data Warehouse. You delete log file data to reduce the size of the Data Warehouse. You delete all data, detailed and summarized, when you have imported test data and want to empty the Data Warehouse before importing valid data.

IP resolution. Resolves Internet Protocol (IP) addresses from the imported user data. IP resolution converts IP addresses, imported from your log files, into domain names. For example, 198.105.232.4 becomes www.microsoft.com. This helps readers of your reports understand the data in the reports more easily.

Campaign data import. Imports data about campaigns. You use campaign data to analyze the success of your campaigns. You use the Campaign resource of Commerce Server Business Desk to set up campaigns. For information about using the Campaigns modules in Business Desk, see About Campaigns. You can also run reports to analyze campaign data. For information about reports, see Advertising Reports.

Transaction data import. Defines and imports transaction data. Transaction data is created on your Web site when a user adds and removes items from a shopping cart, or makes a purchase. You can run reports to analyze transaction data. For information about reports, see Product Sales Reports.

User profile data import. Imports user profile data into the Data Warehouse. Commerce Server collects user profile data when users visit your Web site. Commerce Server collects profile data about registered users when users enter personal information into the User Object profile definition on your site.

Commerce Server also collects information about the actions of guest users (users who are not registered on your Web site). Guest user profile data contains a Global Unique Identifier (GUID) for the guest user, and behavior data.

You can modify the User Object profile definition in the Profiles resource in Commerce Server Manager, and in the Profile Designer module in Business Desk. You can use the Users module in Business Desk to modify user profile data.

For information about working with profile definitions in the Profiles resource, see Running the Profiles Resource. For information about working with the Profile Designer and Users modules in Business Desk, see Business Desks Users. You can also run reports to analyze user data. For information about reports, see User Reports.

Report preparation. Populates OLAP cubes with the import data, prepares the data for report generation, and refreshes the cubes after a deletion. This task must be performed after every import and delete task.

Product catalog import. Imports product data from your catalogs. Importing product data provides your transaction reports with more descriptive product information than is available in transaction data. You can also run reports to analyze the sale of products. For information about reports, see Product Sale Reports.

Configuration synchronization. Synchronizes the Data Warehouse with your Commerce Server application after you make changes to configuration settings. If the online site configuration changes, this task should be performed before any other task.

See Also

Configuring Web Log Files for Import

Configuring Web Log File Import Properties

Adding a Non-Commerce Application and Web Server


Import Processes

Commerce Server provides five import processes for importing and transforming data in the Data Warehouse.

  • Web Log File Data Import Process

  • Transaction Data Import Process

  • User Data Import Process

  • Campaign Data Import Process

  • Product Catalog Data Import Process

Web Log File Data Import Process

This process imports Web log file data generated by your Web servers. The Web log files must be in the World Wide Web Consortium (W3C) extended Web log file format. For information about configuring Web log files in the W3C extended Web log file format, see Configuring Web Log Files for Import.

You use the Web server log import task to provide information about what log file to import and where to find it. The Web log file import process looks for the log files in the specified location, parses them, and applies the properties that you set in the Advanced Web Server Log Import Properties dialog box.

If your site has more than one Web server, the Web log file import process combines the files from the different Web servers in memory, and organizes the log file data chronologically. The Web log file import process filters the Web log file data using the import properties you set. It applies a user visit inferential algorithm to transform click data into distinct user and visit counts.

Additionally, if you select to import query strings associated with the Web site, the Web log file import process imports them. For information about configuring Web log files, see Configuring Web Log File Import Properties.

Commerce Server supports Web servers that are not running Internet Information Services (IIS) 5.0 and do not include Commerce Server components that are capable of creating log files in the W3C log file format. You can make these Web server log files available to the Data Warehouse for import. For more information about adding applications and Web servers that do not use Commerce Server components, see Adding a Non-Commerce Application and Web Server.

Note

  • The Web log file import process will not import log files while IIS is actively writing to them. Do not import your log file directly from your Web site. Instead, verify that the server is no longer accessing the file, and then copy the file to a different location. You can then import it from the location you selected.

Transaction Data Import Process

This process imports site transaction data when you run the Transaction data import task. Transaction data is stored order data, such as purchase orders and requisition numbers. By running reports on the imported transaction data, you can analyze how individual products are selling, how much is being requisitioned, or how much your customers are purchasing. You can perform a full import of all transaction data from the Commerce Server database, or you can perform an incremental import of transaction data that has not yet been imported into the Data Warehouse.

User Data Import Process

This process imports user profile data when you run the User profile data import task. You collect user data on your Web site with the User Object profile definition. You use the Profile Designer module in Business Desk to designate which user profile properties will be imported into the Data Warehouse. (You can also perform this task using the Profiles resource in Commerce Server Manager.) For information about specifying user data for import into the Data Warehouse, see Profile Definitions.

By running reports on the imported user data, you can analyze whether your user base is growing, and how successful your site is at converting guest users to registered users. The user data import process imports user data into the Data Warehouse in time intervals that you can specify to prevent locking the database table. For example, if you plan to import data for 10,000 users, you can specify 15-minute intervals for user data import, so that your server is not overloaded.

You can perform a full import of all user data from the Commerce Server database, or you can perform an incremental import of user data from the Commerce Server database that has not yet been imported into the Data Warehouse.

Campaign Data Import Process

This process imports campaign data when you run the Campaign data import task. Campaign data includes advertisers, advertisement campaigns, and campaign item information. The campaign import process imports campaign data from the Commerce Server database. By running reports on the imported campaign data, you can analyze the success of your advertising.

Product Catalog Data Import Process

This process imports data about products in your catalog when you run the Product catalog data import task. Product catalog data contains the dimensional information about catalog products, such as name, description, color, and size. The catalog data import process imports the catalog data from the Commerce Server database. Reports such as Product Analysis and Transaction Analysis require catalog data to display properly. If catalog data is not imported into the Data Warehouse, products are identified in reports by their stock keeping unit (SKU) numbers only.

See Also

Configuring Web Log Files for Import

Configuring Web Log File Import Properties

Adding a Non-Commerce Application and Web Server

Adding Properties to Profile Definitions


Data Warehouse Storage Engine

The Data Warehouse storage engine provides three storage processes for loading data into the Data Warehouse.

  • Summarization

  • Schema Management

  • Data Loading

Summarization

You use summarization to summarize user, transaction, campaign, and catalog data from the Commerce Server database when you run the Web server log import task and the Report preparation task. Summarizations transform raw data in the Commerce Server database into information in the Data Warehouse that you use to analyze user activity on your Web site. This is done by totaling and counting the related raw data.

For example, 1,000 records of single hits on a particular page are summarized into the information that the page had 1,000 hits. You can use this information to make decisions that will increase traffic on your Web site.

Schema Management

You use schema management to modify the Data Warehouse schema as needed during the import process. For example, if you add a new property to the User Object profile definition and mark it as exported, the User profile import process adds the new column to the Data Warehouse schema when user profile data containing that property is imported.

The following table lists the import process and describes the schema changes the Data Warehouse storage engine makes to the Data Warehouse schema.

Import process | Data Warehouse schema change
Web log file | Query strings are added to the schema.
User | User profile properties are added to or removed from the schema.
Product catalog | Product catalog dimensions are added to or removed from the schema.

Data Loading

You use data loading to support the loading of high volumes of data into the Data Warehouse database, using parallel reads and writes.

See Also

Configuring Web Log Files for Import

Configuring Web Log File Import Properties

Adding a Non-Commerce Application and Web Server


OLAP Cubes

Online analytical processing (OLAP) cubes are data structures that the Data Warehouse uses to contain the data you import. The cubes divide the data into subsets, defined by shared dimensions.

A dimension is the descriptive attribute of a measure. For example, a dimension might describe the number of purchases a user makes. The number of purchases is a measure. The user and the products purchased are dimensions. The following figure shows the relationship between dimensions and measures. For more information about OLAP cubes, see SQL Server Books Online.

Dimensions and measures
Units
Time
Product
Time
Product
Dimension
Tables
Geographic
Geographic
Dimension
Measures

The OLAP cubes used by Commerce Server are created during the unpacking process and are populated and processed for data retrieval when the Report preparation task is run. Storing data in cubes increases the speed of data retrieval when you run Web site analysis reports in Business Desk. The following table lists the Commerce Server cubes and dimensions.

Cube | Dimensions
Weekly User Trends | Date Site Week of Year
Campaign | Advertiser Campaign DateHour Events Page Group Site UserType URI
Sales | CustomerOrders Date Products Site UserType
Basket Events | DateHour Events Products RegisteredUser Site UserType
OrderEvents | DateHour Day of Week Events Hour of Day Site UserType Week of Year
Buyer Visits | BuyerType Site UserType
Bandwidth | DateHour Day of Week Hour of Day Site
Users | Date Site UserType
Entry Pages | Date Site URI
Exit Pages | Date Site URI
Web Usage | Date DateHour Day of Week Hour by Day Referrer RegisteredUser SiteUserType Week of Year
Page Usage | Date HTTP Status Is Request Level Directory Site URI Win32Status

See Also

Configuring Web Log Files for Import

Configuring Web Log File Import Properties

Adding a Non-Commerce Application and Web Server


Configuring the Data Warehouse Resource

You must configure the Data Warehouse resource so your Data Warehouse works with Microsoft SQL Server. You can also configure the time zone and start day of the week that the Data Warehouse assigns to imported time data.

To connect your Data Warehouse to SQL Server, you set the connection string during the installation process. You can use Commerce Server Manager to change the user ID and password in the connection string at the global resource level. The Data Warehouse logs in to SQL Server with a user ID and a password.

Note

  • You can change only the user ID and password in the Data Warehouse connection string. To change the entire connection string, you must unpack the site again. . For information about unpacking a site, see Unpacking a Site and Example B: Installing on a Three-Computer Non-clustered Configuration.

To change the connection string at the global resource level

To change the time zone and start day of the week

To change the connection string at the global resource level

  1. Expand Commerce Server Manager, expand Global Resources, right-click Data Warehouse, and then click Properties.

  2. On the Connection tab of the Data Warehouse Properties dialog box, do the following:
    Use this | To do this
    SQL Server Authentication | Click to use a supplied user name and password to authenticate your login information.
    User ID | Type the user ID to use for authentication when you log in.
    Password | Type the password to use for authentication when you log in.

  3. To save your changes, click OK.

To change the time zone and start day of the week

  1. Expand Commerce Server Manager, expand Global Resources, right-click Data Warehouse, and then click Properties.

  2. On the Time tab of the Data Warehouse Properties dialog box, do the following:
    Use this | To do this
    Adjust timezone to | Select the time zone from the drop-down list.
    Start day of the week | Select the start day of the week from the drop-down list.

  3. To save your changes, click OK.

Note

  • The SQL Server start day of the week is used in reports. The start day of the week you set in the Data Warehouse Properties dialog box is used to aggregate data imported from Web log files in weekly intervals.

The Data Warehouse resource is configured. You must configure Web log files for import and synchronize your site configuration with the Data Warehouse before importing data into the Data Warehouse.

See Also

Installing Commerce Server

Unpacking a Site

Configuring a Web Server


Configuring Web Log Files for Import

Before you can import Web log files into the Data Warehouse, you must configure the Web log file properties to use the World Wide Web Consortium (W3C) log file format. You configure the Web log file properties using Internet Services Manager.

To configure the default Web site properties for import

To specify the location of a log file to the Data Warehouse

To configure the default Web site properties for import

  1. Expand Internet Information Services, expand the server on which you unpacked the site, right-click the default Web site, and then click Properties.

  2. On the Web Site tab, in the Default Web Site Properties dialog box, do the following:
    Use this | To do this
    Enable Logging | Select this box if you want to enable the log to record Web site activity.
    Active log format | Select W3C Extended Log File Format from the drop-down list.

  3. Click Properties.

  4. On the Extended Properties tab, in the Extended Logging Properties dialog box, do the following:
    Select this | To import this
    Date | The date on which activity occurred on your Web site.
    Time | The time the activity occurred.
    Client IP Address | The IP address of the client that accessed your server.
    User Name | The name of the user who accessed your server.
    Server IP Address | The IP address of the server on which the log entry was generated.
    Server Port | The port number the client is connected to.
    Method | The action the client was trying to perform (for example, open a Web page).
    URI Stem | The Uniform Resource Identifier (URI) stem of the resource accessed, for example, an HTML page.
    URI Query | The query, if any, that the client was trying to perform. For example, a search string for which a client was seeking a match.
    HTTP Status | The status of the action, in HTTP terms.
    Win32 Status | The status of the action, in terms used by Microsoft Windows.
    Bytes Sent | The number of bytes sent by the server.
    Bytes Received | The number of bytes received by the server.
    User Agent | The browser used on the client.
    Cookie | The content of the cookie sent or received.
    Referrer | The site that directed the user to the current site.

    Important

    • You must select Client IP address, URI stem, and Time in order for Web log files to be imported correctly. Include the Date property to ensure accuracy in the reporting of dates. For information about setting Web server properties, see Configuring a Web Server.
  5. Click OK to exit the Extended Logging Properties dialog box, and then click OK to exit the Default Web Site Properties dialog box.

The Web log file properties are configured in the W3C log file format.

To specify the location of a log file to the Data Warehouse

  1. Expand Internet Information Services, expand the server name, right-click Default Web Site, and then click Properties.

  2. In the Default Web Site Properties dialog box, click Properties.

  3. In the Extended Logging Properties dialog box, on the General Properties tab, type the path of the log file directory in the Log file directory box.

  4. Click OK to exit the Log file Properties dialog box, and then click OK to exit the Default Web Site Properties dialog box.

The Data Warehouse can find the log file for your Web site. After you have configured the default Web site properties for import into the Data Warehouse, you will need to synchronize the IIS properties in Commerce Server Manager with the properties in the IIS metabase and the Data Warehouse. For instructions for synchronizing the IIS properties with the Data Warehouse, see Synchronizing Site Configuration with the Data Warehouse.

See Also

Configuring a Web Server

Configuring an Application

Adding a Non-Commerce Application and Web Server

Synchronizing Site Configuration with the Data Warehouse


Synchronizing Site Configuration with the Data Warehouse

You use the Configuration synchronization task to synchronize your site configuration with the Data Warehouse, so that any changes you make to the site configuration are propagated to the Data Warehouse. You must run the synchronize task before you run the import or delete tasks.

To synchronize site configuration with the Data Warehouse

  1. Expand Microsoft SQL Servers, expand SQL Server Group, and then expand the server on which your Data Warehouse is installed.

  2. Right-click Data Transformation Services, and then click New Package.

    Alternatively, if you are changing an existing package, right-click Data Transformation Services, click All Tasks, and then select Open Package. Select the package you want to change, and then click Open.

  3. On the Task menu, click Configuration synchronization (Commerce Server).

  4. In the Synchronize DW Properties dialog box, do the following:
    Use this | To do this
    Description | Type a description for the synchronize task.
    Site name | Select from the drop-down list the site that you want to synchronize with the Data Warehouse.

  5. Click OK.

  6. On the Package menu, click Execute.

    The Executing Package dialog box appears, showing the progress of your synchronization. When the process is complete, the Package Execution Results dialog box informs you it completed successfully.

  7. Click OK, and then click Done.

The Data Warehouse is synchronized with your Commerce Server site configuration. You can now configure Web log file import properties and import data into the Data Warehouse.

See Also

Configuring Web Log Files for Import

Configuring a Web Server

Configuring an Application

Adding a Non-Commerce Application and Web Server


Configuring Web Log File Import Properties

You can configure five sets of properties to control and customize the data you import into the Data Warehouse from your Web log files. The settings that you select for these properties can improve your analysis of the data, as well as make your import processes faster and your Data Warehouse more manageable.

Note

  • Unless specified otherwise, these settings apply to all of the applications in the site.

The following properties control what data is imported from your Web log files into the Data Warehouse:

  • Default Files. Ensure that the hit counts for unique visitors to your site default page are accurate, allowing for redirects and multiple versions of your URL.

  • Excludes. Prevent the following data from being imported in the Data Warehouse: hits from certain hosts, requests for specific file types or expressions, and hits by crawlers.

  • Inferences. Customize the assumptions made during import about users and visits in order to best meet the analysis needs of your organization.

  • Log Files. Customize the response to time overlaps in log files.

  • Query Strings. Import Web site query strings, so that the data associated with them can be analyzed.

See Also

Data Warehouse Components

Synchronizing the Data Warehouse with Your Application

Importing Data into the Data Warehouse

Preparing to Create Reports


Default Files

A default file, also known as a directory index file or home page, is the Web page that users reach when they type a site URL that does not contain a specific file name in the Address box of their browser. For example, users reach the www.microsoft/default.htm page when they type either www.microsoft.com or www.microsoft.com/default.htm in their browser. Web log files, however, count the two URLs as hits to two different pages.

You can set the Default Files option in Commerce Server 2000 to designate multiple URLs to be counted as hits to the same page. You can use this option to create redirects and multiple paths into your site without decreasing the accuracy of your total site user statistics.

In addition, you can choose to display file name strings without their top-level directories before they are imported. This practice makes it easier to work with your files if your site directories are stored in a subdirectory that you do not need to view in your reports.

For Internet Information Services (IIS) 5.0, this setting is synchronized automatically during setup with the base URL directory index files that are listed in IIS.

Note

  • For non-IIS servers, the default settings are Index.html, Index.htm, and Default.htm. If these settings are not correct for your site, change them to ensure that your request count will be accurate.

To set a directory index file

  1. Expand Microsoft SQL Server, expand SQL Server Group, and then expand the server on which your Data Warehouse is installed.

  2. Right-click Data Transformation Services, and then click New Package.

    Alternatively, if you are changing an existing package, right-click Data Transformation Services, click All Tasks, and then select Open Package. Select the package you want to change, and then click Open.

  3. On the Task menu, click Web server log import (Commerce Server).

  4. In the Import Web Server Logs dialog box, click Advanced.

  5. On the Default Files tab, in the Advanced Web Log Import Properties dialog box, do the following:
    Use this | To do this
    Truncate top level directory from file system paths | Select this box to display file name strings without their top-level directories.
    Directory index file | Type the name of the file you want to designate as a directory index file.
    Add | Click to add the new directory index file to the default file list.

  6. Click Apply, and then click OK.

The directory index files have been set for the Web log file import process. You can continue to configure the Web log file import process, or you can import data into the Data Warehouse. You must synchronize your site configuration with the Data Warehouse before importing data into the Data Warehouse.

See Also

Data Warehouse Components

Configuring Web Log File Import Properties

Importing Data into the Data Warehouse


Excludes

You can exclude certain types of data from your imports. By excluding certain data, you keep the size of your Data Warehouse manageable, and page requests are more accurately defined in your reports. You can exclude the following types of data:

  • Hosts. You can exclude data from users who originate from certain hosts (for example, employees or software testers). This feature is typically used to exclude internal hosts. However, you can specify any host for exclusion.

    The Data Warehouse will not import hits associated with hosts that you exclude. The hits associated with the excluded hosts are, however, included in some aggregation-only reports, such as Summary Hit Counts and Bandwidth Data.

    When you enter a host name to exclude, you must type a string that Commerce Server 2000 can use to search the log files. For example, www.microsoft.com will exclude information from users whose host is www.microsoft.com. Do not include spaces in the name you type.

  • File types. Even though one page in your Web site may include several files, you want to ensure that only one page request is counted rather than a hit for each file in a page. For example, if a page includes graphics that are stored in separate files but are logically part of the page, exclude the graphics files from the import for more accurate hit counts. You can set the Excludes property to exclude files by specifying the file name extensions of the types of files you want to exclude.

    By default, files with the extensions .gif, .jpg, .jpeg, .css, and .cdf are excluded from Commerce Server imports. You can also remove file extensions from the exclude list. The name you type is the string that Commerce Server will search for in the log files. You must type the extension exactly.

  • File expressions. In addition to excluding a file from being imported by its file extension, you can exclude a file by its file path. You can provide a complete file expression for an individual file, or you can use wildcard characters to exclude a group of files that share similar characters in their expressions.

    File expressions are not case sensitive. Do not include an underscore (_) or spaces. You must type the exact string for which you want Commerce Server to search.

    The following table lists the wildcard characters you can use in file expressions.

    Character Description Example
    * Matches any number of characters in a character string t* matches Test, total, and Terrific
    ? Matches any single alphanumeric character Te?t matches Test and text

  • Crawlers. Search engines rely on crawlers that pace through the World Wide Web checking for certain content, titles, key words, and so on. By default, crawlers are excluded from import to prevent hits by Internet search engines, robots, and any other user agent from being imported into the Data Warehouse. (These hits, however, are used in reports such as Summary Hit Counts and Bandwidth Data.)

    You can find a list of crawlers that are excluded by default in the Commerce Server root directory, in the file Crawler.ini. The default list includes the major crawlers that are excluded by the major Web auditing organizations. You can add new crawlers to the exclude list or restore crawlers for import; however, restoring crawlers may reduce your overall system performance.

The Excludes tab of the Advanced Web Log Import Properties dialog box provides a drop-down list from which you can choose the type of data you want to work with. Select the All option from the list if you want to see a list of all the exclusions.

By default, excluding data from import excludes that data for all applications running on your site. You can also exclude data from specific applications, while including similar data from other applications on your site.

For example, if you have two site applications, Application1 and Application2, and each application contains a directory named /Examples. You can choose to exclude the content in the /Examples directory for both applications, or you can specify that data should be excluded only from the /Examples directory of Application1. The content in the Application2 /Examples directory will continue to be imported.

To add an import exclusion

To delete an import exclusion

To add an import exclusion

  1. Expand Microsoft SQL Server, expand SQL Server Group, and then expand the server on which your Data Warehouse is installed.

  2. Right-click Data Transformation Services, and then click New Package.

    Alternatively, if you are changing an existing package, right-click Data Transformation Services, click All Tasks, and then select Open Package. Select the package you want to change, and then click Open.

  3. On the Task menu, click Web server log import (Commerce Server).

  4. In the Import Web Server Logs dialog box, click Advanced.

  5. In the Advanced Web Log Import Properties dialog box, on the Excludes tab, do the following:
    Use this | To do this
    Include default crawler list for the exclude criteria | Select this check box to prevent crawlers on the default crawler list from being imported.
    Add | Click to open the Excludes dialog box to create a new exclude item.

  6. In the Excludes dialog box, do the following:
    Use this | To do this
    Select exclude category | Select the type of exclusion you want to add from the drop-down list.
    Name | Type the string Commerce Server will search for in the log files. For example, type *.gif to exclude graphic files. Commerce Server will not import items that match the string you type. The string cannot contain spaces.
    All applications within a site | Select this option if you want to exclude the item from all applications within a site.
    Selected applications within a site | Select this option if you want to specify an application from which to exclude the item.
    Select all | Select this option to exclude the data from all of the applications listed above the button.
    Deselect all | Select this option to cancel the selection of all of the applications listed above the button.

  7. Click OK to close the Excludes dialog box and return to the Excludes tab of the Advanced Web Log Import Properties dialog box.

  8. Continue to add exclusions. When you are finished, click Apply, and then click OK to save your additions and close the dialog box.

To delete an import exclusion

  1. Expand Microsoft SQL Server, expand SQL Server Group, and then expand the server on which your Data Warehouse is installed.

  2. Right-click Data Transformation Services, and then click New Package.

    Alternatively, if you are changing an existing package, right-click Data Transformation Services, click All Tasks, and then select Open Package. Select the package you want to change, and then click Open.

  3. On the Task menu, click Web server log import (Commerce Server).

  4. In the Import Web Server Logs dialog box, click Advanced.

  5. In the Advanced Web Log Import Properties dialog box, on the Excludes tab, do the following:
    Use this | To do this
    Exclude Type | Select the exclude item you want to delete.
    Remove | Remove the exclude item.

  6. Click Apply, and then click OK to close the dialog box.

The import exclusions are configured for the Web log file import process. You can continue to configure the Web log file import properties, or you can import data into the Data Warehouse. You must synchronize your site configuration with the Data Warehouse before you import data into the Data Warehouse.

See Also

Data Warehouse Components

Configuring Web Log File Import Properties

Importing Data into the Data Warehouse


Inferences

Commerce Server 2000 uses the concept of user visits to understand Web site traffic. A visit can be defined as a set of requests from the same user within a specified time span. However, the identification of users is not completely accurate because the Web client computers send only a limited amount of data to the Web server computer. Commerce Server attempts to identify users based on the properties in the Web log file. Inferences refer to the process of identifying unique users based on the data in the Web log file. You can set user and visit inferences in the Data Warehouse to customize the assumptions made during import about users and visits to best meet the analysis needs of your organization.

Users

Visits

Users

You may want to identify users as individuals whose browsing or buying patterns are of interest.

Commerce Server offers three options for identifying users.

  • Use Commerce Server identification cookies for inferences. You can set Commerce Server to automatically issue encrypted cookies that identify distinct users and associate them with user profiles in the Commerce Server database.

  • Use user names for inferences. If your users register with your site, they can be identified by their chosen user names.

  • Use custom cookie identifiers. You can add a custom cookie identifier.

Note

  • If you previously used Microsoft Site Server 3.0 Commerce Edition (SSCE), the Site Server cookies that were in use at that time are now treated as custom cookies. They appear in the list of custom cookies on the Inferences tab, in the Advanced Web Log Import Properties dialog box, just beneath the text box labeled Enter new custom cookie identifier.

By default, all three methods are enabled for Commerce Server. Unless you disable one or more of these methods, they will be used in the following order to identify users: Commerce Server identification cookies, custom cookie identifiers, and then user names. If these methods are not enabled or available, users are identified by their IP address and client agent.

To set an inference for users

  1. Expand Microsoft SQL Server, expand SQL Server Group, and then expand the server on which your Data Warehouse is installed.

  2. Right-click Data Transformation Services, and then click New Package.

    Alternatively, if you are changing an existing package, right-click Data Transformation Services, click All Tasks, and then select Open Package. Select the package you want to change, and then click Open.

  3. On the Task menu, click Web server log import (Commerce Server).

  4. In the Import Web Server Logs dialog box, click Advanced.

  5. In the Advanced Web Log Import Properties dialog box, on the Inferences tab, do the following:
    Use this | To do this
    Use Commerce Server identification cookies for inferences | Select this check box if you want to use Commerce Server cookies for user inferences.
    Use user names for inferences | Select this check box if you want to use unique user names for inferences.
    Use custom cookie identifiers | Select this check box if you want to use custom cookies for inferences.
    Enter new custom cookie identifier | Type the identifier for your custom cookie in this box.
    Add | Click to add the new custom cookie identifier.
    Remove | Click to remove the selected custom cookie identifiers.
    Up | Click to move the selected custom cookie identifier up in the list. Cookies are run in the order that they appear in this list.
    Down | Click to move the selected custom cookie identifier down in the list. Cookies are run in the order that they appear in this list.

  6. Click Apply, and then click OK.

The user inference is configured for the Web log file import process. You can continue to configure the Web log file import properties, or you can import data into the Data Warehouse. You must synchronize your site configuration with the Data Warehouse before you import data into the Data Warehouse.

Visits

A visit to a Web site is the length of time a unique user spends interacting with that Web site. Typically, a visit begins when a user accesses a site either by clicking a link to the site, or by typing the site URL into the Address box of their browser. Determining when a visit ends is more difficult. If the user closes the browser in the middle of a session, minimizes the browser, or types a new URL into the Address box of the browser, there is no log entry indicating that the visit has ended.

To compensate for the lack of a clear indication that a visit has ended, Commerce Server sets a default visit timeout of 30 minutes of user inactivity to declare that a visit has ended. If you choose, you can change the length of the visit timeout to better meet the needs of your Web site. If the visit timeout elapses, ending the visit, and the user returns to the site a moment later, the report will show two visits.

Note

  • In some cases, your server may not log user visit activity chronologically, which may cause data for a visit to be imported out of chronological order. The Data Warehouse can adjust for this up to the length of the visit timeout. However, if a visit exceeds the visit timeout, the accuracy of your data will be impacted.

To set an inference for visits

  1. Expand Microsoft SQL Server, expand SQL Server Group, and then expand the server on which your Data Warehouse is installed.

  2. Right-click Data Transformation Services, and then click New Package.

    Alternatively, if you are changing an existing package, right-click Data Transformation Services, click All Tasks, and then select Open Package. Select the package you want to change, and then click Open.

  3. On the Task menu, click Web server log import (Commerce Server).

  4. In the Import Web Server Logs dialog box, click Advanced.

  5. In the Advanced Web Log Import Properties dialog box, on the Inferences tab, type a number in the Visit Inferences box to designate the minutes of user inactivity to allow before a visit ends.

  6. Click Apply, and then click OK.

The visit inference is configured for the Web log file import process. You can continue to configure the Web log file import properties, or you can import data into the Data Warehouse. You must synchronize your site configuration with the Data Warehouse before you import data into the Data Warehouse.

See Also

Data Warehouse Components

Configuring Web Log File Import Properties

Importing Data into the Data Warehouse


Log Files

You use the time overlap property to eliminate redundancy that can occur when log files contain requests that overlap in time. You use the log file rotation property to eliminate redundancy or the loss of data that can occur when Log files are rotated among servers to keep the log files from getting too large.

Without the time overlap and log file rotation settings, it is impossible to import log files into the Data Warehouse without losing activity data because log files are continually created as your site operates. Your files may contain data for overlapping time periods if you run log files on separate servers, interrupt and resume logging on a single server, accidentally re-import a log file, or concatenate distinct log files.

Time Overlaps

Log File Rotation

Time Overlaps

Time overlaps may occur if you have multiple servers associated with a site, interrupt and resume logging on a single server, accidentally re-import a log file, or concatenate distinct log files. (Concatenation makes tracking time overlaps extremely difficult and therefore should be avoided.) The default time overlap period for Commerce Server is 30 minutes.

When a time overlap is detected during import, by default the overlapping requests are discarded and the remaining requests are imported. You can change both the time overlap period and the action you want to occur when an overlap is detected.

If you import a log file accidentally, you can delete the log file using the Data deletion task. For information about deleting log files, see Deleting Data from the Data Warehouse.

The following figure shows how the four overlap actions, Discard records and proceed, Import all records, Stop the import, and Stop all imports, affect the portions of the second and third log files that are retained when an overlap is detected.

Web log file overlap
Portion of log file not imported
Portion of log file imported
Log file
Log File 3
Log File 2
Log File 1
Discard records and proceed
Import all
records
Stop the
import
Stop all
imports

To configure Web log file time overlaps

  1. Expand Microsoft SQL Server, expand SQL Server Group, and then expand the server on which your Data Warehouse is installed.

  2. Right-click Data Transformation Services, and then click New Package.

    Alternatively, if you are changing an existing package, right-click Data Transformation Services, click All Tasks, and then select Open Package. Select the package you want to change, and then click Open.

  3. On the Task menu, click Web server log import (Commerce Server).

  4. In the Import Web Server Logs dialog box, click Advanced.

  5. In the Advanced Web Log Import Properties dialog box, on the Log Files tab, do the following:
    Use this | To do this
    Number of minutes that records must overlap | Type the number of minutes that records must overlap.
    If overlap is detected Select an action to take if an overlap is detected:
    • Discard records and proceed. (Default setting) Discards all overlap requests and imports the remaining requests.

    • Import all records. Imports all requests, including overlap requests.

    • Stop the import. Does not import the log file containing overlap requests. All other log files are imported.

    • Stop all imports. Stops all log file imports. You must delete the imported log file if you do not want to keep the data imported before the overlap request was detected.

    Note

    • Select Stop the import or Stop all Imports to troubleshoot problems you may experience with importing.
  6. Click Apply, and then click OK.

The time overlap property is now configured for the Web log file import process. You can continue to configure the Web log file import properties, or you can import data into the Data Warehouse. You must synchronize your site configuration with the Data Warehouse before you import data into the Data Warehouse.

Log File Rotation

Log file rotations cause an arbitrary cutoff of data in log files because data for some visits are divided between the end of one log file and the beginning of the next. You can choose to store, commit, or disregard the open visits at the end of your import process.

To set log file rotation

  1. Expand Microsoft SQL Server, expand SQL Server Group, and then expand the server on which your Data Warehouse is installed.

  2. Right-click Data Transformation Services, and then click New Package.

    Alternatively, if you are changing an existing package, right-click Data Transformation Services, click All Tasks, and then select Open Package. Select the package you want to change, and then click Open.

  3. On the Task menu, click Web server log import (Commerce Server).

  4. In the Import Web Server Logs dialog box, click Advanced.

  5. In the Advanced Web Log Import Properties dialog box, on the Log Files tab, do the following:
    Use this To do this
    When import is completed Select an action to take with the open visits at the end of your import process:
    • Store open visits for the next import. (Default setting) Reconstructs the actual visit as if there were one seamless log file. This option takes slightly more time because the open visits must be called up from the cache at each new import. You must import log files in chronological order for this option to work correctly.

    • Commit all open visits to database. The visit count is higher at the opening and closing of the log file period because visits that span those two periods are counted twice.

    • Discard open visits. The report count is lower at the closing of the log file period, because visits that have not been closed are dropped.

  6. Click Apply, and then click OK.

The log file rotation property is now configured for the Web log file import process. You can continue to configure the import properties, or you can import data into the Data Warehouse. You must synchronize your site configuration with the Data Warehouse before you import data into the Data Warehouse.

See Also

Data Warehouse Components

Configuring Web Log File Import Properties

Importing Data into the Data Warehouse


Query Strings

If your site uses query strings, you can record the query strings in log files and import them into the Data Warehouse. Query strings can be used in your site for searching or running executable files. If you have a list of query strings that your site uses, you can enable reporting on the content associated with those query strings.

By default, query strings are stored with the Uniform Resource Identifier (URI) in the Data Warehouse. The query strings allow you to perform HTML title lookups for the pages on your site that use query strings. However, if there are many different combinations of parameter names and values for the query strings in your log files, the number of imported requests could increase substantially, which may reduce system performance. If this occurs, you may want to discontinue storing query strings with the URI.

Notes

  • The Data Warehouse can import a combined maximum of 256 single- and multi-valued query strings.

  • Imported query strings can consist of a maximum of 150 single-valued query strings or a maximum of 256 multi-valued query strings. Importing too many query strings may cause the Web log import process to fail.

  • The Data Warehouse limits the length of imported multi-valued strings (including query strings) to 512 characters. Any multi-valued query string consisting of more than 512 characters is truncated to 512 characters when it is imported.

To configure query strings for import

To remove a query string from import

To view the properties of a query string configuration

To configure query strings for import

  1. Expand Microsoft SQL Server, expand SQL Server Group, and then expand the server on which your Data Warehouse is installed.

  2. Right-click Data Transformation Services, and then click New Package.

    Alternatively, if you are changing an existing package, right-click Data Transformation Services, click All Tasks, and then select Open Package. Select the package you want to change, and then click Open.

  3. On the Task menu, click Web server log import (Commerce Server).

  4. In the Import Web Server Logs dialog box, click Advanced.

  5. In the Advanced Web Log Import Properties dialog box, on the Query Strings tab, do the following:
    Use this | To do this
    Save query strings with URI | Select this box if to store your query strings together with their associated URIs in the Data Warehouse.
    Add | Click to open the Query Strings dialog box.

  6. In the Query Strings dialog box, do the following:
    Use this | To do this
    Name Type the name of the query string exactly as it appears in your log files.

    The name cannot match any of the default Data Warehouse columns; it also cannot contain "CEVT" (this grouping of letters is reserved for Commerce Server query strings). In addition, the name cannot contain spaces or include the characters: ', ", +, &, ^, ', ", {,}, <, >, or =.

    All applications within a site | Select this option to import query strings from all applications within the site.
    Selected applications within a site | Select this option to select the applications for which you want to import query strings.
    Select data type Select the data type of your query string from this drop-down list. Four data types are possible: integer, string, date/time, or real.

    The maximum number of characters for the data type string is 255 characters.
    Multivalue data type | Select this check box if your query string has a multi-value data type.

  7. Click OK to close the Query Strings dialog box.

  8. Click Apply, and then click OK.

Query strings are configured for the Web log file import process. You can continue to configure the Web log file import properties, or you can import data into the Data Warehouse. You must synchronize your site configuration with the Data Warehouse before you import data into the Data Warehouse.

To remove a query string from import

  1. Expand Microsoft SQL Server, expand SQL Server Group, and then expand the server on which your Data Warehouse is installed.

  2. Right-click Data Transformation Services, and then click New Package.

    Alternatively, if you are changing an existing package, right-click Data Transformation Services, click All Tasks, and then select Open Package. Select the package you want to change, and then click Open.

  3. On the Task menu, click Web server log import (Commerce Server).

  4. In the Import Web Server Logs dialog box, click Advanced.

  5. In the Advanced Web Log Import Properties dialog box, on the Query Strings tab, select the query string you want to remove, and then click Remove.

  6. Click Apply, and then click OK.

The query string is removed from the Web log file import process. You can continue to configure the Web log file import properties, or you can import data into the Data Warehouse. You must synchronize your site configuration with the Data Warehouse before you import data into the Data Warehouse.

To view the properties of a query string configuration

  1. Expand Microsoft SQL Server, expand SQL Server Group, and then expand the server on which your Data Warehouse is installed.

  2. Right-click Data Transformation Services, and then click New Package.

    Alternatively, if you are changing an existing package, right-click Data Transformation Services, click All Tasks, and then select Open Package. Select the package you want to change, and then click Open.

  3. On the Task menu, click Web server log import (Commerce Server).

  4. In the Import Web Server Logs dialog box, click Advanced.

  5. In the Advanced Web Log Import Properties dialog box, on the Query Strings tab, click Properties to open the Query Strings dialog box. (You cannot change any of the properties shown.)

    Note

    • To change properties, you must first remove the query string for import, and then add it again with the new properties you want.
  6. Click OK, and then click OK again.

You can continue to configure the Web log file import properties, or you can import data into the Data Warehouse. You must synchronize your site configuration with the Data Warehouse before you import data into the Data Warehouse.

See Also

Data Warehouse Components

Configuring Web Log File Import Properties

Importing Data into the Data Warehouse


Importing Data into the Data Warehouse

You use the Commerce Server import tasks to import data into the Data Warehouse.

This section contains:

  • Importing Web Log File Data

  • Importing Catalog Data

  • Importing Campaign Data

  • Importing Transaction Data

  • Importing User Profile Data


Importing Web Log File Data

You use the Web server log import task to import Web log file data from your site. You determine the import frequency for the data by analyzing traffic at your site. The more traffic your Web site has, the more frequently you should import Web log file data.

You can import log files from Web sites that are not running Internet Information Services (IIS) 5.0 and do not include Commerce Server components. For more information about adding applications and Web servers that do not use Commerce Server components, see Adding a Non-Commerce Application and Web Server.

Before you import Web log file data, you must synchronize your site configuration with the Data Warehouse by executing the Configuration synchronization task. After you import Web log file data, you must run the Report preparation task, which organizes the imported data into designated online analytical processing (OLAP) cubes.

To import Web log files into your Data Warehouse

  1. Expand Microsoft SQL Server, expand SQL Server Group, and then expand the server on which your Data Warehouse is installed.

  2. Right-click Data Transformation Services, and then click New Package.

    Alternatively, if you are changing an existing package, right-click Data Transformation Services, click All Tasks, and then select Open Package. Select the package you want to change, and then click Open.

  3. On the Task menu, click Web server log import (Commerce Server).

  4. In the Import Web Server Logs dialog box, do the following:
    Use this | To do this
    Description | Type a description for the import task.
    Site name | Select from the drop-down list the name of the Web site that contains the Web server log you are importing.
    Application | Click to sort the list of log files by application.
    Machine (Computer) | Click to sort the list of log files by computer.
    IIS Web Site | Click to sort the list of log files by IIS Web site.
    Log File Path | Click to sort the list of log files by log file path.
    Log file path | Type the path of the Web log file you want to import, or click the ellipsis [...] button to browse for the log file path.
    View Log Files | Click to open the Web Server Log Files dialog box, select the Web log files you want to import from the Web Server Log Files list, and then click OK to return to the Import Web Server Logs dialog box.
    Import all log files since last import | Select this option to specify that all log files created since the last import will be imported.
    Import log files based on date/time range | Select this option to specify that only log files created between the Start date/time and End date/time will be imported.
    Start date/time | Type the date and time for the beginning of the range from which log files will be imported. This option is available only if you select the Import log files based on date/time range option.
    End date/time | Type the date and time for the end of the range from which log files will be imported. This option is available only if you select the Import log files based on date/time range option.

  5. Click OK.

  6. On the Package menu, click Execute.

    The Executing Package dialog box appears, showing the progress of your import. When the import process is complete, the Package Execution Results dialog box informs you it completed successfully.

    Note

    • If the Web log file import process fails, run the Data deletion task to delete the data associated with that Web log file, and then run the Report preparation task to refresh the OLAP cubes.
  7. Click OK, and then click Done.

The data from the Web log file is imported into the Data Warehouse. You must run the Report preparation task to organize the imported data into the designated OLAP cubes.

Notes

  • You can add multiple Data Transformation Services (DTS) tasks to a package, add sequencing or workflow information, and then run all the tasks in the package.

  • You can refine your import process by setting a variety of advanced Web log file import properties. For information about configuring Web log file import properties, see Configuring Web Log File Import Properties. For information about setting Web server properties, see Configuring a Web Server.

See Also

Data Warehouse Components

Configuring Web Log File Import Properties

Synchronizing Site Configuration with the Data Warehouse

Preparing to Create Reports

Deleting Data from the Data Warehouse


Importing Catalog Data

You use the Product catalog import task to import catalog data. Before you import catalog data, you must synchronize your site configuration with the Data Warehouse by executing the Configuration synchronization task. After you import catalog data, you must run the Report preparation task, which organizes the imported data into designated online analytical processing (OLAP) cubes.

Note

  • You must use the full load option and perform a full import the first time you import catalog data into the Data Warehouse. After you have imported catalog data, use the incremental load option to import only new data, created since you last imported catalog data.

To import catalog data into your Data Warehouse

  1. Expand Microsoft SQL Server, expand SQL Server Group, and then expand the server on which your Data Warehouse is installed.

  2. Right-click Data Transformation Services, and then click New Package.

    Alternatively, if you are changing an existing package, right-click Data Transformation Services, click All Tasks, and then select Open Package. Select the package you want to change, and then click Open.

  3. On the Task menu, click Product catalog import (Commerce Server).

  4. In the Catalog Import Properties dialog box, do the following:
    Use this | To do this
    Description | Type a description for this import task.
    Site name | Select from the drop-down list the site that contains the data you want to import.
    Incremental load | Select this option to import only new catalog data based on a previous import.
    Full load | Select this option to import all catalog data.

  5. Click OK.

  6. On the Package menu, click Execute.

    The Executing Package dialog box appears, showing the progress of your import. When the import process is complete, the Package Execution Results dialog box informs you it completed successfully.

  7. Click OK, and then click Done.

Catalog data is imported into the Data Warehouse. You must run the Report preparation task to organize the imported data into the designated OLAP cubes.

Note

  • You can add multiple Data Transformation Services (DTS) tasks to a package, add sequencing or workflow information, and then run all the tasks in the package.

See Also

Data Warehouse Components

Importing Data into the Data Warehouse

Synchronizing Site Configuration with the Data Warehouse

Preparing to Create Reports


Importing Campaign Data

You use the Campaign data import task to import campaign data. Before you import campaign data, you must synchronize your site configuration with the Data Warehouse by running the Configuration synchronization task. After you import campaign data, you must run the Report preparation task, which organizes the imported data into designated online analytical processing (OLAP) cubes.

To import catalog data into your Data Warehouse

  1. Expand Microsoft SQL Server, expand SQL Server Group, and then expand the server on which your Data Warehouse is installed.

  2. Right-click Data Transformation Services, and then click New Package.

    Alternatively, if you are changing an existing package, right-click Data Transformation Services, click All Tasks, and then select Open Package. Select the package you want to change, and then click Open.

  3. On the Task menu, click Campaign data import (Commerce Server).

  4. In the Campaign Import Properties dialog box, do the following:
    Use this | To do this
    Description | Type a description for this import task.
    Site name | Select from the drop-down list the site that contains the data you want to import.

  5. Click OK.

  6. On the Package menu, click Execute.

    The Executing Package dialog box appears, showing the progress of your import. When the import process is complete, the Package Execution Results dialog box informs you it completed successfully.

  7. Click OK, and then click Done.

Campaign data is imported into the Data Warehouse. You must run the Report preparation task to organize the imported data into the designated OLAP cubes.

Note

  • You can add multiple Data Transformation Services (DTS) tasks to a package, add sequencing or workflow information, and then run all the tasks in the package.

See Also

Data Warehouse Components

Importing Data into the Data Warehouse

Synchronizing Site Configuration with the Data Warehouse

Preparing to Create Reports


Importing Transaction Data

You use the Transaction data import task to import transaction data. Before you import transaction data, you must synchronize your site configuration with the Data Warehouse by executing the Configuration synchronization task. After you import transaction data, you must run the Report preparation task, which organizes the imported data into designated online analytical processing (OLAP) cubes.

Note

  • You must use the full load option and perform a full import the first time you import transaction data into the Data Warehouse. After you have imported transaction data, use the incremental load option to import only new data, created since you last imported transaction data.

To import transaction data into your Data Warehouse

  1. Expand Microsoft SQL Server, expand SQL Server Group, and then expand the server on which your Data Warehouse is installed.

  2. Right-click Data Transformation Services, and then click New Package.

    Alternatively, if you are changing an existing package, right-click Data Transformation Services, click All Tasks, and then select Open Package. Select the package you want to change, and then click Open.

  3. On the Task menu, click Transaction data import (Commerce Server).

  4. In the Transaction Import Properties dialog box, on the General tab, do the following:
    Use this | To do this
    Description | Type a description for this import task.
    Site name | Select from the drop-down list the site that contains the data you want to import.
    Incremental load | Select this option to import only new transaction data (based on a previous import).
    Full load | Select this option to import all transaction data.

  5. Click OK.

  6. On the Package menu, click Execute.

    The Executing Package dialog box appears, showing the progress of your import. When the import process is complete, the Package Execution Results dialog box informs you it completed successfully.

  7. Click OK, and then click Done.

Transaction data is imported into the Data Warehouse. You must run the Report preparation task to organize the imported data into the designated OLAP cubes.

Note

  • You can add multiple Data Transformation Services (DTS) tasks to a package, add sequencing or workflow information, and then run all the tasks in the package.

See Also

Data Warehouse Components

Importing Data into the Data Warehouse

Synchronizing Site Configuration with the Data Warehouse

Preparing to Create Reports


Importing User Profile Data

You use the User profile data import task to import user profile data. User profile data is user data collected on your Web site with the User Object profile definition. For information about creating profile definitions, see Running the Profiles Resource.

Before you import user data, you must synchronize your site configuration with the Data Warehouse by executing the Configuration synchronization task. After you import user data, you must run the Report preparation task, which organizes the imported data into designated online analytical processing (OLAP) cubes. For information about specifying user data for import into the Data Warehouse, see Adding Properties to Profile Definitions.

Note

  • You must use the full load option and perform a full import the first time you import user profile data into the Data Warehouse. After you have imported user profile data, use the incremental load option to import only new data, created since you last imported user profile data.

To import user data into your Data Warehouse

  1. Expand Microsoft SQL Server, expand SQL Server Group, and then expand the server on which your Data Warehouse is installed.

  2. Right-click Data Transformation Services, and then click New Package.

    Alternatively, if you are changing an existing package, right-click Data Transformation Services, click All Tasks, and then select Open Package. Select the package you want to change, and then click Open.

  3. On the Task menu, click User profile data import (Commerce Server).

  4. In the User Import Properties dialog box, do the following:
    Use this | To do this
    Description | Type a description for this import task.
    Site name | Select from the drop-down list the site that contains the data you want to import.
    Query interval (mins.) Type the time interval for the import. User data is imported in time intervals to prevent locking the database table. For example, a Web site with 10,000 users would import user data in 15-minute intervals.

    Setting a smaller value will lock the table for a shorter duration but will increase the number of queries against the table and therefore the time the task takes to run. Setting the value to zero will execute a single query, locking the table for the entire duration of import but may degrade site performance.
    Import start date | Select a date from the drop-down calendar on which to begin your import.
    Incremental load | Select this option to import only new users (based on a previous import).
    Full load | Select this option to import all user data.

  5. Click OK.

  6. On the Package menu, click Execute.

    The Executing Package dialog box appears, showing the progress of your import. When the import process is complete, the Package Execution Results dialog box informs you it completed successfully.

  7. Click OK, and then click Done.

User profile data is imported into the Data Warehouse. You must run the Report preparation task to organize the imported data into the designated OLAP cubes.

Note

  • You can add multiple Data Transformation Services (DTS) tasks to a package, add sequencing or workflow information, and then run all the tasks in the package.

See Also

Data Warehouse Components

Importing Data into the Data Warehouse

Synchronizing Site Configuration with the Data Warehouse

Preparing to Create Reports

Adding Properties to Profile Definitions


Performing Internet Protocol Resolution

You use the IP resolution task periodically to resolve Internet Protocol (IP) addresses. This ensures that the Data Warehouse contains as meaningful data as possible.

When you start an IP resolution task, a cache of already resolved IP addresses is checked in an attempt to resolve the new IP addresses. If unresolved IP addresses remain after the cache has been checked, then the Domain Name System (DNS) server is checked. IP resolution typically has a 60 to 75 percent success rate. IP addresses are resolved in a batch file, which optimizes the connection with your DNS server.

When you start an IP resolution task, by default only the IP addresses without a domain name will be resolved. If you want to capture any possible domain name changes, however, you can choose to resolve all IP addresses. This option updates even the domain names already in the Data Warehouse.

Note

  • You must use the full lookup option the first time you resolve IP addresses in the Data Warehouse. After you have performed a full lookup, you can perform incremental IP resolution to look up only new IP addresses.

To resolve IP addresses

  1. Expand Microsoft SQL Server, expand SQL Server Group, and then expand the server on which your Data Warehouse is installed.

  2. Right-click Data Transformation Services, and then click New Package.

    Alternatively, if you are changing an existing package, right-click Data Transformation Services, click All Tasks, and then select Open Package. Select the package you want to change, and then click Open.

  3. On the Task menu, click IP resolution (Commerce Server).

  4. In the IP Resolution Properties dialog box, do the following:
    Use this | To do this
    Description | Type a description for this task.
    Site name | Select from the drop-down list the site that contains the data for which you want to perform IP resolution.
    Incremental lookup | Select this option to resolve only IP addresses that have not already been resolved.
    Full lookup | Select this option to resolve all IP addresses.
    Local domain name | Type the local domain name of the Domain Name Server (DNS) that is the primary server used to resolve IP addresses.
    Number of days to cache results | Type the number of days to cache resolved IP addresses. The default is 30 days. If you increase the default, IP resolution occurs more quickly. However, domain name changes may not be caught.
    Number of seconds to wait before timeout | Type the number of seconds to specify how long the DNS server is searched before an IP address is marked as unresolved. The default is 60 seconds. If you increase the default, you will resolve more IP addresses, but IP resolution will take longer.
    Number of lookup requests to keep in batch | Type the number of lookup requests to specify the number of IP addresses that are transferred to your DNS server in a batch. The default is 500; the possible range is between 10 and 99,999 requests.

  5. Click OK.

  6. On the Package menu, click Execute.

    The Executing Package dialog box appears, showing the progress of your import. When the import process is complete, the Package Execution Results dialog box informs you it completed successfully.

  7. Click OK, and then click Done.

IP resolution is performed. You must run the Report preparation task to organize the imported data into the designated OLAP cubes. For instructions about running the Report preparation task, see Preparing to Create Reports.

Note

  • You can add multiple Data Transformation Services (DTS) tasks to a package, add sequencing or workflow information, and then run all the tasks in the package at one time.

See Also

About the Data Warehouse

Configuring Web Log File Import Properties

Preparing to Create Reports


Preparing to Create Reports

You use the Report preparation task to populate the online analytical processing (OLAP) cubes with the data in the Data Warehouse. Commerce Server 2000 uses OLAP cubes to organize the summarized data in the Data Warehouse so that the reports run in the Analysis modules complete faster. The Report preparation task must be run every time data is imported into or deleted from the Data Warehouse. For information about OLAP cubes, see SQL Server Books Online.

Notes

  • The first time you run the Report preparation task to populate the OLAP cubes in the Data Warehouse, you must select full cube processing. After you have run the Report preparation task, you can perform incremental cube processing to load only new data into the OLAP cubes.

  • You must also select full cube processing after you delete all data from the Data Warehouse. For information about deleting data from the Data Warehouse, see Deleting Data from the Data Warehouse.

To populate OLAP cubes with data

  1. Expand Microsoft SQL Server, expand SQL Server Group, and then expand the server on which your Data Warehouse is installed.

  2. Right-click Data Transformation Services, and then click New Package.

    Alternatively, if you are changing an existing package, right-click Data Transformation Services, click All Tasks, and then select Open Package. Select the package you want to change, and then click Open.

  3. On the Task menu, click Report preparation (Commerce Server).

  4. In the Prepare Reports Properties dialog box, do the following:
    Use this | To do this
    Description | Type a description of the Report preparation task.
    Site name | Select the site for which you are populating the OLAP cubes.
    Incremental | Select to process the OLAP cubes incrementally.
    Full | Select to process the OLAP cubes in their entirety.

  5. Click OK.

  6. On the Package menu, click Execute.

    The Executing Package dialog box appears, showing the progress of your import. When the import process is complete, the Package Execution Results dialog box informs you it completed successfully.

  7. Click OK, and then click Done.

The data is loaded into the OLAP cubes. You can now use the Commerce Server Business Analytics System, including Commerce Server reports, to analyze the data in the Data Warehouse. For more information about running reports, see Business Desk Analysis.

Note

  • You can add multiple Data Transformation Services (DTS) tasks to the open package, add sequencing or workflow information, and then run all the tasks in the package at one time.

See Also

Data Warehouse Components

Synchronizing Site Configuration with the Data Warehouse

Importing Data into the Data Warehouse


Deleting Data from the Data Warehouse

You use the Data deletion task to delete data from the Data Warehouse. Two types of data are stored in the Data Warehouse: detailed log file data and summarized data. The Data Warehouse creates these types of data by keeping track of specified information as the data is being imported. If a Web log file import fails, you use the Data deletion task to delete that log file from the Data Warehouse. You can also use the Data deletion task to delete all data from the Data Warehouse.

It is important that you frequently delete obsolete log file data so that you do not experience declining performance and limited memory capacity in your Data Warehouse. If you want to maintain historic data from your Commerce Server site, you can extract the data for preservation in reports.

Note

  • Deleting data from individual Web log files requires temporary space in the Data Warehouse database. If a Data deletion task fails, free up space in the Data Warehouse database and repeat the deletion process.

After you delete data from the Data Warehouse, you must run the Report preparation task to refresh the online analytical processing (OLAP) cubes. You must select full cube processing after you delete data from the Data Warehouse.

Note

  • If you delete detailed data imported from an individual Web log file, the log file data accessed by the reports in the Analysis module in Commerce Server Business Desk will remain the same. Only the Entry Path Analysis report is affected by the deletion of detailed data. If you want to delete the data the reports are based on, you must choose to delete all data imported from the Web log file.

To delete log file data

  1. Expand Microsoft SQL Server, expand SQL Server Group, and then expand the server on which your Data Warehouse is installed.

  2. Right-click Data Transformation Services, and then click New Package.

    Alternatively, if you are changing an existing package, right-click Data Transformation Services, click All Tasks, and then select Open Package. Select the package you want to change, and then click Open.

  3. On the Task menu, click Data deletion (Commerce Server).

  4. In the Delete Task dialog box, do the following:
    Use this | To do this
    Description | Type a description for the task.
    Site Name | Select from the drop-down list the site that contains the log files you want to delete.
    Select delete type Select Web Log Imports from the drop-down list.

    Note

    • If you have two sites with different Data Warehouses, and you select All, you will only delete data from the Data Warehouse of the currently selected site. You will not delete data from both Data Warehouses.
    Delete detailed data | Select this option to delete the detailed data associated with the Web log files you want to delete.

  5. Select the check boxes next to the Web log files you want to delete.

  6. Click OK.

  7. On the Package menu, click Execute.

    The Executing Package dialog box appears, showing the progress of your import. When the import process is complete, the Package Execution Results dialog box informs you it completed successfully.

  8. Click OK, and then click Done.

The detailed data of the selected Web log files is deleted from the Data Warehouse. You must run the Report preparation task to organize the imported data into the designated OLAP cubes.

Note

  • You can add additional Data Transformation Services (DTS) tasks to the open package, add sequencing or workflow information, and then run all the tasks in the package at one time.

See Also

About the Data Warehouse

Data Warehouse Components

Configuring a Web Server

Preparing to Create Reports

Importing Data into the Data Warehouse


Extending the Data Warehouse

You can extend the logical schema and the functionality of the Data Warehouse. For information about extending the logical schema of the Data Warehouse and importing custom data into the Data Warehouse, see Working with the Data Warehouse. For information about creating new Data Transformation Services (DTS) tasks, see SQL Server Books Online.

See Also

Working with the Data Warehouse

Data Warehouse Meta-Model


Running Direct Mailer

You use Commerce Server Direct Mailer to send personalized e-mail messages from a Web page, or non-personalized mailings from a flat text file, to large groups of recipients. Direct Mailer can be used as a stand-alone process or integrated into the Campaigns modules in Commerce Server Business Desk.

The centralized design of Direct Mailer makes it easy to administer. Direct Mailer operates at the Commerce Server global resource level. Each site points to the specific group instance of Direct Mailer to be used for that site. This allows you to partition and load balance which sites use Direct Mailer.

Direct Mailer supplies a command line interface that you use to create, run, monitor, and delete Direct Mailer jobs, as well as perform job startup and recovery tasks. To configure properties on Direct Mailer, you use Commerce Server Manager.

When Direct Mailer is installed, it is automatically integrated with other Commerce Server features. However, you can use it as a stand-alone product without using other Commerce Server components. To use Direct Mailer as a stand-alone product, you use its command line interface.

This section contains:

  • Workflow for Direct Mailer. Illustrates the workflow of a Direct Mailer job.

  • About Direct Mailer. Provides the software requirements and dependencies for Direct Mailer. Describes the components of Direct Mailer, including a brief overview of the Direct Mailer pipeline, and opt-out lists and how they function.

  • Creating and Managing Direct Mail Lists. Describes how to use lists in the Business Desk List Manager, and how to create and process Direct Mailer lists.

  • Setting Up a Direct Mail Campaign. Describes the steps necessary to set up a direct mail campaign.

  • Developing Direct Mail Content. Describes how to construct personalized content for direct mail message bodies.

  • Configuring Direct Mailer. Explains how to modify the time frame in which Direct Mailer sends e-mail messages, as well as how to use multiple delivery locations.

  • Viewing Direct Mailer Job Status. Explains how to check the status of your Direct Mailer jobs.

  • Pausing, Stopping, and Deleting a Direct Mailer Job. Explains how to stop and delete a Direct Mailer job.

  • Restarting a Direct Mailer job. Explains how to restart a Direct Mailer job that stopped before it completed processing.

  • Running Direct Mailer in Stand-alone Mode. Explains how to run Direct Mailer as a stand-alone product.


Workflow for Direct Mailer

The following figure shows the workflow of a Direct Mailer job.

Direct Mailer workflow
Commerce Server
Business Desk
List Manager
Campaign Manager
Direct Mail
Campaign
Data Warehouse
User
SQL Server
Web Logs
Reports
IIS Event
Processor
Campaign Database
(Retail_Commerce)
CDO
Pipeline
DML Run
Direct Mail
NT Service
SQL Server Agent
SQL Server Direct Mail Database
Tracks all jobs
on the database
Direct Mail
User Interface
Stand-alone
Mode
Web Servers Personalized
Mail Pages


About Direct Mailer

Direct Mailer is a Windows 2000 service that is installed with Commerce Server as part of a complete installation, or optionally installed in a custom installation. There can be only one instance of Direct Mailer per server. However, you can have more than one Direct Mailer resource at the global resource level.

Direct Mailer performs the following tasks:

  • Manages Direct Mailer jobs.

  • Constructs personalized and non-personalized message bodies.

  • Formats e-mail message headers.

  • Sets the code-page value (language) and converts message bodies to the correct message type (MIME Encapsulation of Aggregate HTML Documents (MHTML), Multipurpose Internet Mail Extensions (MIME), or text).

  • Sends e-mail messages to recipients.

You can supply a list of recipients to Direct Mailer by using the List Manager module in Commerce Server Business Desk or, when running Direct Mailer in stand-alone mode from the command line, you can specify a list to use (by file name or SQL Server query). For any given list of recipients, Direct Mailer performs the same processing steps through the List Manager objects.

Direct Mailer can construct message bodies from either Web pages or static files. It can also be extended to construct messages using other sources, such as SQL Server templates, by adding custom components to the Direct Mailer pipeline. For more information about adding custom components to the Direct Mailer pipeline, see Using the Direct Mailer Pipeline.

Direct Mailer can send personalized e-mail messages from a Web page, or non-personalized mailings from a flat text file, to large groups of recipients.

Direct Mailer Requirements

Direct Mailer Databases

Direct Mailer Pipeline

Opt Out Lists

Direct Mailer Requirements

Direct Mailer has the following requirements:

  • Software Requirements and Dependencies

  • Mailing List Formats

  • Message Formats

  • Message Sources

Software Requirements and Dependencies

Direct Mailer uses SQL Server 7.0 or SQL Server 2000 as its database. It requires SQL Server Agent to be installed and running in order to start recurring mailings. Direct Mailer must be installed on the same computer as the Direct Mailer database. SQL Server must be running in order for Direct Mailer to start.

For more information about SQL Server, see SQL Server Books Online.

Microsoft Windows 2000 includes the following components, which Direct Mailer is dependent on:

  • Microsoft ActiveX Data Objects (ADO). ADO enables Direct Mailer to access and manipulate data in its database. To access data on one or more SQL Servers, it uses OLE DB Provider for Microsoft SQL Server.

  • Microsoft Windows Collaboration Data Objects (CDO). CDO provides a set of COM interfaces through which Direct Mailer operates. Direct Mailer primarily employs two major interfaces: IMessage and IConfiguration, which allow composing, formatting, and sending Simple Mail Transfer Protocol (SMTP) messages over the network, as well as local delivery.

Mailing List Formats

Direct Mailer supports the following mailing list sources:

  • Text file, such as a comma-separated value (.csv) file

  • SQL Server query

  • Analysis report

  • Segment list

A direct mail list contains one or more rows of recipients. Each row in the list contains a single recipient and is comprised of the following elements in comma-delimited format:

Parameter | Description
Email address | Required. Name or <name@domain>.
GUID | Optional. The unique user ID that will be used to provide content in a personalized mail message.
Message format | Optional. Controls the message format type that CDO translates the results into. For example, text, MHTML or MIME.
Language | Optional. The code-page value for the mail message.
URL | Optional. Provides the ability to pass individual URLs per user to CDO.

Note

  • If an optional parameter is omitted, you must supply the delimiter in order to line up the subsequent optional parameters.

Message Formats

Direct Mailer supports the following message formats:

  • Plain text

  • Multipurpose Internet Mail Extensions (MIME)

  • MIME Encapsulation of Aggregate HTML Documents (MHTML)

Message Sources

Direct Mailer can use a URL or a file path as a message source. If you use a file, you must verify that it resides in a directory that Direct Mailer can access.

For performance reasons, Direct Mailer pre-loads the file content into memory, limiting the file size in memory. The file can be any size, but only the first two million ASCII characters or one million Unicode characters are loaded into memory.

Direct Mailer Databases

Direct Mailer uses SQL Server 7.0 or SQL Server 2000 and SQL Server Agent extensively. The Direct Mailer database is created automatically in SQL Server when you install Commerce Server. You use SQL Server Agent, which runs continually, to view details about your Direct Mailer jobs. You can check status, the date and time the Direct Mailer jobs were last run, and the next scheduled run time.

Direct Mailer uses the following databases when it is run as an integrated component of Commerce Server:

  • Direct Mailer database. Contains the details and information associated with the Direct Mailer job.

  • Campaigns database. Contains the details and information associated with the direct mail campaign item.

The following figure shows Direct Mailer jobs and their details listed in SQL Server Agent.

Direct Mailer job status

Click the illustration to enlarge or reduce.

To start a Direct Mailer job in SQL Server Agent

  1. Expand the nodes to the following path: \Microsoft SQL Servers\SQL Server Group\<SQL Server Name>\Management\SQL Server Agent.

  2. Click Jobs. The Direct Mailer jobs appear in the right pane of the SQL Server Enterprise Manager.

  3. Right click the Direct Mailer job and select Start Job.

Note

  • To reschedule a Direct Mailer job, you use the Campaigns Manager module in Commerce Server Business Desk. For information about scheduling a Direct Mailer job, see Scheduling a Direct Mail Campaign.

See Also

Direct Mailer Pipeline

Direct Mailer Pipeline

The Direct Mailer pipeline is used to process lists of recipients. You can add new components to the pipeline, integrate the components with line-of-business systems, or replace them with components supplied by third parties.

The following table lists the stages of the Direct Mailer pipeline that are provided by Commerce Server. Each stage contains zero or more components.

Stage | Description
Throttle | Limits the speed in messages-per-hour at which Direct Mailer runs. This is useful to avoid flooding mail servers.
Preprocess Recipient | Verifies the data of the recipient.
Filter Recipient | Use as a model to further add/write custom components for this stage to extend the existing pipeline. For example, opting out a recipient.
Create Cookies | Creates the necessary cookies to impersonate a site user and get personalized content from the Web server.
Compose E-mail | Composes and formats the message body. The Collaboration Data Objects (CDO) for Microsoft Windows 2000 creates the e-mail message.
Send E-mail | Sends the previously created e-mail message.
Postprocess Recipient | Use as a model to further add/write custom components for this stage to extend the existing pipeline. For example, updating the Direct Mailer database to mark the messages that were sent, and writing the appropriate error codes if needed.

The following diagram shows the Direct Mailer pipeline and the components included in each pipeline stage.

Direct Mailer pipeline

Click the illustration to enlarge or reduce.

For more information about adding and removing components from the Direct Mailer pipeline, see Using the Direct Mailer Pipeline.

See Also

Direct Mailer Requirements

Direct Mailer Databases

Setting Up a Direct Mail Campaign

Using the Direct Mailer Pipeline

Opt Out Lists

Direct Mailer supports opting out or "filtering" a direct mail list against an opt-out list. For Direct Mailer jobs running as part of a campaign item, the platform supports the ability for the individual recipients to opt-out of a direct mail campaign item. This is done by using an opt-out Active Server Page (ASP) page, which is shipped as part of the Solution Sites.

The developer that authors the ASP page for the Direct Mailer jobs from the Web server can provide links to an Opt-out.asp page, which enables the recipient to either opt-out from the site or the direct mail campaign item by clicking the appropriate link. When a Direct Mailer job running as part of a campaign item is executed, Direct Mailer checks for the presence of the site level opt-out list and the campaign item level opt-out list. If either list exists, they are subtracted from the original direct mail list and the resulting list acts as the new direct mail list.

To support opt-out lists from the command line interface, you use the OptoutListType, OptoutListLocation, and the OptoutListSQL parameters in a job file compatible with the Windows.ini file format. For more information about opting out using the command line interface, see the Job Data Section.

See Also

Job Data Section


Creating and Managing Direct Mail Lists

You use List Manager to create and manage lists of direct mail recipients. There are two types of lists: generic lists and mailing lists. Generic lists are lists imported into List Manager from the Reports module, the Segment Viewer module, a SQL Server table, or an ASCII text file. List Manager automatically attempts to convert generic lists into mailing lists if they contain rows of e-mail addresses. Mailing lists are used by Direct Mailer to create and send pieces of mail to selected recipients in the list. If the generic list does not contain e-mail addresses, the list is imported as a user list if the format requirements are met. For more information about mailing list formats, see Mailing List Formats.

After the lists are imported into List Manager, you can use them to run Direct Mailer jobs to target your users more successfully. For example, you can run reports that show you the characteristics and past behavior of your users, and then create a direct mail campaign to target advertisements or products to those users.

You can also use List Manager to export lists to a file or SQL Server database, add or subtract lists, copy lists, extract lists, and delete lists.

Create a List of Recipients

Process a List of Recipients

Create a List of Recipients

To create a list of recipients for a direct mail campaign, you use the List Manager module in Campaigns. Lists are created in List Manager by importing lists created by other applications, such as Microsoft SQL Server (to create a SQL table), Notepad (to create an ASCII text file), Microsoft Excel (to create a spreadsheet) or Microsoft Outlook (to create .pst files that contain messages, appointments, contacts, and other Outlook items).

You can generate a list of recipients from analysis reports, Segment Viewer, or from an external database, and then import that list to the List Manager. For information about importing a list into List Manager, see Importing and Exporting Lists.

Process a List of Recipients

To process a list of recipients, Direct Mailer firsts loads the list of recipients from List Manager into a job table. It then iterates through the list of users, sending the data about the recipients through the Direct Mailer pipeline.

See Also

Direct Mailer Pipeline


Setting Up a Direct Mail Campaign

The Campaign Manager module provides an interface for creating direct mail campaigns. You can manage Direct Mailer jobs for each direct mail campaign through the Campaign Manager. You can create new direct mail campaigns, personalize messages, and modify properties. Attachments can be added to your direct mail campaigns, and you can schedule when the direct mail campaigns will run. You can also test your direct mail campaign using a test mailing list before sending it to production.

The following is an overview of the steps you perform to set up and run a direct mail campaign:

  1. Develop the message body to be delivered to the recipients. For example, if you are delivering personalized message bodies, develop a personalized Active Server Page (ASP) that will provide the message body to Direct Mailer.

  2. Identify and set up the data source that contains data about the recipients:
    • To generate a list of recipients from data in the Data Warehouse, use the Reports module in Commerce Server Business Desk. To view the static reports you want to use, select the reports, and then export the resulting list to the List Manager. For more information about importing and exporting lists in List Manager, see Importing and Exporting Lists.

    • To generate a list of recipients from a file, you will need the path of the file.

    • To generate a list of recipients from a SQL Server database, you will need the connection string and the SQL Server query string.
  3. Create and schedule the direct mail campaign. Use the Campaign Manager module to specify the following information:
    • Name of campaign and customer

    • Name of the list of recipients

    • Start time and date of the direct mail campaign

    • Uniform Resource Locator (URL) or static file where Direct Mailer should get the personalized message body

Note

  • The URL of the personalized message body must have a valid HTML content type extension, such as .htm or .asp. Invalid extensions such as .xml will result in a Collaboration Data Objects (CDO) error and the message will not be sent.

The direct mail campaign runs at the scheduled time. For information about testing your direct mail lists before sending them to production, see Testing a Direct Mail Campaign.

See Also

About Campaigns

Creating a Campaign

Adding a Direct Mail Campaign Item

Managing Lists of User Records


Developing Direct Mail Content

Direct Mailer can construct message bodies from either Web pages or static files. You can also extend Direct Mailer to construct messages using other sources, such as SQL Server templates, by adding custom components to the Direct Mailer pipeline. For more information about adding custom components to the Direct Mailer pipeline, see Using the Direct Mailer Pipeline.

For performance reasons, Direct Mailer pre-loads the file content for a static file into memory. The file size is limited to two million ASCII characters or one million Unicode characters. The remaining characters in the file are ignored and will not be sent in the message.

The only way to send individually personalized mail is by using a Web page. To deliver personalized message bodies, you must first develop the personalized Web page.

Note

  • If you specify a text attachment when sending a mailing in MIME Encapsulation or Aggregate HTML Documents (MHTML) format from Direct Mailer, the personalized Web page will show up as an attachment when viewed with Microsoft Outlook. This issue applies only with Outlook, not with Microsoft Outlook Express.


Configuring Direct Mailer

Before you run Direct Mailer, you may want to review and modify the properties for controlling the way your jobs are run. The following figure shows the properties for Direct Mailer, which operates at the global resource level.

Direct Mailer properties

Click the illustration to enlarge or reduce.

To modify the properties of Direct Mailer

  1. Expand Commerce Server Manager, open the Commerce Group you want to administer, and then click Global Resources.

  2. Right click Direct Mailer, and then select Properties.

  3. In the Properties dialog box, do the following:
Use this (Properties) | To do this (Selected Property Value)
Delivery Locations | Type the delivery location. There must be at least one entry specified. Drop directories are listed for local delivery, and the SMTP server address is listed for remote delivery.
Delivery Method | Type the value that determines whether the mailings are to be delivered. 1 - Remotely 2 - Locally to a drop directory
Log Folder Path | Type the location of the Direct Mailer operational log file.
Maximum Error Percentage | Type the maximum percentage of non-fatal errors per job.
Maximum Thread Count | Type the maximum number of threads per job.
Messages Per Hour | Type the number of messages per hour that this server can produce. If set to zero (0), Direct Mailer processes messages as fast as possible.
Performance Update Interval | Type the performance update interval in seconds.
Pipeline Configuration File | Type the location of the pipeline configuration file, DMLPipe.pcf.
Proxy Bypass | Type the local computers where a proxy check is not required, or a value that represents all local computers.
Proxy Server | Type the name of the proxy server to use.
Connection Strings | Type the connection string to the Direct Mailer SQL Server database.

Note

  • The Log Directory, Messages Per Hour, Proxy Bypass, Proxy Server, and Connection String properties are based on a per service instance. This means that any changes made to the values for these properties require Direct Mailer to be restarted. The remaining Direct Mailer properties are based on a per job instance and do not require Direct Mailer to be restarted.

Restarting Direct Mailer

You can restart Direct Mailer from either the command line interface or through the administration tools.

To restart Direct Mailer from the command line interface

  1. At the command line, type net stop dmlservice.

  2. When the service has stopped, type net start dmlservice.

To restart Direct Mailer using Services

  1. Open Services from the Start menu. Click Start, point to Programs, point to Administration Tools, and then click Services.

  2. In the Services screen, in the right pane, right-click Commerce Server Direct Mailer, and then select Restart.

See Also

Modifying Direct Mailer Speed

Using Multiple Delivery Locations


Modifying Direct Mailer Speed

Direct Mailer is designed so that you can limit the number of messages per hour it processes so the job does not overload the production Mail server. To do this, you modify the Messages Per Hour property, which determines how many messages the Direct Mailer processes in an hour. If the Messages Per Hour property is set to zero (0), Direct Mailer processes the messages as fast as possible.

To modify Direct Mailer speed

  1. Expand Commerce Server Manager, expand Global Resources, right-click Direct Mail on <SQL Server Name>, and then click Properties.

  2. In the Properties dialog box, select Messages Per Hour, and in the Selected Property Value box, type the number of messages per hour that you want Direct Mailer to send.

    If you set Selected Property Value to zero (0), Direct Mailer processes messages as fast as possible.

  3. Click OK.

  4. Restart Direct Mailer. For information about restarting Direct Mailer, see Restarting Direct Mailer.

The new setting is applied immediately to all Direct Mailer jobs.

Besides the Messages Per Hour property, there are other factors that determine how fast Direct Mailer processes messages. For example:

  • Direct Mailer performance is dependent on the Collaboration Data Objects (CDO) for Microsoft Windows 2000.

  • Direct Mailer calculates the delay value for each pipeline cycle, based on overall performance and throttling settings.

  • Direct Mailer performance is closely related to Simple Mail Transfer Protocol (SMTP) server performance and throttling requirements.


Using Multiple Delivery Locations

When Direct Mailer is configured to use multiple delivery locations, whether they are drop directories or Simple Mail Transfer Protocol (SMTP) servers, it uses the same list for every job running. Direct Mailer reads the list of locations from the Global Configuration Dictionary, which contains global configuration parameters shared over all the jobs running on all the sites. Direct Mailer does not sort the Global Configuration Dictionary or check it for duplicate entries.

If the Delivery Method property is set to local (2), Direct Mailer treats each entry in the list as a fully qualified path to the SMTP server pickup directory. If the Delivery Method property is set to remote (1), Direct Mailer expects each entry in the list to use the following format:

<SMTP server address>[: port]

Specifying the port is optional, but if it is not specified, Direct Mailer uses port 25.

When a Direct Mailer job is started, the first recipient in the direct mail list uses the first delivery location. The next recipient uses the subsequent delivery location. This delivery process is repeated until there are no new delivery locations. In this case, the delivery locations are recycled back to the first delivery location.

If a failure occurs in mailing, Direct Mailer does not re-try another location, nor does it perform timeout or availability checking. Therefore, any given recipient can only use the delivery location that is assigned them.

To use multiple delivery locations

  1. Expand Commerce Server Manager, expand Global Resources, right-click Direct Mailer, and then click Properties.

  2. In the Properties dialog box, select Delivery Locations, and in the Selected Property Value box, type the fully qualified path to the drop directory or SMTP Server. Universal naming convention (UNC) paths are not supported.

For multiple delivery locations, separate each location with either a comma or semicolon. The comma and semicolon are the only supported delimiters used to separate different paths.

  3. Select Delivery Method, and in the Select Property Value box, type 2 to use local delivery, or 1 to use remote delivery.

  4. Click OK.

The new setting is applied immediately to all Direct Mailer jobs.


Viewing Direct Mailer Job Status

You can check the status of your Direct Mailer jobs to determine if a job is currently running, has been suspended or terminated, or has completed successfully. You can view the status of your Direct Mailer jobs using the command line interface.

To view the status of Direct Mailer jobs using the command line interface

  • At the command line, type DmlRun /list to view all Direct Mailer jobs.

The list of Direct Mailer jobs is displayed.

The following information is displayed for each Direct Mailer job:

  • Job identification number

  • Job status

  • Job description

  • Site name

  • Campaign item identification number

  • Campaign item name

Note

  • Site name, campaign item identification number, and campaign item name are only displayed if they exist for the Direct Mailer job.

The following table lists job status codes.

Code | Description
0 | The job was created but not initialized.
1 | The job was completely defined but not running (Inactive) or the job was terminated.
2 | The job completed.
3 | The job is running (Active).
4 | The job is running but currently suspended (paused, but still Active).
-2 | The job was stopped by Direct Mailer due to serious problems or because the error threshold limit was reached.
-3 | The job was defined as css_site, but not all the data was available at the run time.


Pausing, Stopping, and Deleting a Direct Mailer Job

You can pause a Direct Mailer job at any time. If you pause a Direct Mailer job, Direct Mailer stops processing the list of recipients, but you can restart it at a later time. Direct Mailer records which recipient it will process next, so that if the job is paused (for example, by shutting down the computer, or if a hard drive crashes) it can start approximately where it left off, once it is restarted. The recipients that were processed in the last one to one and a half seconds before the power shutdown may not receive their e-mail.

You can stop (terminate) a Direct Mailer job while it is running. Once a Direct Mailer job has been stopped you cannot continue from where it left off when it was stopped. You must restart the Direct Mailer job, and it will process from the beginning of the list of recipients.

You can delete a Direct Mailer job if the job has been stopped, completed, or if the job failed. You cannot delete a Direct Mailer job while it is running. If you delete a Direct Mailer job, all information about the job is deleted from Direct Mailer. You must recreate the job if you want to run it again.

Note

  • Pausing, stopping, and deleting a Direct Mailer job can only be done using the command line interface. You cannot use the Business Desk Campaign Manager module to pause, stop, or delete a Direct Mailer job.

To pause a Direct Mailer job from the command line interface

  1. At the command line, type DmlRun /list to display a list of all Direct Mailer jobs.

  2. Note the jobID number of the Direct Mailer job you want to pause, and then type:

    DmlRun /pause:<jobID number>

    The Direct Mailer job is paused.

To stop a Direct Mailer job from the command line interface

  1. At the command line, type DmlRun /list to display a list of all Direct Mailer jobs.

  2. Note the jobID number of the Direct Mailer job you want to stop, and then type:

    DmlRun /term:<jobID number>

    The Direct Mailer job is stopped.

To delete a Direct Mailer job from the command line interface

  1. At the command line, type DmlRun /list to display a list of all Direct Mailer jobs.

  2. Note the jobID number of the Direct Mailer job you want to delete, and then type:

    DmlRun /delete:<jobID number>

The Direct Mailer job is deleted.

See Also

Deleting and Restoring a Campaign Item

Managing and Controlling Direct Mailer jobs from the Command Line

Restarting a Direct Mailer job


Restarting a Direct Mailer Job

If a Direct Mailer job stops before it completes processing, Direct Mailer updates the job status, indicating that the job has stopped and did not complete successfully. You use the DmlRun /list command from the command line interface to view the Direct Mailer job. To automatically return the job status on the console, you use the /wait option. For information about viewing Direct Mailer job status, see Viewing Direct Mailer Job Status.

If a Direct Mailer computer stops, (for example, if the hard drive crashes) all Direct Mailer jobs that are running on that computer stop. If a Direct Mailer job stops before it completes processing, you must manually restart the jobs that were stopped.

To restart a Direct Mailer job

  1. At the command line, type DmlRun /list to display a list of all Direct Mailer jobs.

  2. Note the jobID number of the Direct Mailer job you want to restart, and then type:

    DmlRun /run:<jobID number>

The Direct Mailer job is restarted.

See Also

Managing and Controlling Direct Mailer Jobs from the Command Line


Running Direct Mailer in Stand-alone Mode

The stand-alone mode of Direct Mailer facilitates it as a platform component that can be easily integrated with line-of-business systems. For example, advertisers prefer that Commerce Server analysis reports be mailed to them. This use ignores any communication from the application to the Direct Mailer. For example, Direct Mailer can mail a file containing an Ad Placement report to a list of advertisers. The job information in this case comes from command line parameters and a configuration file.

To run Direct Mailer from the command line interface you use the executable file, DmlRun, together with command line options. You can use these options to perform several tasks, such as to create, run, monitor, and delete Direct Mailer jobs.

Note

  • To schedule direct mail campaigns, you either use the Campaign Manager module in Business Desk or use the Windows Task Scheduler manually. The Windows Task Scheduler can run a batch file that uses the command line interface.

The following is an overview of the steps required to set up and run Direct Mailer in stand-alone mode:

  1. Develop the content to be delivered to the recipients. If necessary, develop the Web page or static file that will provide the personalized message body.

  2. Identify the data source for the list of recipients.

  3. Create the Direct Mailer job file.

  4. Create the Direct Mailer job by using the /create option from the command line interface.

  5. Run the stand-alone job from the command line.


Creating a Direct Mailer Job File

Before you create a stand-alone Direct Mailer job, you need to create a Direct Mailer job file that specifies information about the job, such as whether it delivers personalized message bodies, the format of mail message headers, and the location of the list of recipients.

You can create a job file using any text editor. The job file must be a text file that is compatible with Microsoft Windows .ini file format.

Add the following sections to your job file:

  • Job Data Section. Specify key parameters about the job, such as the data source for the content, list of recipients, message format type, subject, and opt-out list.

  • Job Attachments Section. This section is optional. Specify the number and the source of the attachments.

After Direct Mailer runs, it writes a Results section in the job file. The parameters in the Results section are Job ID, ErrorCode, and ErrorString. If a job is successful, JobID and an ErrorCode=0 are written. If a job was unsuccessful, the JobID, the ErrorCode number, and the ErrorString are written.

Job Data Section

The following table lists the parameters that you can define for job data in the job file.

Parameter | Type | Description
JobDesc | string (128 max) | Optional. Specify a description of the job.
TemplateURL | string (2084 max) | Optional. Specify the mail template source in Uniform Resource Locator (URL) form, either http:// or file://. If you are using a flat file as the template, type a full server-centric local path name. Universal naming convention (UNC) path names are supported.
MailFrom | string (256 max) | Required. Specify the From field of the e-mail.
MailSubject | string (256 max) | Optional. Specify the Subject field of the e-mail address.
MailReplyTo | string (256 max) | Optional. Specify the e-mail address that will receive responses.
DefaultFmt integer Optional. Specify the default message format for the content to be mailed.

1 = Plain text
2 = MIME Encapsulation of Aggregate HTML Documents (MIME)
3 = MIME Encapsulation of Aggregate HTML Documents (MHTML)
JobLocale | string (255 max) | Optional. Specify the default locale for the job.
MailPersonalize integer Optional. Specify 1 if you are delivering personalized content, and 0 if you are not delivering any personalized content.

Note

  • Any non-integer (any character value(s)) will have the same effect as entering "MailPersonalize=0".

  • Any non-zero integer will have the same effect as entering "MailPersonalize=1".
MailingListType integer Required. Specify the mailing list type.

1 = Flat file
2 = List Manager list
3 = SQL Server query
MailingListLocation string (256 max) Required. Specify the location of the mailing list.

For flat files, specify the full, local, server-centric path name. Do not include any schema prefixes, such as file://.

For SQL Server queries, specify the connection string.

For List Manager lists, specify the list identification number.

UNC path names are supported.
MailingListSQL | string (256 max) | Specify the SQL statement to mail from. A value is required if the MailingListType = 3, otherwise, it is ignored.
OptoutListType integer Optional. Specify the opt-out list type.

1 = Flat file
2 = List Manager list
3 = SQL Server query
OptoutListLocation string (256 max) Optional. Only required if OptoutListType is used. Specify the location of the opt-out list.

For flat files, specify the full, local, server-centric pathname. Do not include any schema prefixes, such as file://.

For SQL Server queries, specifies the connection string.

For List Manager lists, specifies the list identification number.

UNC path names are supported.
OptoutListSQL | string (256 max) | Specify the SQL statement to opt-out from. A value is required if the OptoutListType = 3, otherwise, it is ignored.
UserFlags | integer | Optional. Specifies any user-defined flags associated with the job.

Job Attachments Section

The following table lists parameters you can define for job attachments. This section of the job file is optional.

Parameter | Type | Description
AttachmentCount | integer | Specify the number of attachments (greater than 0).
Attachment_<N> | string (2084 max) | Specify the attachment URL or file system path for the <N> attachment, where N is a number between 1 and AttachmentCount. Verify that the URL includes a schema prefix, such as http:// or file://. For file attachments, include the full, server-centric path name. UNC path names are supported.

Results Section

After Direct Mailer runs, it writes a Results section to the job file. The following table lists the parameters that Direct Mailer writes to the Results section.

Parameters | Type | Description
ErrorCode | HRESULT | 0 = Operation (create, start, delete, and so forth) ran successfully. If unsuccessful, the error code is written.
ErrorString | string (256 max) | If ErrorCode indicates the job did not complete successfully, this parameter will include descriptive text explaining the error. Otherwise, this field is blank.
JobID | GUID | This parameter specifies the new job ID that can be used for starting, stopping, or handling this job.

See Also

Opt Out Lists


Creating and Running a Direct Mailer Job

After you have created a job file, you can set up a stand-alone Direct Mailer job. To create the job, you use the /create option from the command line interface.

To create a stand-alone Direct Mailer job

  1. At the command line, type:

    DmlRun /create:filename=<job file name>

    Type a full path name for the job file. Direct Mailer looks for the job file in the current directory if no directory is specified.

    If the parameters of the job data file are incorrect, Direct Mailer writes an error code and a description of the error to the Results section of the job file.

    The Direct Mailer job is created.

  2. To get the jobID number, type:

    DmlRun /list

  3. To run the job, type:

    DmlRun /run:<jobID number>

    The Direct Mailer job is started.

  4. To create and start a job, type:

    DmlRun /create:filename=<job file name> /execute

    The Direct Mailer job is created and started.

See Also

Creating a Direct Mailer Job File

Managing and Controlling Direct Mailer Jobs from the Command Line


Managing and Controlling Direct Mailer Jobs from the Command Line

You can manage a Direct Mailer job from the command line interface by using the Win32 console application DmlRun. Direct Mailer includes a set of command line options that you use with DmlRun. These options enable you to create, run, monitor, and delete Direct Mailer jobs.

For example, to list all your Direct Mailer jobs and review the jobID numbers, you type DmlRun /list. To stop a specific job that Direct Mailer is processing, for example 1456, you type DmlRun /term:1456.

The following table lists the options you can use with DmlRun.

Option | Description
/run:<jobID number> | Starts a job, or continues a job that was paused.
/term:<jobID number> | Stops a job that is running.
/pause:<jobID number> | Suspends the job but does not stop it; all the resources remain allocated. Use this option when you want to balance Simple Mail Transfer Protocol (SMTP) server load.
/create:<param-string> | Creates a new Direct Mailer job based on the data in your job file. After the job is created, use the /run option to run it.
/delete:<jobID number> | Deletes a Direct Mailer job.
/list | Lists all Direct Mailer jobs.
/list:[css_site=xxxx;] [filename=yyy;] Enumerates all the jobs for the given Commerce Server site (if specified) or for all sites (if the css_site keyword is omitted). If the "filename" is specified, the output is directed to the specified file. If no directory is specified, the file name is created in the WINNT directory.

To see an example of the job list file format, see Using the /list Option.
/del_old:age | Deletes completed jobs older than "age" days.
/wait Optional. You can use this option with the /run, /term, /create, and /execute options. When combined with the /run option, DmlRun waits until the job is finished before it returns the job status back to the console. You can also combine the /wait option with the /create /execute options to cause the same effect.

When you use the /term /wait options, DmlRun waits until the job actually terminates.

Notes

  • The /wait option must be combined with another option; it cannot be used alone.

  • Using the /wait /term options will return an error statement such as the following: "Error: The job {7f2c6324-6b72-402d-853d-8b1c654ae842} exited with status code 1".
/execute Optional. When you use the /create /execute options, DmlRun creates and runs the job.

You must always include the /create option on a line in which you use the /execute option.

/server:<server name> | Optional. You can use this option with any other option. It forces DmlRun to manage the job remotely on the specified server.
/? or /help or /h | Provides help for the command line options and usage. You cannot use this option with any other option.

The following options cannot appear on the same command line together:

  • /create

  • /delete

  • /del_old

  • /list

  • /pause

  • /run

  • /term

Using the /list Option

The job list file can be produced by the DmlRun /list:<filename> command. It is a text file in .ini-compatible format. Each job occupies its own section, "Job #" where "#" is a sequential number (from 1 to the total number of jobs). The following is an example extract from the file:

[General]
JobCount=2

[Job 1]
JobID number=<job_id for the job>
Description=<Descriptive text for the job>
Status=<Integer; status code for the job>
LastRunTime=<Date/Time when the job ran last time. Blank if job did not run.>
FinishedTime=<Date/Time when the job was completed. Blank if job did not finish.>
CampaignItem=<Campaign item ID. Appears only if part of a campaign.>
DMLItem=<Direct Mailer item ID. Appears only if part of a campaign.>
CommerceSite=<css_site ID. Blank if not part of a site.>

[Job 2]

See Also

Creating a Direct Mailer Job File

Creating and Running a Direct Mailer Job


Running the Predictor Resource

You use the Commerce Server Predictor resource to add predictive capabilities to your Web site, such as predicting which products users may purchase based on products similar users — those sharing the same characteristics — have purchased previously. You use Commerce Server Manager to set up and manage the Predictor resource.

This section contains:

  • Predictor Resource Workflow. Illustrates the workflow for building and managing models.

  • About the Predictor Resource. Describes the predictive capabilities supported by the Predictor resource. Describes the Predictor resource components.

  • Deploying the Predictor Resource. Describes how and why to deploy the Predictor resource for optimal use.

  • Configuring Predictor Resource Properties. Explains how to configure the Predictor resource for use with databases other than the Commerce Server Data Warehouse.

  • Starting and Stopping the Predictor Resource. Explains how to start and stop the Predictor resource.

  • Building a New Analysis Model. Explains how to build a new analysis model based on a model configuration.

  • Deploying an Analysis Model. Explains how to deploy an analysis model.

  • Viewing Analysis Model Configuration Tables. Explains how to view analysis model configuration tables.

  • Viewing Analysis Models. Explains how to view the analysis models you created. To view the analysis models, you use either the Prediction Model Viewer in Commerce Server Manager or the Segment Viewer in Commerce Server Business Desk.

  • Using Dependency Network View. Explains how to use the Prediction Model Viewer to view the dependency network.

  • Using Decision Tree View. Explains how to use the Prediction Model Viewer to view the decision tree.

  • Rebuilding an Analysis Model. Explains how to rebuild an analysis model.

  • Renaming an Analysis Model. Explains how to rename an analysis model.

  • Deleting an Analysis Model. Explains how to delete an analysis model.

  • Monitoring the Predictor Resource. Explains how to monitor the Predictor resource for processing errors.


Predictor Resource Workflow

The following figure illustrates the workflow for building, viewing, analyzing, and deploying analysis models.

Predictor Resource workflow diagram
Transactions
New configuration model
(created by the site developer)
Prediction model
Segment model
Select an analysis model:
Select a configuration model:
Deploy Model onto Web
servers using
PredictorClient API calls
View and analyze the
Segment model using the Segment Viewer
(in Business Desk)
View and analyze the
Prediction model using the Prediction Model Viewer
(in Commerce Server Manager)
Build the analysis model
Import data
into the
Data Warehouse

  1. Import data into the Commerce Server Data Warehouse.

  2. Select a configuration model from the Build Model dialog box.

    Or create a new model configuration.

  3. Select an analysis model type from the Build Model dialog box.

  4. Build the analysis model.

  5. View and analyze a Prediction model in the Prediction Model Viewer.

  6. View and analyze a Segment model using the Segment Viewer in Business Desk.

  7. Deploy the analysis model onto your Web servers using PredictorClient API calls.

Note

  • Prediction models provide more accurate recommendations than Segment models. Use Prediction models to provide recommendations on your site.


About the Predictor Resource

The Predictor resource is a Microsoft Windows 2000 service that is optionally installed with Commerce Server 2000 as part of a complete or a custom installation. The Predictor resource enables you to provide predictive capabilities for your Web site. You use the Predictor resource to build complex analysis models by specifying the table columns or attributes that you want to predict. For example, you can use the Predictor resource to determine the type of content, ads, and cross-sells that might interest your users. After the Predictor resource builds the analysis models, you can add the Predictor Client Object to your Active Server Pages (ASP) pages, which adds intelligent cross-sell, product recommendations, and property prediction to your site.

Multiple instances of the Predictor resource are supported per Commerce site, but only one instance is supported per computer. You can install the Predictor resource on each computer that contains your Commerce Server Data Warehouse, or you can install the Predictor resource on dedicated computers to preserve system memory. Running the Predictor resource on a separate computer uses more network bandwidth than running the Predictor resource and the Data Warehouse on the same computer. The Predictor resource requires that you use Microsoft SQL Server as your database.

Building analysis models is memory intensive. You can prevent a resource hit on the Web servers by building the model once and then copying it to each of your Web servers (using the IPredictorClient::LoadModelFromDB method with the Predictor Client Object). Each Web server can host multiple analysis models (for different predictive functionality).

After you build an analysis model, you can view it. You can view a Prediction model with the Prediction Model Viewer in Commerce Server Manager, and a Segment model in the Segment Viewer module in Commerce Server Business Desk.

Note

  • There can be only one instance of the Predictor resource per computer.

The Predictor resource contains analysis models and analysis model configurations. The Predictor resource provides the Prediction Model Viewer to analyze and view your analysis models.

This section contains:

  • Analysis Models

  • Analysis Model Configurations

  • Prediction Model Viewer

  • Predictor Best Practices

  • Analysis Model Effectiveness


Analysis Models

An analysis model is a set of statistical relationships based on observations of past site users and/or their purchase history, click history, or other behavior. The model contains information about the types of users who visit your site, but it does not contain information about specific users. The detailed information used to create an analysis model is stored in the Commerce Server Data Warehouse.

All models are stored as binary data in the Data column of the PredictorModels table in the Data Warehouse database.

A site can run several different analysis models, and each model can be based on data from a different database. Sites can share analysis models because the models are not site-specific. Commerce Server 2000 does not limit the number of models you can use for each site or server.

Prediction Models and Segment Models

Cases

Dense Table

Sparse Table

Prediction Models and Segment Models

You can build two types of analysis models: Prediction models and Segment models. You view Prediction models with the Prediction Model Viewer in Commerce Server Manager and Segment models in the Segment Viewer module in Commerce Server Business Desk.

A Prediction model consists of a set of decision trees and a summary network called a dependency network. A dependency network summarizes the dependencies (predictive relationships) described by the decision trees. Prediction models provide more accurate predictions than do segmentation or memory-based algorithms. You use the Prediction Model Viewer to view both the dependency network and the individual decision trees.

A Segment model partitions groups of users into segments based on similar user properties. Similar segments are grouped into collections of segments, creating a segment hierarchy. You use the Segment Viewer module in Business Desk to view Segment models.

Before you build an analysis model, you must ensure that the data you want to build the model with is available in the Data Warehouse. In addition, if you do not want to use the default Transactions model configuration, you will need to create your own configuration.

You construct analysis models from cases, which you construct from the data in the Data Warehouse. Data must be imported into the Data Warehouse before you can use the data to build cases. For information about importing data into the Data Warehouse, see Importing Data into the Data Warehouse.

Cases

A case is the set of all information known about a specific site user and consists of attribute/value pairs. This information may include user profile data, purchase history, click history, or a combination of these. A typical analysis model uses between 10,000 and 50,000 cases with a resulting size of between 10 kilobytes (KB) and 100 KB. The number of cases in a given model configuration affects the accuracy of the analysis models using that configuration. In general, predictions are more accurate when many cases are available for a model. However, after a certain point (often 50,000 cases or less), there is little increase in accuracy when additional cases are used. In contrast, the time necessary to build an analysis model increases with the number of cases in the configuration.

You build cases from the data stored in the Data Warehouse database. Only certain types of data tables in the Data Warehouse database will provide useful information for your Web business. For example, to predict which products specific users are likely to purchase, you will likely want to use data tables or views (virtual tables that represent the data in one or more tables in an alternative way) containing information about your users, such as user profiles, purchase history, and/or click history.

The two most common types of data used to build a model configuration are user profile data, which is stored in dense tables, and transaction history logs, which are stored in sparse tables. You can use the Transactions model configuration provided by default to analyze transactions in a sparse table, or you can create your own model configuration. For example, you can create a configuration that analyzes a single dense table with demographic information, or you can create a configuration that analyzes both a dense table and one or more sparse tables containing transactions.

Note

  • If both one dense and one or more sparse tables are used, only data corresponding to users listed in the dense table will be processed. If you want to use sparse data for users without corresponding information in the dense table, you must create records in the dense table for these users with all unknown values set to NULL. For information about the procedure for setting up your own configuration, see Predictor Schema.

Dense Table

In a dense table (or view), the attributes of a case are represented as column values in a single row. Demographic customer data (possibly consisting of Age, Gender, and Salary) typically is represented best in a dense table. In this type of dense table, there is exactly one row for each user and exactly one column for each attribute.

A common source of data for a dense table is profile information submitted by users when they complete a registration form. For information about creating profile definitions to collect user data on your Web site, see Running the Profiles Resource.

The following figure shows the layout of a typical dense table.

Click the illustration to enlarge or reduce.

Sparse Table

In a sparse table (or view), a case is represented as multiple rows, with each row representing an attribute/value pair. For example, product purchase data may have the schema: (CustomerID, ProductID, Quantity). In this type of sparse table, there is one row for each product purchased by the user. In general, a sparse table contains one row for each transaction, such as one row for each item ordered or each page visited. This table may have several rows for each user who visits your site, because one user may have ordered several items or visited several pages. All of the rows associated with a single user comprise one case. The case identifier is typically some user ID, such as a unique user or login name. The property is the item you want to predict, and the value is the quantity of that property.

Because the data needed for a sparse data table may be stored in two or more tables in your data source, you may need to use SQL Server Enterprise Manager to create a view that contains the columns required by your analysis model configuration. For example, to predict a purchase that is based on other products purchased, you need the user ID, product SKU, and quantity purchased columns. These columns may be located in two or three different linked tables (such as Customers, Orders, and Order Details, or Requisition and POLineItems) depending on the structure of your database.

The following figure shows the layout of a typical sparse table.

Click the illustration to enlarge or reduce.

For information about building dense and sparse tables and creating analysis model configurations, see Predictor Schema.


Analysis Model Configurations

An analysis model configuration contains information used to build Prediction and Segment models. The Predictor resource uses analysis model configurations to map data from the Commerce Server Data Warehouse database to cases. A case is the set of information known about a specific user and consists of a set of attribute/value pairs. Cases are used to build analysis models, which in turn, are used by the Predictor Client Object to make predictions about the future behavior of users.

An analysis model configuration specifies:

  • A collection of tables and/or views in the Data Warehouse that contains the data to be modeled.

  • Attributes for the model. An attribute is a useful distinction about a user — for example, the age of a user, whether a user has purchased a particular product, or whether a user has clicked on a particular ad.

Commerce Server 2000 provides a Transactions model configuration you can use to build Prediction and Segment models to analyze transaction data from the Data Warehouse. If you want to build Prediction and Segment models based on other types of data, you must create new model configurations with the Predictor schema. For information about how to build a new analysis model configuration, see Predictor Schema.

You can build your own analysis model configuration manually for any of the following reasons:

  • The field names in your tables (or views) differ from those in the built-in tables.

  • You do not use the built-in data tables included with Commerce Server.

  • The model configurations provided do not meet your business needs.

The Transactions model configuration provided by Commerce Server is maintained in the Data Warehouse database in three main tables and in an optional fourth table:

  • PredictorModelCfgs. Lists the existing model configuration. This model configuration is included under Model Configurations in Commerce Server Manager.

  • PredictorDataTables. Lists and describes the tables containing the data to be modeled.

  • PredictorModels. Stores the actual analysis models and the parameters that were used to build them.

  • PredictorAttributes <configuration name>. Indicates which properties are to be used to build the model or which properties you want to be predicted. This table is optional and can be used to override the automatic assignment of attribute distributions.

For information about viewing the model configuration tables using Microsoft SQL Server, see Viewing Analysis Model Configuration Tables.


Prediction Model Viewer

You use the Prediction Model Viewer to view your Prediction models. The Prediction Model Viewer provides two views for analyzing your Prediction models: the Dependency Network view and Decision Tree view.

Dependency Network View

Decision Tree View

Dependency Network View

You use Dependency Network view to analyze the statistical dependencies of the attributes in your analysis model. Dependency Network view is the view that first appears when you open a Prediction model in the Prediction Model Viewer. Dependency Network view is a graph of your Prediction model that is represented with nodes and arcs. Nodes correspond to attributes and arcs correspond to statistical dependencies among the attributes.

Prediction Model Viewer

Click the illustration to enlarge or reduce.

The nodes appear as an oval with text. ToolTips appear with the full name of the attribute if you pause on a node. When no nodes are selected, all nodes appear green in color.

When you open a Prediction model in Dependency Network view, the nodes are automatically displayed in a manner that is easy to visualize. The nodes continuously move as Commerce Server improves the layout. You can stop and restart the improvement process. You can click a node to highlight the direct relationships between that node and the other nodes in the graph. You can drag nodes to manually adjust the layout. For information about working with the layout arrangement of your model, see Arranging the Layout in Dependency Network View. Node colors indicate the following:

  • Green. The node is selected.

  • Red. The selected node helps to predict this node.

  • Blue. This node helps to predict the selected node.

  • Purple. A predictive relationship exists in both directions.

The slider along the left side of Dependency Network view enables you to control the number of relationships exposed based on the strength of the relationship. As the slider is moved down, arcs are removed — that is, the arcs corresponding to the weakest dependencies are removed until only the arcs for the strongest dependences are shown.

You use the slider to help you view a Prediction model with dozens of characteristics and hundreds of relationships because it helps you to focus on the dependencies you are most interested in.

Decision Tree View

You can use the Predictor resource Decision Tree view to analyze the tree components of your Prediction model. You access Decision Tree view by double-clicking a node in Dependency Network view. A decision tree is graphical shorthand for a set of probabilistic rules of the form:

IF X = Value and Y = Value and so on, THEN Target = Value with probability p

The conditions in the "IF" clause of a particular rule correspond to a left-to-right traversal of the tree. In particular, each internal node is annotated with the name of an attribute, and the out-going edges are annotated with value(s) for that attribute.

Nodes are oval in shape and purple in color. Leaf nodes, which show the prediction probabilities, are gray rectangular boxes.

Decision Tree view

Click the illustration to enlarge or reduce.

Each leaf node stores a probability distribution for the target attribute. (A probability distribution is a set of probabilities, one for each possible value of the target.) If the target attribute is categorical and has less than eight values, the probability for each value is depicted in the leaf node as a histogram. When a categorical attribute is binary (that is, the attribute simply indicates the presence or absence of a value), then only the probability of the attribute being present is shown as the fraction of the bar that is green (see the previous figure). For a categorical attribute with more than eight values, each leaf node is annotated with the most likely value for the target. If the target attribute is continuous, each leaf node is annotated with the expected range of the target.

You can also double-click an internal node to more easily read the path to that node.

You can continue navigating through the tree without closing the dialog box. The dialog box displays the path for the currently selected node.

Note that there is a useful correspondence between the contents of the decision trees and that of the dependency network. Namely, there will be an arc from attribute A to attribute B in the dependency network if, and only if, attribute A is a node in the decision tree for attribute B. (Both views are saying the same thing: knowing attribute A helps to predict attribute B.)

See Also

Using Dependency Network View


Predictor Best Practices

You can improve the performance of the Predictor resource in the following ways:

  • Control the sample size used to build an analysis model

  • Control how many attributes are to be included in an analysis model

  • Build your model on the same computer that contains your Data Warehouse

You can control the relative accuracy of an analysis model and the time it takes to build it, by varying the sample size. The larger the sample, the more accurate the analysis model and the longer it takes to build the model. However, the accuracy of analysis models larger than 30,000 to 50,000 cases does not significantly improve. You control the number of cases used to build an analysis model by modifying Number of Cases in the Model Build Properties dialog box. You can also pre-sample your data using a view or table and build the model from that sample. With this method, you should be careful to sample the cases at random, instead of choosing them sequentially.

You can control the fractions of attributes used for inputs to predict the accuracy of an analysis model and the time it takes to build the model. The higher the fraction, the more accurate the model, but the longer it takes to build the model. To control the number of attributes that are included in an analysis model, modify Input Attribute Fraction and Output Attribute Fraction in the Model Build Properties dialog box. A value of 1.0 indicates that the Predictor resource is to use all of the attributes available to build the model. If the database contains many attributes, (for example, a product catalog with tens or hundreds of thousands of products) it is best to use a lower number. Unless you have a reason to do otherwise, it is probably best to use equal input and output fractions.

When you try to improve the results of your Prediction model, consider the data sizes and limits, and the performance criteria for the Predictor resource.

It is also recommended that you build your analysis models on the same computer that contains your Commerce Server Data Warehouse.

Data Sizes and Limits

Performance Criteria

Data Sizes and Limits

The following table shows the average and maximum data sizes for the Predictor resource.

Parameter | Average value | Maximum value
Number of products in product catalog | 50,000 | 500,000
Number of cases to build model | 30,000 | No limit other than the amount of available memory.
Number of transactions per user | 20 | Total number of attributes
Size of computed model | 100 KB | Limited by your database limitations
Maximum number of attributes predicted per call | 10 | Total number of attributes

Performance Criteria

The following table shows the performance criteria for the Predictor resource. The criteria are based on the average numbers defined in Data Sizes and Limits.

All numbers are measured on a 400 MHz Pentium II with 512 MB of RAM for the service. Client computers are 400 MHz Pentium II with 128 MB of RAM.

Criteria | Component | Minimum | Maximum | Average
Latency to make prediction | Client | 0 milliseconds | 200 milliseconds per prediction call | 100 milliseconds per prediction call
Throughput of prediction requests | Client | 30 predictions per second per CPU | Not applicable | 50 predictions per second per CPU
New model build time | Service | Not applicable | 8 hours | 1.5 hours
Load model from database | Client | Not applicable | 30 seconds | 10 seconds
Service start time | Service | Not applicable | 45 seconds | 10 seconds

See Also

Analysis Model Effectiveness


Analysis Model Effectiveness

You can test the effectiveness of an analysis model by using it to predict new data. The Predictor resource provides "scores" that measure how accurately a model predicts new data. You can use these scores to measure the effectiveness of analysis models as you adjust the values used for the Sample Size and Input and Output Attribute Fraction parameters. You use the parameter Measured Accuracy Sample Fraction to set the number of cases used for testing.

The Predictor resource includes two scores. One is called the Recommendation Score. This score is designed to measure the quality of your analysis model when used to recommend products for cross-selling. It measures the quality of a ranked list of recommendations returned from the model. The second is called the Data Fit Score. This score is designed to measure the quality of predictions made by an analysis model when filling in missing data, such as missing user properties. You can view these scores in Commerce Server Manager under the Models node. The scores are stored in your Commerce Server Data Warehouse in the PredictorModels table under the columns DataFitScore and Recommendation Score.

The Recommendation Score works as follows. Each case in the new (test) data is fed to the analysis model one at a time, with one of the transactions (chosen at random) removed. The model then returns a list of recommendations (at most the number of recommendations in the Measured Accuracy Maximum Predictions parameter), and the model is considered to be successful if the transaction that was removed is on the list. The score is the percentage of cases in which the analysis model was successful. The parameter Measured Accuracy Maximum Predictions is set at model build time and should correspond to the number of recommendations you plan to show to the user.

The Data Fit Score is the geometric average of the probability that the analysis model assigns to an observation in the test data, divided by the probability that a marginal model assigns to the observation. The marginal analysis model is a "straw-horse" model that assumes all attributes are independent of each other.

Both scores evaluate only the ability of the model to make predictions on the cases in the test data. Consequently, in order for either of the scores to be a significant indicator of the actual performance of an analysis model, the test data needs to approximate the distribution of cases that are likely to be seen in practice. Furthermore, it is important that the test data not overlap with the data used to build the analysis model. If the scores vary significantly depending on the particular test data sampled for scoring (for example, by changing the Measured Accuracy Sample Fraction option slightly, you observe a very different score), then your test data is likely to be inadequate. You may also see a high degree of variability if you have an insufficient number of input or "training" cases.

Negative Data Fit Scores for Segment models

The segmentation process groups together cases into segments such that cases in a given segment are more similar than cases in other segments. The segment description summarizes the cases in a segment. The description is probabilistic. For example, suppose that each case represents a user and the Commerce Server Data Warehouse contains the salary of the user and whether the user purchased products X, Y, and Z. The segment description for this example is determined by measuring the following quantities over the users (cases) in a given segment: the average salary (and standard deviation of salary), the probability that product X was purchased, the probability that product Y was purchased, and the probability that product Z was purchased. The Segment model consists of a segment description for each segment.

The Segment model and segment descriptions are computed using only input or "training" cases. Because of this, if there are "test " cases that contain information that was not present in the training cases, small values for the Recommendation Score or negative values for the Data Fit Score may be observed. Ideally, the training cases and test cases will contain similar information. If small values for the Recommendation Score or negative values for the Data Fit Score are observed, increasing the value of the Sample Size parameter or decreasing the value of the Measured Accuracy Sample Fraction parameter may alleviate the problem. Be aware that increasing the Sample Size parameter may result in longer time needed to build the Segment model. Use caution in decreasing the Measured Accuracy Sample Fraction parameter because this results in a smaller number of test cases. In general, it is better to have many test cases.

The Recommendation Score and Data Fit Score evaluate the Segment model only in its ability to make predictions. A Segment model that has a small value for Recommendation Score or a negative value for Data Fit Score indicates that the model may not make accurate predictions only on the test cases. You may likely find the segments produced by the Segment model to be useful for other purposes and you may evaluate them using the Segment Viewer in Commerce Server Business Desk.

See Also

Analysis Models

Analysis Model Configurations

Building a New Analysis Model

Viewing Analysis Models

Viewing Analysis Model Configuration Tables

PredictorClient Object (C++)

PredictorClient Object (Visual Basic)


Deploying the Predictor Resource

Building analysis models is a CPU-intensive process. You can run the Predictor resource on the computer where your Commerce Server Data Warehouse is stored, or you can deploy it to a separate host. If you run the Predictor resource on the same computer as your Data Warehouse, model build time will be faster because the data does not need to be transmitted over a network; however, this could reduce Data Warehouse performance. If you build your analysis models when there is less activity on your Data Warehouse, reduced performance on the Data Warehouse should not become an issue.

Determining whether or not to deploy the Predictor resource on a separate computer (one that does not contain your Data Warehouse) depends on the size and number of analysis models you want to build. If you are building small models that take only a minute or two to build, it is advisable to deploy the Predictor resource on the same computer as your Data Warehouse. If you are building very large analysis models, for example, you have a catalog with 1,000,000 products and you sell all of them regularly, it is advisable to deploy the Predictor resource to a dedicated host.

Note

  • Running your online analytical processing (OLAP) server, the Data Warehouse, and the Predictor resource on the same computer can cause large analysis reports to run slowly.

See Also

Deploying Your Site


Configuring Predictor Resource Properties

Prediction recommendations are enabled by default in the Predictor resource for use with the Commerce Server Data Warehouse. If you want to disable the default recommendations, you must modify the Active Server Pages (ASP) code or rename the analysis model that the ASP code expects to load for the default recommendations.

The first two procedures explain how to configure the Predictor resource properties so that the Predictor resource will list models and model configurations in databases other than the Commerce Server Data Warehouse.

Note

  • If you want to use a database other than the Commerce Server Data Warehouse database, you must reconfigure the Use external database property, and then enter a connection string for the external database using the Data Link Properties dialog box.

To list analysis models and model configurations in an external database

To set the connection string to an external database

To list only models and model configurations in the Commerce Server Data Warehouse

To list analysis models and model configurations in an external database

  1. Expand Commerce Server Manager, expand Global Resources, right-click Predictor on <server name>, and then click Properties.

  2. In the Predictor on <server name> Properties dialog box, on the Properties tab, in the Properties box, select Use external database.

  3. In the Selected property value box, set the property to -1 (True).

The Predictor resource will list models and model configurations from an external database, in addition to those in the Data Warehouse, in the Commerce Server Manager console. (Models and model configurations in the Commerce Server Data Warehouse are always listed.)

After you have set this property, you must set a connection to the external database.

To set the connection string to an external database

  1. Expand Commerce Server Manager, expand Global Resources, right-click Predictor on <server name>, and then click Properties.

  2. In the Predictor on <server name> Properties dialog box, on the Connection Strings tab, select External database, and then click Modify.

  3. In the Data Link Properties dialog box, do the following:
    Use this | To do this
    Select or enter a server name | Select a server name from the drop-down list, or type the location of the server where the database you want to access is located.
    Use Windows NT Integrated security | Click to specify that the provider request a secure (or trusted) connection to a SQL Server running on Microsoft Windows NT.
    Use a specific user name and password | Click to use a supplied user name and password to authenticate your logon information to the data source.
    User name | Type the user ID to use for authentication when you log on to the data source.
    Password | Type the password to use for authentication when you log on to the data source.
    Blank password | Select this option to return a blank password in the connection string.
    Allow saving password | Select this option to allow the password to be saved with the connection string.
    Select the database on the server | Type the database name that you want to access.

    Note

    • For more information about using the Data Link Properties dialog box, click Help in the dialog box.
  4. Click Test Connection to ensure that you have entered server and database information correctly, and then click OK to close the connection message.

  5. To close the Data Link Properties dialog box, click OK.

    In the Predictor on <server name> Properties dialog box, on the Connection Strings tab, the value of the external connection string appears in the Connection strings in this resource box.

  6. To exit the Predictor on <server name> Properties dialog box, click OK.

If you want the value of an external connection string to be ignored, and have only those models and configuration files in the Data Warehouse be listed in the Predictor resource details screen, you must set the Use external database property to 0 (False).

To list only models and model configurations in the Commerce Server Data Warehouse

  1. Expand Commerce Server Manager, expand Global Resources, right-click Predictor on <server name>, and then click Properties.

  2. In the Predictor on <server name> Properties dialog box, on the Properties tab, in the Properties box, select Use external database.

  3. In the Selected property value box, set the property to 0 (False).

  4. To apply the changes and exit the Predictor on <server name> Properties dialog box, click Apply.

Only analysis models and analysis model configurations that are in the Data Warehouse will be listed in the Predictor resource details screen.


Starting and Stopping the Predictor Resource

You can start and stop the Predictor resource using Commerce Server Manager. You can also stop the Predictor resource using the Administrative Tools in Microsoft Windows 2000, but it is preferable to use Commerce Server Manager so that the Predictor resource user interface can update accordingly. When the Predictor resource is started or stopped, the event is recorded in the event log of the local computer.

To start the Predictor resource using Commerce Server Manager

To stop the Predictor resource using Commerce Server Manager

To stop a model build in the Predictor resource using Commerce Server Manager

To pause and resume a model build in the Predictor resource using Commerce Server Manager

To start the Predictor resource using Commerce Server Manager

  • Expand Commerce Server Manager, expand Global Resources, expand Predictor on <server name>, right-click the second Predictor on <server name>, and then click Start.

The Predictor resource is started.

To stop the Predictor resource using Commerce Server Manager

  • Expand Commerce Server Manager, expand Global Resources, expand Predictor on <server name>, right-click the second Predictor on <server name>, and then click Stop.

    Note

    • You can stop the Predictor resource only if it is running.

The Predictor resource is stopped and an event is recorded in the event log of the local computer.

To stop a model build in the Predictor resource using Commerce Server Manager

  • While the analysis model is building, right-click the model name, and then click Stop.

    Note

    • You can stop a model build only if the model status is Running.

An error dialog box appears indicating that the build failed and that the operation ended abnormally. The Predictor resource is stopped and an event is recorded in the event log of the local computer. The status of the build returns to Idle.

To pause and resume a model build in the Predictor resource using Commerce Server Manager

  1. While the analysis model is building, right-click the model name, and then click Pause.

    The status of the build changes to Paused.

  2. To resume building the model, right-click the model name, and then click Resume.

    The status of the build changes to Running.


Building a New Analysis Model

You can build multiple analysis models for each site. The model build process is resource intensive, so it is recommended that you build an analysis model only when the impact on your computer will be minimal.

The time required to build an analysis model depends on the size of the input data (total number of cases), the sample size, the number of attributes in the data, and the hardware and topology of your servers.

To build a new analysis model

  1. Expand Commerce Server Manager, expand Global Resources, expand Predictor on <server name>, expand the second Predictor on <server name>, and then click Model Configurations.

  2. In the details screen, right-click the model configuration you want to use to build an analysis model, and then click Build.

  3. In the Model Build Properties dialog box, do the following:
    Use this | To do this
    Name | Type a name for the analysis model.
    Build priority | Select the build priority for this build. The default is Normal (which is the build priority for the particular build thread).
    Model type | Select from the drop-down list either prediction or segment for this model.

  4. Click Next.

  5. In the second screen of the Model Build Properties dialog box, do the following:
    Use this | To do this
    Sample size | Type the number of cases that are used to build the analysis model. You can change the default value if necessary. For example, if you have a large table with 200,000 rows, you may want to specify that the Predictor resource use only 20,000 rows to build the analysis model. The default is -1 or 20,000, whichever is less.
    Measured accuracy sample fraction | Type the fraction of the sample data you want to use to automatically score the accuracy of the model, as a number between 0.0 and 1.0. For example, if you type 0.0 as the value of the Measured accuracy sample fraction option, the model will not be scored. If you type 0.4, 40 percent of the sample data will be used to score the model. (The remaining 60 percent will be used to build the model.)
    Measured accuracy maximum predictions | Type the maximum number of recommendations to be presented on your site (used to compute the Recommendation Score). The default is 10 attributes.
    Input attribute fraction | Type the fraction of attributes to be used as input to the predictions as a number between 0.0 and 1.0. For example, specifying an input attribute fraction of 0.05 selects the most significant 5 percent of input attributes. The default value is 1.0, which includes all attributes as inputs for prediction. Values less than 1.0 are recommended if the number of attributes is very large, such as product recommendations for a catalog with over 1,000 products.
    Output attribute fraction | Type the fraction of attributes to be predicted as a number between 0.0 and 0.1. For example, specifying an output attribute fraction of 0.05 results in decision trees being built for the most significant 5 percent of attributes. (If the output attributes are products, this will return trees for the 5 percent most popular products.) The default value is 1.0, which produces trees for all attributes. Values less than 1.0 are recommended if the number of attributes is very large, such as product recommendations for a catalog with over 1,000 products.
    Number of Segments | Type the maximum number of segments in which to partition the users. This is an initial hint for the algorithm, which may find fewer significant segments than this value. This value is only available if you are building a Segment model.
    Buffer size | Type the size of the buffer that will be used to read cases during segmentation. The default is 1,000,000 bytes. The buffer size can affect the build time and quality of the model. For example, if the model contains many attributes, you should set a large buffer size. The system resources of the computer running the Predictor resource determine buffer size limitations. This value is only available if you are building a Segment model.

  6. Click Finish.

The status of the build process is displayed in the details screen.

During the build process, the status is Building. When the build process is finished, the status is Idle. If the build process is unsuccessful, a message that describes the problem is displayed and then written to the Commerce Server 2000 Application Log. You can use Event Viewer to view the Application Log.

Note

  • If you build your own Prediction model configuration, you can explicitly list the attributes you want to use for input and output. When you do, the attribute fractions shown in Step 6 apply to these lists. For example, if you put five attributes in the input list and you specify an input attribute fraction of 0.8, then only the four most informative features from that list are used as input attributes when the analysis model is building.

See Also

Viewing Analysis Model Configuration Tables

Predictor Best Practices

Deploying an Analysis Model


Deploying an Analysis Model

To deploy your analysis models to your Web servers, you can have your site developer modify the Global.asa file so that it contains a call to the LoadModelFromDB method. This call loads the Prediction model from your Commerce Server Data Warehouse onto your Web servers when the application is started. This method depends on your Data Warehouse always being available. If you cannot depend on your Data Warehouse to be available all the time, then use the following method.

You can deploy analysis models programmatically if you cannot ensure that the Data Warehouse you are loading your model from will always be available, or if you are concerned about minimizing your site re-initialization time. Be aware that this method does constitute extra work for your site developer.

You can have your site developer write a script that loads the model from the Data Warehouse (LoadModelFromDB), saves it to a file (SaveModelToFile) on the computer containing the Predictor resource, and then copies that file to each Web server.

After the model is built, the site developer must modify the ASP file located on each Web server in order to load the model from the file in which it was saved (LoadModelFromFile) onto each server. The site developer then must call one of the prediction methods (Predict, PredictMostLikelySegment, or PredictAllSegments) with the appropriate parameters.

Note

  • Although your site developer can use the prediction methods to create both Segment and Prediction models, do not use Segment models for real-time recommendations because they are not optimized for this purpose and will not produce recommendations as accurate as Prediction models. Always build and use Prediction models for real-time recommendations on your site. You can also use the same model configuration to build a separate Segment model, based on the same data, and view it with the Segment Viewer in Commerce Server Business Desk. For information about using prediction methods, see Prediction Objects.

See Also

Deploying the Predictor Resource

Deploying Your Site


Viewing Analysis Model Configuration Tables

You can view the analysis model configuration tables and columns using Microsoft SQL Server Enterprise Manager.

To view the analysis model configuration tables

  1. Expand Microsoft SQL Servers, expand SQL Server Group, expand the server that contains the database you want to view, expand Databases, expand the database that contains the tables you want to view, and then click Tables.

    A list of all the tables in the database you selected appears in the details screen.

  2. In the details screen, double-click the name of the table that contains the columns you want to view. The model configuration table names are PredictorModelCfgs, PredictorDataTables, and PredictorModels.

The Table Properties - <table name> dialog box appears containing a list of the column names and associated attributes.

See Also

Analysis Model Configurations

Analysis Models

Viewing Analysis Models

PredictorModels Table


Viewing Analysis Models

You can view the Prediction models that you created with Commerce Server 2000 using the Prediction Model Viewer, accessed through Commerce Server Manager. The Prediction Model Viewer contains two views: Dependency Network view and Decision Tree view.

For information about how to view Segment models, see Viewing a Segment Model.

To view a Prediction model

  1. Expand Commerce Server Manager, expand Global Resources, expand Predictor on <server name>, expand the second Predictor on <server name>, and then click Models.

  2. In the details screen, right-click the Prediction model you want to view, and then click View Model.

The Prediction Model Viewer appears with the model you chose in Dependency Network view (the default).

See Also

Using Dependency Network View

Using Decision Tree View

Viewing a Segment Model


Using Dependency Network View

You use Dependency Network view to view your Prediction models as graphs.

This section contains:

  • Finding All Available Nodes in Dependency Network View

  • Using the Slider in Dependency Network View

  • Arranging the Layout in Dependency Network View

  • Zooming In and Out in Dependency Network View

  • Enlarging and Shrinking Nodes in Dependency Network View

  • Using Fit to Page in Dependency Network View

  • Viewing Decision Tree Details in Dependency Network View


Finding All Available Nodes in Dependency Network View

Use the Find toolbar button to display a list of all the available nodes in Dependency Network view. This option is useful when your model contains hundreds of nodes because you can quickly access a specific node.

To find a node

  1. Expand Commerce Server Manager, expand Global Resources, expand Predictor on <server name>, expand the second Predictor on <server name>, and then click Models.

  2. In the details screen, right-click the Prediction model you want to view, and then click View Model.

  3. On the Edit menu, click Find on the toolbar. The Node Finder dialog box appears.

  4. In the Node Finder dialog box, in the Node Name box, type part of or all of the name of the node you want to find.
The Node Finder dialog box

Click the illustration to enlarge or reduce.

  1. Select none, one, or both of the following options:
    • To view all hidden nodes, select the Show hidden nodes box.

    • To view all nodes connected to the node you want to find, select the Add Linked Nodes box.
  2. Click Go to Node.

The Prediction Model Viewer displays the node you are searching for in Dependency Network view, or it displays the node you are searching for and all the nodes connected to the node you are searching for in Dependency Network view, depending on the options you selected in the previous steps.

Note

  • To find a node and then view it in Decision Tree view, click Show Tree on the Node Finder dialog box.


Using the Slider in Dependency Network View

You can use the slider in Dependency Network view to hide the weakest dependencies in your model.

To use the slider

  1. Expand Commerce Server Manager, expand Global Resources, expand Predictor on <server name>, expand the second Predictor on <server name>, and then click Models.

  2. In the details screen, right-click the Prediction model you want to view, and then click View Model.

  3. Point to the top of the slider, hold down your left mouse button, and drag the slider to the stopping point you want to view.


Arranging the Layout in Dependency Network View

You can change the default layout arrangement of your model in Dependency Network view. You may want to change the layout if it is difficult to see the dependencies that you want to view.

To change the layout arrangement

  1. Expand Commerce Server Manager, expand Global Resources, expand Predictor on <server name>, expand the second Predictor on <server name>, and then click Models.

  2. In the details screen, right-click the Prediction model you want to view, and then click View Model.

  3. Click Improve Layout on the toolbar to stop the layout improvement process, and then drag one or more nodes to a better position on the screen.

    Note

    • To start the layout improvement process, and return to an automatic layout of the nodes, click Improve Layout on the toolbar to automatically re-layout all nodes.

All connecting nodes and arcs are moved into the new position.


Zooming In and Out in Dependency Network View

You can enlarge or reduce the size of a Prediction model as it appears in the Prediction Model Viewer. You may need to enlarge or reduce the model size in order to view details about a particular area of the model.

To zoom in

  1. Expand Commerce Server Manager, expand Global Resources, expand Predictor on <server name>, expand the second Predictor on <server name>, and then click Models.

  2. In the details screen, right-click the Prediction model you want to view, and then click View Model.

  3. Click Zoom In on the toolbar.

The model is enlarged 10 percent in the Prediction Model Viewer.

To zoom out

  1. Expand Commerce Server Manager, expand Global Resources, expand Predictor on <server name>, expand the second Predictor on <server name>, and then click Models.

  2. In the details screen, right-click the Prediction model you want to view, and then click View Model.

  3. Click Zoom Out on the toolbar.

The model is reduced 10 percent in the Prediction Model Viewer.


Enlarging and Shrinking Nodes in Dependency Network View

You can enlarge or shrink the nodes in a Prediction model without changing the size of the model itself in Dependency Network view.

To enlarge nodes

  1. Expand Commerce Server Manager, expand Global Resources, expand Predictor on <server name>, expand the second Predictor on <server name>, and then click Models.

  2. In the details screen, right-click the Prediction model you want to view, and then click View Model.

  3. Click Improve Layout on the toolbar to stop layout improvement, click a node, and then click EnlargeNode on the toolbar to enlarge the nodes.

The nodes grow. Click Improve Layout on the toolbar to continue layout improvement. If the layout process determines that the nodes are not in proportion, it adjusts them.

To shrink nodes

  1. Expand Commerce Server Manager, expand Global Resources, expand Predictor on <server name>, expand the second Predictor on <server name>, and then click Models.

  2. In the details screen, right-click the Prediction model you want to view, and then click View Model.

  3. Click Improve Layout on the toolbar to stop layout improvement, click a node, and then click Shrink Nodes on the toolbar.

The nodes shrink. Click Improve Layout on the toolbar to continue layout improvement. If the layout process determines that the nodes are not in proportion, it adjusts them.


Using Fit to Page in Dependency Network View

You use the "Fit to Page" option to scale a Prediction model so that it will fit in the viewing area of the Prediction Model Viewer.

To scale a model to fit in the Prediction Model Viewer viewing area

  1. Expand Commerce Server Manager, expand Global Resources, expand Predictor on <server name>, expand the second Predictor on <server name>, and then click Models.

  2. In the details screen, right-click the Prediction model you want to view, and then click View Model.

  3. Click Fit to Page on the toolbar.

The model is scaled to fit within the boundaries of the viewing area in the Prediction Model Viewer.


Viewing Decision Tree Details in Dependency Network View

You can view the decision tree details of your Prediction model from Dependency Network view.

To view decision tree details from Dependency Network view

  1. Expand Commerce Server Manager, expand Global Resources, expand Predictor on <server name>, expand the second Predictor on <server name>, and then click Models.

  2. In the details screen, right-click the Prediction model you want to view, and then click View Model.

  3. Double-click the node that contains the decision tree details you want to view.

The Prediction Model Viewer changes to Decision Tree view, showing the decision tree for that node.

To return to Dependency Network view after viewing the decision tree details

  1. Expand Commerce Server Manager, expand Global Resources, expand Predictor on <server name>, expand the second Predictor on <server name>, and then click Models.

  2. In the details screen, right-click the Prediction model you want to view, and then click View Model.

  3. Double-click the model node that contains the decision tree details you want to view.

  4. To exit Decision Tree view and return to Dependency Network view, click Back Button on the toolbar.

Decision Tree view changes to Dependency Network view.


Using Decision Tree View

You use the Predictor resource decision tree to analyze your analysis model.

This section contains:

  • Zooming In and Out in Decision Tree View

  • Enlarging and Shrinking Nodes in Decision Tree View

  • Using Fit to Page in Decision Tree View

  • Using Return to Graph in Decision Tree View


Zooming In and Out in Decision Tree View

You can change the size of a Prediction model as it appears in Decision Tree view in order to view details about a particular area of the model or to view the entire model.

To zoom in

  1. Expand Commerce Server Manager, expand Global Resources, expand Predictor on <server name>, expand the second Predictor on <server name>, and then click Models.

  2. In the details screen, right-click the Prediction model you want to view, and then click View Model.

  3. Double-click the model node that contains the decision tree details you want to view.

  4. Click Zoom In on the toolbar.

Decision Tree view of the model is enlarged 10 percent in the Prediction Model Viewer.

To zoom out

  1. Expand Commerce Server Manager, expand Global Resources, expand Predictor on <server name>, expand the second Predictor on <server name>, and then click Models.

  2. In the details screen, right-click the Prediction model you want to view, and then click View Model.

  3. Double-click the model node that contains the decision tree details you want to view.

  4. Click Zoom Out on the toolbar.

Decision Tree view of the model is reduced 10 percent in the Prediction Model Viewer.


Enlarging and Shrinking Nodes in Decision Tree View

You can enlarge or shrink the nodes in a Prediction model without changing the size of the model itself.

To enlarge nodes

  1. Expand Commerce Server Manager, expand Global Resources, expand Predictor on <server name>, expand the second Predictor on <server name>, and then click Models.

  2. In the details screen, right-click the Prediction model you want to view, and then click View Model.

  3. Double-click the model node that contains the decision tree details you want to view.

  4. Select the node you want to enlarge, and then click Enlarge Node on the toolbar.

To shrink nodes

  1. Expand Commerce Server Manager, expand Global Resources, expand Predictor on <server name>, expand the second Predictor on <server name>, and then click Models.

  2. In the details screen, right-click the Prediction model you want to view, and then click View Model.

  3. Double-click the model node that contains the decision tree details you want to view.

  4. Select the node you want to shrink, and then click Shrink Node on the toolbar.


Using Fit to Page in Decision Tree View

You use the "Fit to Page" option to scale a Prediction model so that it will fit in the viewing area of the Prediction Model Viewer.

To scale a model to fit in the Prediction Model Viewer viewing area

  1. Expand Commerce Server Manager, expand Global Resources, expand Predictor on <server name>, expand the second Predictor on <server name>, and then click Models.

  2. In the details screen, right-click the Prediction model you want to view, and then click View Model.

  3. Double-click the model node that contains the decision tree details you want to view.

  4. Click Fit to Page on the toolbar.

The model is scaled to fit within the boundaries of the viewing area in the Prediction Model Viewer.


Using Return to Graph in Decision Tree View

You use the Return to Graph option to exit from Decision Tree view and return to Dependency Network view.

To exit Decision Tree view and return to Dependency Network view

  1. Expand Commerce Server Manager, expand Global Resources, expand Predictor on <server name>, expand the second Predictor on <server name>, and then click Models.

  2. In the details screen, right-click the Prediction model you want to view, and then click View Model.

  3. Double-click the model node that contains the decision tree details you want to view.

  4. Click Return to Graph on the toolbar.

Decision Tree view closes and Dependency Network view opens.


Rebuilding an Analysis Model

Rebuilding an analysis model is necessary when one of two events occurs: the current model data file is corrupt or the data used to build the model has changed substantially since the last model build.

To rebuild an analysis model

  1. Expand Commerce Server Manager, expand Global Resources, expand Predictor on <server name>, expand the second Predictor on <server name>, and then click Models.

  2. In the details screen, right-click the model you want rebuild, and then click Rebuild.

  3. In the Model Build Properties dialog box, click Next to accept the model information you previously entered.

  4. In the Model Build Properties dialog box, click Finish to accept the model information you previously entered.

The analysis model starts building, showing the build status on the details screen as Running. After the model is built, the build status changes to Idle.

See Also

Building a New Analysis Model

Viewing Analysis Models


Renaming an Analysis Model

When you rename an analysis model, verify that the Web site using the model is also updated and that no other site is using the model under the old name.

To rename an analysis model

  1. Expand Commerce Server Manager, expand Global Resources, expand Predictor on <server name>, expand the second Predictor on <server name>, and then click Models.

  2. In the details screen, right-click the model you want to rename, and then click Rename.

  3. Type a new name for the model, and then press ENTER.

  4. In the <model name> renaming confirmation dialog box, click Yes to accept the changes.

See Also

Building a New Analysis Model

Viewing Analysis Models


Deleting an Analysis Model

Before you delete an analysis model, verify that your Web site is no longer using that model.

To delete an analysis model

  1. Expand Commerce Server Manager, expand Global Resources, expand Predictor on <server name>, expand the second Predictor on <server name>, and then click Models.

  2. In the details screen, right-click the model you want to delete, and then click Delete.

  3. In the <model name> delete confirmation dialog box, click Yes to delete the model.

The model is deleted from the list of available models.

Caution

  • After you delete a model, it cannot be restored; you must create a new model.


Monitoring the Predictor Resource

You can monitor the status of your analysis models through Commerce Server Manager or you can use performance counters to help you monitor the performance of the Predictor resource for prediction time, model load time, number of times a model is loaded, or the total number of predictions made.

When you view the current status of an analysis model, the following information is displayed in the details screen:

  • Model Name

  • Model Type

  • Size of Last Model Generated

  • Date/Time Last Model Was Generated

  • Time Taken to Build Last Model

  • Status of service (The status can be one of the following: Building Model, Idle, Loading Data, Running, or Paused.)

  • Source Configuration

  • Recommended Score

  • Data Fit Score

If you receive the message Build Failed, open the Event Viewer to view the event log. Depending on the type of failure that occurred, you should be able to adjust the appropriate parameters and rebuild the model.

The Predictor resource has four performance counters, one (the Client Avg Prediction Time counter) that allows you to measure how fast predictions are occurring, and three others that count how often certain operations on the Predictor Client Object are being called.

For more information about Predictor performance counters, see Monitoring the Predictor Resource.

See Also

Predictor Best Practices

Analysis Model Effectiveness


Running the Profiles Resource

You use the Commerce Server Profiles resource to manage the collection of data on your Web site. For example, you can create profile definitions that control the data that is collected from users on your Web site. You can define the data that is collected with a profile definition, and designate whether a particular piece of data is exported to the Commerce Server Data Warehouse. You can create data sources that control where the data is stored when it is collected. You can create site terms to provide users with options to choose from when they answer data collection questions on your site, such as a list of colors from which to choose their favorite color.

This section contains:

  • Workflow for Profiles. Illustrates the workflow for managing profiles.

  • About the Profiles Resource. Describes the features and functionality of the Profiles resource.

  • Configuring the Profiles Resource. Explains how to change the connection string for the Profiles resource.

  • Adding a New Data Source. Explains how to add and partition a new data source that you use to map the information you collect on your Web site to the databases (or LDAP sources) you use to store the collected data.

  • Adding a New Data Object. Explains how to add a new data object to expose a database table or an LDAP class to a profile definition.

  • Adding a New Data Member. Explains how to add a new data member that you use to map a profile property to a specified column of a database table or to a specified attribute of an LDAP class.

  • Adding a New Profile Definition. Explains how to add profile definitions and map them to data objects.

  • Adding Properties to Profile Definitions. Explains how to add profile properties and profile property custom attributes.

  • Validating Profile Definitions. Explains how to validate a single profile definition or all of your profile definitions to verify that the profile properties are correctly mapped to the data store.

  • Adding a Profile Definition to a Profile Definition. Explains how to reference a property of a profile definition to another profile definition so that two profiles can be linked. For example, you can link a user profile to the address profile for the user.

  • Adding Site Terms. Explains how to create site terms.

  • Adding a Site Term to a Profile Definition. Explains how to add a site term to a profile property so that a user selects a value from the site term as the value for the property.

  • Example: Creating a Profile Definition with Two Data Sources. Explains how to create a user profile definition that stores data in both a Microsoft SQL Server database and a Microsoft Active Directory database.

  • Managing Data Sources. Explains how to modify and delete data sources, data objects, and data members.

  • Managing Profile Definitions. Explains how to modify and delete profile definitions.

  • Managing Profile Properties. Explains how to modify and delete profile properties and property custom attributes.

  • Managing Site Terms. Explains how to modify and delete site terms and site term values.


Workflow for Profiles

The following figure illustrates the workflow for creating data sources and profile definitions.

Workflow for the Profiles resource
Add Properties
to a
Profile Definition
Add Site
Term
Add Profile
Definition
Add
Data Member
Add
Data Object
Create Data Source
Create Databases for User Data

  1. You create a new data source to expose databases and LDAP sources to the Profiles resource.

  2. You create a new data object to expose a database table (or an LDAP class) to the Profiles resource.

  3. You create new data members to expose columns in a database table (or attributes in an LDAP class) to the Profiles resource.

  4. You create a new profile definition that uses the data object to map to the database.

  5. You use the profile designer screen in the Profiles resource to add a new property to the profile definition and assign it a data member.

  6. You verify that your profile definitions map to existing data stores.

  7. You use the site terms editor screen in the Profiles resource to create a site term to restrict data input on your Web site.

  8. You use the profile designer screen to link a profile definition or a site term to a profile definition.


About the Profiles Resource

You use the Profiles resource to create data sources, profile definitions, and site terms. You use profile definitions to collect user and business data from your Commerce Server 2000 Web site. You use data sources to map the data collected with profile definitions to the column and table in the database (or attribute and class in a Lightweight Directory Access Protocol (LDAP) source) where that data will be stored. You create site terms to provide choices for users when they enter personal preferences or other information on your Web site.

This section contains:

  • Data Sources

  • Data Source Partitions

  • Profile Definitions

  • Site Terms

  • Sample Data Sources

  • Sample Profile Definitions

  • Sample Site Terms


Data Sources

You use data sources to expose your data store to the Profiles resource, so that the data collected on your Web site, with profile definitions, can be stored in the data store. Commerce Server 2000 supports OLE DB databases and Lightweight Directory Access Protocol (LDAP) sources.

Data sources contain the following components:

  • Data objects. Expose a table in an OLE DB database or a class in an LDAP source to a profile definition. The process of creating a data object does not create a new table in your database or a new class in your LDAP source. Instead, creating a data object makes the table or LDAP class visible to the Profiles resource. The table or class must exist before you create a data object to expose it.

  • Data members. Expose a column in a table in an OLE DB database or an attribute of a class in an LDAP source to a profile property. For example, you use a profile definition to collect information from users when they register on your Web site. The user information (such as first name, last name, and e-mail address) is collected by profile properties. Each property is associated with a data member, which maps (or directs) the information collected to the database column or LDAP attribute that will store it.

    When you create a data member, you do not create a new column in your database table or a new attribute in the class in your LDAP source. Instead, you make the column or LDAP attribute visible to the Profiles resource. The column or attribute must exist before you create a data member to expose it.

The following figure shows how the parts of the physical schema of data storage, data sources, and profile definitions fit together.

Connections between data storage, a data source, and a profile definition
Data Source
Data Object
Data
Member
Data
Member
Data Object
Column
Attribute
Table
Class
OLE DB
database
LDAP Source
Data Source
Property
Property
Profile
definition

See Also

Data Source Partitions

Sample Data Sources

Profile Definitions

Adding a New Data Source

Managing Data Sources


Data Source Partitions

You use the Profiles resource to create partitioned data sources. Commerce Server 2000 supports data source partitioning to accommodate site traffic that can exceed 10 million users. Partitioning is an effective means to scale and maintain the database transaction loads associated with large populations of users. Each partition of a data source can connect to a database or a Lightweight Directory Access Protocol (LDAP) source. With a partitioned data source, the individual databases offer better performance and response times than if all of the data collected with a profile definition is stored in a single database.

Mapping to Multiple Databases

Custom Attributes

Changing Partitions

Hashing Keys

Mapping to Multiple Databases

When you use a partitioned data source to map a profile definition to multiple OLE DB databases or LDAP sources, the data storage devices (OLE DB databases or LDAP sources) must have identical schemas. For example, if you create a partitioned data source that maps a profile definition to three databases, the table definitions of all three databases must be identical. Commerce Server data sources support a maximum of 128 total partitions.

Custom Attributes

You can add custom attributes to a data source partition. Custom attributes are application specific. Typically, the attributes that are common to all profile definitions or data stores are stored in the ClassDef or SourceDef table. However, there might be specific attributes that apply only to certain selected data source objects. For example, you can create a custom attribute to maintain the sort order of data sources or partitions on a data source, or to help you maintain consistency with other objects, such as member definition and source definition objects. Data source custom attributes are available only within the Profiles resource.

Changing Partitions

After you add a partition to a data source, you can change the partition, but you cannot remove it. If you want to remove the partitioning of a data source, you must define a new data source, and then delete the old one. When you partition a data source, you must identify one partition as the default partition.

Hashing Keys

A hashing key is a unique key that is used to keep data from a single source (in this case, a profile definition) together, even though physically it is stored in multiple databases. Data sources use a hashing key to partition data across multiple databases. You use the Profiles resource (or the Profile Designer module in Commerce Server Business Desk) to select a profile property to be the hashing key for a profile definition.

If you do not define a profile property as the hashing key, all data collected with a profile definition is stored in the database assigned to the default partition. After you have defined a hashing key, you cannot redefine it. For information about defining a hashing key, see Adding Properties to Profile Definitions.

See Also

Sample Data Sources

Profile Definitions

Adding a New Data Source

Managing Data Sources


Profile Definitions

You use the Profiles resource to create new profile definitions. A profile is a single instance of a profile definition, containing the data that the profile definition collects. For example, when a user enters data into a user profile definition on your Web site, Commerce Server 2000 creates a profile for the user that the business manager can access in Commerce Server Business Desk.

You can use the Profiles resource to add properties to a profile definition that specify what data the profile definition will collect, and to specify the attributes of the properties of a profile definition. Business managers can also do this using the Profile Designer module in Business Desk.

Associating Profiles

Mapping Profile Properties to Storage Locations

Profile Definition Components

Associating Profiles

You can use the Profiles resource to associate profiles. You associate profiles to expand the data that you collect with profile definitions. For example, you want to collect multiple addresses, such as a billing address and a shipping address, from users who purchase items on your Web site. You could do this by adding properties (such as First Name, Last Name, Street, City, State, and Zip Code) for each address you want to collect to the User Object profile definition.

A better way to collect multiple addresses is to add a single property to the User Object profile definition for each address, and use that property to associate address profiles with user profiles. For example, you add a property to the User Object profile definition called "Billing Address." You define the property type of Billing Address as profile. You then select the Address profile definition as the type reference for the Billing Address property.

When a user enters a billing address on your Web site, the billing address is stored in an address profile. The address profile is saved with a unique name. The unique name of the address profile is collected as a string in the Billing Address property of the user profile. Because the user profile contains the unique name of the address profile, the data in the user profile and the address profile can be presented together on your Web site and in reports. For instructions for associating profile definitions, see Adding a Profile Definition to a Profile Definition.

Mapping Profile Properties to Storage Locations

Profile properties use data members to map data entered by users on your Web site to the appropriate storage location. For example, when a user types a first name into the First Name property of the User Object profile definition, the name is stored in the database column that the data member for the First Name property specifies.

After a profile definition has been created with the Profiles resource, the business manager can modify the properties in the profile definition and manage the data available in individual user profiles in Business Desk.

Profile Definition Components

A profile definition contains properties, property groups, and attributes.

Properties

Properties define the actual data that is collected by a profile definition. For example, First Name is a property of the Address profile definition. You can define profile properties as the types in the following table.

Property type | Description
String | Stores up to a maximum of 4,000 Unicode characters. String properties map to string data members.
Long string | Stores up to a maximum of 2 to the power of 17 (2^17) Unicode characters. Long string properties map to string data members.
Number | Stores integers. The maximum length of a number property is determined by the data store. Number properties map to number data members.
Decimal | Stores floating-point numbers. The maximum length of a decimal property is determined by the data store. Decimal properties map to number data members.
Boolean | Stores one of two values (for example, True/False, Yes/No, or 1/0). Boolean properties map to Boolean data members.
Binary | Stores binary content, primarily for programmatic use, up to a maximum size of 4 kilobytes (KB). Binary properties map to binary data members.
Long binary | Stores content, such as spreadsheets, documents, pictures, and audio clips up to a maximum size of 128 KB. Long binary properties map to binary data members.
Date/time | Stores composite date and time values. The format and the maximum length are determined by the data store. Date/time properties map to date/time data members.
Date | Contains date values. The format and the maximum length are determined by the data store. Date properties map to date/time data members.
Time | Contains values for hour, minute, second, and millisecond. The format and the maximum length are determined by the data store. Time properties map to date/time data members.
Currency | Stores numbers in currency format. The format and the maximum length are determined by the data store. Currency properties map to currency data members.
Password | Stores text. The Profiles resource treats the password property like a string property. Business Desk displays the values stored in a password property as asterisks (*). Password properties map to string data members and have a maximum length of 255 Unicode characters.
Site term | Stores valid values from the list of term names associated with the corresponding site term. Site term properties map to string data members and have a maximum length of 255 Unicode characters.
Profile | Stores a value that corresponds to the value of the primary key of a specific instance of that associated profile. Profile properties map to string data members and have a maximum length of 255 Unicode characters.

The property type must be the same as the data type of the data member it is mapped with. For example, you map a string property with a string data member to a string column in the data store. Each property has attributes that define the characteristics of that property.

Property Groups

Property groups are logical groupings of profile properties. You use property groups to organize related properties into groups in the profile designer screen.

Attributes

Attributes are characteristics specified for a property or property group. For example, the property First Name has the profile property attributes Name, Display name, Description, and Type. There are two special types of attributes:

  • Advanced attributes. You use the advanced attributes described in the following table to change how your applications use a profile property. For example, the Exported attribute determines whether a property will be imported into the Commerce Server Data Warehouse.
    Attribute | Description
    Active | Indicates whether this property is displayed in Business Desk.
    Map to Data | Identifies the data member this property uses to map to the database column (or LDAP attribute).
    Key Type Each profile definition requires a property that is a primary key and a property that is a join key, or a property that is a dual key (both primary and join keys). There are four key types you can assign:
    • Unique key. Indicates that the value of this property is unique for all members. Properties designated as unique keys have a U(key) symbol next to their names in the Properties list.

    • Primary key. Identifies the profile. The value of this property must be unique for each profile. You map a property that is specified as a primary key to a unique field in a database or LDAP source. Properties designated as primary keys have a P(key) symbol next to their names in the Properties list.

    • Join key. Relates the profile definition to multiple data objects. You use this to map the properties of the profile definition to data members from different data objects. If you are mapping the profile definition to multiple data objects, you must map the join key to a data member from each data object. This causes the data collected by the property (assigned as the join key) to be persisted in the storage locations represented by the data members. Properties designated as join keys have a J(key) symbol next to their names in the Properties list.

    • Dual (primary and join) key. Uniquely identifies the profile and maps the profile definition to multiple data objects. Properties designated as dual keys have a P(key)J(key) symbol next to their names in the Properties list.
    Required | Specifies that this property is required on your Web site and in Business Desk. However, this attribute is not enforced by the Profiles resource. This attribute is read-only if you have selected a key type.
    Exported | Specifies that this property is imported into the Data Warehouse. You can export only mapped properties. You cannot export properties that are multi-valued and of the type Boolean or properties of type binary, long string, and password.
    Defer Cache | Indicates that this property will not be loaded initially when the profile is retrieved, but will be loaded when this particular property is accessed.
    Multi-valued | Enables the collection of multiple values that are associated with this property. Not all data types and data stores support multiple values.
    Searchable | Indicates that this property is indexed in the underlying data store and is available for searching through the Find By function. You map a searchable attribute to an indexed field in the database or LDAP source.
    RDN | Identifies the Relative Distinguished Name (RDN) for a directory store. Set this value if the property maps to an RDN attribute of an LDAP class in the underlying store.
    Hashing Key | Indicates that this property is used to distribute profile instances across multiple data source partitions. This property is read-only for non-partitioned data sources. To retrieve the profile, you must query on this key.

  • Custom attributes. Custom attributes on profile properties are placeholders for storing application-specific custom information. These attribute/value pairs must be of the type string. The maximum length of the attribute name or the value is 127 Unicode characters. For example, you can create a custom attribute that controls how a property is displayed on a Web site page.

    When you unpack a Solution Site, Commerce Server adds the custom attributes described in the following table.

    Attribute | Description
    sAnonymousAccess | Specifies user access to the property in the Customer Service. This attribute is not implemented in Commerce Server.
    sUserAccess | Specifies registered user access to the property in the Customer Service. Set the attribute value to 0 to hide the property from registered users. Set the attribute value to 1 to allow registered users to view the property. Set the attribute value to 2 to allow registered users to view and edit the property.
    sDelegatedAdminAccess | Specifies delegated administrator access to the property in the Customer Service and the Partner Service. Set the attribute value to 0 to hide the property from delegated administrators. Set the attribute value to 1 to allow delegated administrators to view the property. Set the attribute value to 2 to allow delegated administrators to view and edit the property.
    sSiteAdminAccess | Specifies site developer access to the property in Business Desk. This attribute is not implemented in Commerce Server 2000.
    SearchOptions | Specifies whether the profile property is searchable in the Customer Service and the Partner Service. Set the attribute value to ALL to make the property searchable in both regular and advanced search modes. Set the attribute value to ADVANCED to make the property searchable only in the advanced search mode. Set the attribute value to NONE to exclude the property from searches.
    ShowInList | Specifies whether the property is displayed in the user search results list in the Partner Service. Set the attribute value to 1 to display the property. Set the attribute value to 0 to hide the property.
    sFeatureID | Specifies the site scenarios for which the property is displayed in the Customer Service and the Partner Service. Set the attribute value to 2 to display the property only when the site supports the Delegated Admin options. Set the attribute value to 3 to display the property only when the site uses Active Directory. Set the attribute value to 0 to always display the property regardless of scenario.
    DWMembername | Specifies the name of the Data Warehouse data member the property maps to.

The profile designer is available in both the Profiles resource and Business Desk. For information about using the Profile Designer module in Business Desk, see Business Desk Users.

See Also

Sample Profile Definitions

Adding a New Data Source

Adding a New Data Object

Adding a New Profile Definition

Adding Properties to Profile Definitions


Site Terms

You use site terms to restrict user input to a list of specific values. You use the site terms editor screen in the Profiles resource to create and manage site terms. The business manager can use the Site Terms Editor module in Commerce Server Business Desk to create and manage site terms.

You can define a profile property as a site term to limit user input for that property to the values listed in the site term. For example, you define a "favorite color" property of the type site term. Then, you create a Favorite color site term with the values blue, green, white, and purple. If you ask users what their favorite color is when they register on your Web site, they select from the colors you list in the site term for the favorite color property. That way, you limit the values that users can select from, which makes it easier to target users who have the same favorite color. For information about site terms, see Profiles. For instructions for using the Site Terms Editor module in Business Desk, see Site Terms Editor.

See Also

Profiles

Site Terms Editor

Sample Site Terms

Adding Site Terms

Managing Site Terms


Sample Data Sources

When you unpack a Solution Site, Commerce Server 2000 adds a sample data source, named ProfileService_SQLSource, to the Profiles resource. The ProfileService_SQLSource data source provides you with the Address, BlanketPOs, Organization, and User Object sample data objects.

Address

BlanketPOs

Organization

User Object

Address

The following table lists the data members available in the Address data object.

Name | Data type
g_address_id | String
g_id | String
i_address_type | Number
u_address_name | String
u_last_name | String
u_first_name | String
u_description | String
u_address_line1 | String
u_address_line2 | String
u_city | String
u_region_name | String
u_region_code | String
u_postal_code | String
u_country_name | String
u_country_code | String
u_tel_number | String
u_tel_extension | String
i_locale | Number
u_user_id_changed by | String
d_date_last_changed | DateTime
d_date_created | DateTime

BlanketPOs

The following table lists the data members available in the BlanketPOs data object.

Name | Data type
g_org_id | String
g_po_id | String
u_po_number | String
u_description | String
g_user_id_changed_by | String
d_date_last_changed | DateTime
d_date_created | DateTime

Organization

The following table lists the data members available in the Organization data object.

Name | Data type
g_org_id | String
u_name | String
u_trading_partner_number | String
g_user_id_admin_contact | String
g_user_id_receiver | String
u_org_catalog_set | String
g_user_id_changed_by | String
g_user_purchasing_manager | String
d_date_last_changed | DateTime
d_date_created | DateTime

User Object

The following table lists the data members available in the User Object data object.

Name | Data type
u_logon_name | String
g_org_id | String
g_user_id | String
u_user_title | String
i_user_type | Number
u_last_name | String
u_first_name | String
u_email_address | String
u_tel_number | String
u_tel_extension | String
u_fax_number | String
u_fax_extension | String
u_user_security_password | String
g_user_id_changed_by | String
i_account_status | Number
u_user_catalog_set | String
d_date_registered | DateTime
u_campaign_history | String
i_partner_desk_role | Number
d_date_last_changed | DateTime
d_date_created | DateTime
u_pref1 | String
u_pref2 | String
u_pref3 | String
u_pref4 | String
u_pref5 | String

Note

  • The u_pref data members are provided so that you can add properties to the User Object profile definition without extending your database. You can customize these data members.

The ProfileService_SQLSource data source maps to sample profile definitions that are added by default to the Profiles resource and Commerce Server Business Desk. For information about the sample profile definitions, see Sample Profile Definitions.

See Also

Profile Definitions

Sample Profile Definitions

Adding a New Data Source

Adding a New Data Object

Adding a New Data Member

Managing Data Sources


Sample Profile Definitions

When you unpack a Solution Site, Commerce Server 2000 adds the Address, BlanketPOs, Organization, User Object, and Targeting Context sample profile definitions.

Address

BlanketPOs

Organization

User Object

Targeting Context

Address

The following table lists the properties available in the Address profile definition and the data members in the Address data object to which the properties are mapped.

Property | Data member
Address ID | g_address_id
ID | g_id
Last name | u_last_name
First name | u_first_name
Address name | u_address_name
Address type | i_address_type
Description | u_description
Address line 1 | u_address_line1
Address line 2 | u_address_line2
City | u_city
Region code | u_region_code
State name | u_region_name
Postal code | u_postal_code
Country code | u_country_code
Country name | u_country_name
Telephone number | u_tel_number
Telephone extension | u_tel_extension
Locale ID | i_locale
Changed by | u_user_id_changed_by
Date last changed | d_date_last_changed
Date created | d_date_created

BlanketPOs

The following table lists the properties available in the BlanketPOs profile definition and the data members in the BlanketPOs data object to which the properties are mapped.

Property | Data member
Purchase order ID | g_po_id
Organization ID | g_org_id
PO number | u_po_number
Description | u_description
Changed by | g_user_id_changed_by
Date last changed | d_date_last_changed
Date created | d_date_created

Organization

The following table lists the properties available in the Organization profile definition and the data members in the Organization data object to which the properties are mapped.

Property | Data member
Organization ID | g_org_id
Name | u_name
Trading partner number | u_trading_partner_number
Administrative contact | u_user_id_admin_contact
Receiver | g_user_id_receiver
Organization catalog set | u_org_catalog_set
Changed by | g_user_id_changed_by
Purchasing manager | g_user_id_purchasing_manager
Date last changed | d_date_last_changed
Date created | d_date_created

User Object

The following table lists the properties available in the User Object profile definition and the data members in the User Object data object to which the properties are mapped.

Property | Data member
User ID | g_user_id
Logon name | u_logon_name
User password | u_user_security_password
E-mail | u_email_address
User type | i_user_type
User title | u_user_title
Last name | u_last_name
First name | u_first_name
Telephone number | u_tel_number
Telephone extension | u_tel_extension
Fax number | u_fax_number
Fax extension | u_fax_extension
Changed by | g_user_id_changed_by
Organization ID | g_org_id
Account status | i_account_status
User catalog set | u_user_catalog_set
Date registered | d_date_registered
Campaign history | u_campaign_history
Partner Service role flags | i_partner_desk_role
Date last changed | d_date_last_changed
Date created | d_date_created

Targeting Context

The Targeting Context profile definition contains one property, Page Group, which is not mapped.

See Also

Data Sources

Adding a New Data Source

Adding a New Data Object

Adding a New Profile Definition

Adding Properties to Profile Definitions

Managing Profile Definitions


Sample Site Terms

When you unpack the Retail Solution Site, Commerce Server 2000 adds five sample site terms to the Profiles resource. You cannot delete or modify these site terms. The following table lists the site terms available when you unpack the Retail Solution Site.

Site term | Terms
Account Status | Active Account Inactive Account
Days | Sunday Monday Tuesday Wednesday Thursday Friday Saturday
Months | January February March April May June July August September October November December
User Role | Administrator Normal User
User Type | Guest User Registered User

See Also

Adding Site Terms

Managing Site Terms


Configuring the Profiles Resource

You can use Commerce Server Manager to change the Profiles resource connection string. The Profiles resource connection string is set during the unpacking process.

To change the Profiles resource connection string

  1. Expand Commerce Server Manager, expand Global Resources, right-click Profiles, and then click Properties.

  2. In the Profiles (<site name>) Properties dialog box, on the Connection Strings tab, select the connection string you want to change, and then click Modify.

  3. In the Data Link Properties dialog box, on the Connection tab, do the following:
    Use this | To do this
    Select or enter a server name | Select a server name from the drop-down list, or type the location of the server where the database you want to access is located.
    Refresh | Click to refresh the server list.
    Use Windows NT integrated security | Do not use this option. Commerce Server does not support Windows NT authentication.
    Use a specified user name and password | Select this option to supply a user name and password to authenticate your logon information to the data source.
    User Name | Type the user ID to use for authentication when you log on to the data source.
    Password | Type the password to use for authentication when you log on to the data source.
    Blank password | Select this option to enable the specified provider to return a blank password in the connection string.
    Allow saving password | Select this option to allow the password to be saved with the connection string. Whether the password is included in the connection string depends on the functionality of the calling application. If the password is saved, it is returned and saved unmasked and unencrypted.
    Select the database on the server | Select this option to type the database name that you are mapping the data source to, or select the database name from the drop-down list.
    Attach a database file as a database name | Do not use this option. Commerce Server does not support SQL Server version 6.5 or earlier.
    Using the filename | Do not use this option. Commerce Server does not support SQL Server version 6.5 or earlier.
    Test Connection | Click to connect to the specified data source. If the connection fails, verify that the settings are correct. Spelling errors and case sensitivity can cause failed connections.

  4. To return to the Profiles (<site name>) Properties dialog box, click OK.

  5. To apply your changes, click Apply.

The connection string changes are applied to the Profiles resource.

Note

  • All connection strings in the Profiles resource are updated when any one string is changed.

See Also

About the Profiles Resource


Adding a New Data Source

You use the Profiles resource to add new data sources for storing profile data. You use profile data sources to map profile data to your data stores. Data stores can be OLE DB databases or LDAP sources.

You use a data source to map profile definitions to a database or LDAP source. You can partition the data source to map profile definitions to multiple data stores. You must create a database or an LDAP source before you can create a data source. The Profiles resource does not modify the underlying data store. You must make any schema changes directly to the database or to the LDAP store.

Important

  • Some OLE DB drivers listed in the Data Link Properties dialog box are not appropriate for use with the Profiles resource. Do not use the following drivers:
    • Microsoft OLE DB Provider for DTS Packages

    • Microsoft OLE DB Provider for Indexing Service

    • Microsoft OLE DB Provider for Internet Publishing

    • Microsoft OLE DB Simple Packages

    • Microsoft OLE DB Provider for Microsoft Site Server Search

    • Microsoft OLE DB Provider for Commerce Server

    If you select any of these drivers in the Data Link Properties dialog box, you may get a Microsoft Data Link error message stating that the provider is no longer available.

To add a new SQL Server data source

To add a new LDAPv3-Compliant Source data source

To add a custom attribute to a data source partition

To add a new SQL Server data source

  1. Expand Commerce Server Manager, expand Global Resources, expand Profiles, expand Profile Catalog, right-click Data Sources, and then click New Data Source.

  2. In the New Data Source dialog box, do the following:
    Use this | To do this
    Name | Type the programmatic name of the data source. The name can contain a maximum of 127 alphanumeric characters and the underscore (_) symbol. The name cannot contain spaces.
    Display Name | Type the name you want displayed for the data source. The display name can contain a maximum of 127 Unicode characters.
    Description | Type a description for the data source. The description can contain a maximum of 127 Unicode characters.

  3. Click Next.

  4. In the Data Source dialog box, in the Source Type drop-down list, select OLEDB-ANSI Provider, and then click Next.

  5. In the Partitions dialog box, select Partitioned Data Source to partition the data source, and then click Add.

  6. In the Partition dialog box, click Edit.

  7. In the Data Link Properties dialog box, on the Provider tab, select Microsoft OLE DB Provider for SQL Server as the provider for your data source, and then click Next.

  8. In the Data Link Properties dialog box, on the Connection tab, do the following:
    Use this | To do this
    Select or enter a server name | Select a server name from the drop-down list, or type the location of the server where the database you want to access is located.
    Refresh | Click to refresh the server list.
    Use Windows NT integrated security | Do not use this option. Commerce Server does not support Windows NT authentication.
    Use a specified user name and password | Select this option to supply a user name and password to authenticate your logon information to the data source.
    User Name | Type the user ID to use for authentication when you log on to the data source.
    Password | Type the password to use for authentication when you log on to the data source.
    Blank password | Select this option to enable the specified provider to return a blank password in the connection string.
    Allow saving password | Select this option to allow the password to be saved with the connection string. Whether the password is included in the connection string depends on the functionality of the calling application. If the password is saved, it is returned and saved unmasked and unencrypted.
    Select the database on the server | Select this option to type the database name that you are mapping the data source to, or select the database name from the drop-down list.
    Attach a database file as a database name | Do not use this option. Commerce Server does not support SQL Server version 6.5 or earlier.
    Using the filename | Do not use this option. Commerce Server does not support SQL Server version 6.5 or earlier.
    Test Connection | Click to attempt a connection to the specified data source. If the connection fails, verify that the settings are correct. Spelling errors and case sensitivity can cause failed connections.

  9. To return to the Partition dialog box, click OK.

  10. To save the data source and return to Commerce Server Manager, click Finish.

The data source is saved. You can add partitions, custom attributes, and data objects to it.

To add a new LDAPv3-Compliant Source data source

  1. Expand Commerce Server Manager, expand Global Resources, expand Profiles, expand Profile Catalog, right-click Data Sources, and then click New Data Source.

  2. In the New Data Source dialog box, do the following:
    Use this | To do this
    Name | Type the programmatic name of the data source. The name can contain a maximum of 127 alphanumeric characters and the underscore (_) symbol. The name cannot contain spaces.
    Display Name | Type the name you want displayed for the data source. The display name can contain a maximum of 127 Unicode characters.
    Description | Type a description for the data source. The description can contain a maximum of 127 Unicode characters.

  3. Click Next.

  4. In the Data Source dialog box, in the Source Type drop-down list, select LDAPv3-Compliant Source, and then click Next.

  5. In the Partitions dialog box, click Partitioned Data Source to partition the data source, and then click Add.

  6. In the Partition dialog box, click Edit.

  7. In the LDAP Connection String dialog box, do the following:
    Use this | To do this
    Server | Type the server name where the LDAP source is located.
    Port | Type the port name. The default port is 389.

  8. To return to the Partition dialog box, click OK.

  9. In the Partition dialog box, do the following:
    Use this | To do this
    Default Partition | Select to designate this partition as the default partition.
    User Name | Type the user name you use to access the LDAP source. If you are using an Active Directory server, type the user name in the form domain\username.
    Password | Type the password you use to access the LDAP source.

  10. To open the System Attributes dialog box, click Next.

  11. In the System Attributes dialog box, do the following:
    Use this | To do this
    Parent URL | Type the location in the LDAP directory tree where you want your data to be stored.
    Use the same credentials for all users | Select this option to specify that the Profiles resource always use the same credentials when binding to LDAP sources. If this option is not selected, the Profiles resource will use the credentials of the current user.
    Allow Simple Bind | Select this option to send the password in clear text. This option is less secure, but is required by some directory services.
    Dynamic Container | Select this option to connect to a dynamic store, such as Internet Locator Service (ILS).
    One-Level | Select this option to set the default search scope to the current directory.
    Sub-Tree | Select this option to set the default search scope to the current directory and sub-directories.
    Domain Name | Type the domain name of the server if you are using Active Directory.
    Discover | Click to find the domain name.

  12. Click Next.

  13. To return to the Partition dialog box, click OK.

  14. To save the data source and return to Commerce Server Manager, click Finish.

The data source is saved. You can add partitions, custom attributes, and data objects to it.

To add a custom attribute to a data source partition

  1. Expand Commerce Server Manager, expand Global Resources, expand Profiles, expand Profile Catalog, expand Data Sources, right-click the data source that contains the partition you want to add a custom attribute for, and then click Properties.

  2. In the Properties dialog box, on the Partitions tab, select the partition you want to add a custom attribute for, and then click Edit.

  3. In the Partitions dialog box, on the Custom Attributes tab, click New to add attributes to the data source.

  4. In the Custom Attribute dialog box, do the following:
    Use this | To do this
    Name | Type a programmatic name for the attribute. The name can contain a maximum of 127 alphanumeric characters and the underscore (_) symbol. The name cannot contain spaces.
    Display Name | Type the name you want displayed for the attribute. The display name can contain a maximum of 127 Unicode characters.
    Description | Type a description for the attribute. The description can contain a maximum of 127 Unicode characters.
    Value | Type a value for the attribute.

  5. To save the attribute, click OK.

  6. To save the partition information, click OK.

  7. To return to Commerce Server Manager, click Finish.

The data source is saved with the custom attribute.

See Also

About the Profiles Resource

Adding a New Data Object

Adding a New Data Member

Managing Data Sources


Adding a New Data Object

You use the Profiles resource to add a data object to a data source. You select the table in the database (or the class in the LDAP source) that contains the column where you want to store the data collected for a property in a profile definition.

Before you use the Profiles resource to create a data object, you must create a data source. The Profiles resource will not modify the underlying data store. You must make any changes directly to the database or to the LDAP store.

To add a new data object

  1. Expand Commerce Server Manager, expand Global Resources, expand Profiles, expand Profile Catalog, expand Data Sources, expand the data source that you are adding a data object to, right-click Data Objects, and then click New Data Object.

  2. In the New Data Object dialog box, do the following:
    Use this | To do this
    Object Name | Select the data object from the drop-down list that is the name of a table or an LDAP class in the underlying data store.
    Display Name | Type the name you want displayed for the data object. The display name can contain a maximum of 127 Unicode characters.
    Description | Type a description for the data object. The description can contain a maximum of 127 Unicode characters.

  3. Click OK.

The data object is saved. You can add data members to it and you can use it to map a profile definition to a database column (or an LDAP class). You must add data members with which to map profile properties.

See Also

About the Profiles Resource

Adding a New Data Source

Adding a New Data Member

Managing Data Sources


Adding a New Data Member

You use the Profiles resource to add a data member to a data object by selecting the column in an exposed table of the database (or the attribute in an exposed class of the LDAP source) where you want to store the data collected for a property in a profile definition.

When you define a property in a profile definition, you map the property with the data member to the column in a database table (or attribute in an LDAP class) that it exposes. When a user enters data into a property in a profile definition on your Web site, the data the user enters is stored in the designated database column or LDAP attribute. The Profiles resource does not modify the underlying data store. You must make any changes directly to the database or to the LDAP store.

To add a data member

  1. Expand Commerce Server Manager, expand Global Resources, expand Profiles, expand Profile Catalog, expand Data Sources, expand the data source that contains the data object that you want to add a data member to, expand Data Objects, right-click the data object you want to add a data member to, and then click New Data Member.

  2. In the New Data Member dialog box, do the following:
    Use this | To do this
    Member Name Select an available data member name from the list. Unavailable data members have already been added to a data object and appear dimmed. The data members in the list have the same names as the columns or LDAP attributes in the underlying data store to which they map.

    If you want to add additional data members, (or if there are no available data members in the list) you must create a new column or attribute in the underlying data store. The name must match the name of the column or attribute to which the data member maps. The name can contain a maximum of 127 alphanumeric characters and the underscore (_) symbol. The name cannot contain spaces.
    Display Name | Type the name you want displayed in the application for the data member. The display name can contain a maximum of 127 Unicode characters.
    Description | Type a description for the data member. The description can contain a maximum of 127 Unicode characters.
    Type Select the data type for the data member. The data type must be the same as the property that you will map with the data member. The following data types are supported:
    • Binary

    • Boolean

    • Currency

    • DateTime

    • Number

    • String
    Multi-valued | Select this option to enable the collection of multiple values that are associated with the data member.
    Required | Specifies that this property is required on your Web site and in Business Desk. However, this attribute is not enforced by the Profiles resource.
    Indexed | Select this option if the data will be indexed on this data member.
    Primary key | Select this option to designate this data member as the primary key. You must select one data member in each data object to be the primary key.

  3. Click Add. The data member appears in the data member list in the New Data Member dialog box.

  4. Click Finish.

The data member appears in the data member screen.

See Also

About the Profiles Resource

Configuring the Profiles Resource

Adding a New Profile Definition

Example: Creating a Profile Definition with Two Data Sources

Managing Data Sources


Adding a New Profile Definition

You use the Profiles resource to create new profile definitions. For example, the business manager may ask you to create a new profile definition to make additional data available from your Web site and Commerce Server Business Desk. You can create a profile definition that is automatically mapped to a data object. You can also create a profile definition that is not mapped to a data object. You use profile definitions to define the data that you collect about users who visit your Web site.

You can create custom attributes for a profile definition. For example, you can add a custom attribute called defaultParentURL that controls where profiles are stored in the underlying LDAP store. Custom attributes on profile properties are placeholders for storing application-specific information. These attribute/value pairs must be of the type string. Profile definition custom attributes are available only within the Profiles resource.

To add a new profile definition that is mapped to a data object

To add a new profile definition that is not mapped to a data object

To add a custom attribute to a profile definition

To add a new profile definition that is mapped to a data object

  1. Expand Commerce Server Manager, expand Global Resources, expand Profiles, expand Profile Catalog, expand Data Sources, expand the data source that contains the data object that you want to map the new profile definition with, expand Data Objects, right-click the data object the new profile definition will be mapped with, select New, and then click New Profile.

  2. In the New Profile Definition dialog box, do the following:
    Use this | To do this
    Name | Type a programmatic name for the new profile definition. The name can contain a maximum of 127 alphanumeric characters and the underscore (_) symbol. The name cannot contain spaces.
    Display Name | Type the name you want displayed for the new profile definition. The display name can contain a maximum of 127 Unicode characters.
    Description | Type a description for the new profile definition. The description can contain a maximum of 127 Unicode characters.

  3. To close the dialog box, click OK.

  4. Click Finish.

The new profile definition appears in the list of available profile definitions in Commerce Server Manager. The new profile definition contains the properties mapped to the data members of the data object from which you built the profile definition.

To add a profile definition that is not mapped to a data object

  1. Expand Commerce Server Manager, expand Profiles, expand Profile Catalog, right-click Profile Definitions, and then select New Profile.

  2. In the New Profile Definition dialog box, do the following:
    Use this | To do this
    Name | Type a programmatic name for the new profile definition. The name can contain a maximum of 127 alphanumeric characters and the underscore (_) symbol. The name cannot contain spaces.
    Display Name | Type the name you want displayed for the new profile definition. The display name can contain a maximum of 127 Unicode characters.
    Description | Type a description for the new profile definition. The description can contain a maximum of 127 Unicode characters.

  3. To close the dialog box, click OK.

  4. Click Finish.

The new profile definition appears in the list of available profile definitions in Commerce Server Manager. The new profile definition does not contain properties and is therefore not mapped to a data source. You must add properties to the new profile definition.

To add a custom attribute to a profile definition

  1. Expand Commerce Server Manager, expand Global Resources, expand Profiles, expand Profile Catalog, expand Profile Definitions, right-click the profile definition you want to add a custom attribute to, and then click Properties.

  2. In the Properties dialog box, on the Custom Attributes tab, click New to display the Custom Attribute dialog box.

  3. In the Custom Attribute dialog box, do the following:
    Use this | To do this
    Name | Type a programmatic name for the new attribute. The name can contain a maximum of 127 alphanumeric characters and the underscore (_) symbol. The name cannot contain spaces.
    Display Name | Type the name you want displayed for the attribute. The display name can contain a maximum of 127 Unicode characters.
    Description | Type a description for the attribute. The description can contain a maximum of 127 Unicode characters.
    Value | Type the value of the attribute.

  4. Click OK.

  5. To return to Commerce Server Manager, click OK.

The profile definition is saved with the new custom attribute.

See Also

About the Profiles Resource

Adding a New Data Source

Adding Properties to Profile Definitions

Adding Site Terms

Managing Profile Definitions


Adding Properties to Profile Definitions

You use the Profiles resource to add properties to a profile definition. Properties determine the data collected with the profile definition. For example, if you create an Address profile definition, you would add a property named "City" to it. (You can also add properties to a profile definition using the Profile Designer module in Commerce Server Business Desk. For information about using the Profile Designer module, see Business Desk Users.)

You can create property groups to organize the properties. For example, if you add 50 properties to a User profile definition that relate to four different categories, such as lifestyle, opinion, education, and preferences, you can create four property groups, one for each category, and arrange the properties that belong to each category in the appropriate property group. In the Profiles resource, you can choose to show or hide the properties for each property group.

The Profiles resource provides each property with attributes that store characteristics of the property, such as the property name (City) and the property type (string). In addition to the property attributes provided by the Profiles resource, you can also define custom attributes for properties. For example, you can create a custom attribute that controls how a property is used on a Web site.

To add a new property to a profile definition

To add a new property group to a profile definition

To add a custom attribute to a property

To add a new property to a profile definition

  1. Expand Commerce Server Manager, expand Global Resources, expand Profiles, expand Profile Catalog, expand Profile Definitions, and then click the profile definition that you want to add a property to.

  2. In the profile designer screen, in the Properties list, select the property group to which you want to associate the property you are adding, and then click Add.

  3. In the Add dialog box, select Add a new property, and then click OK.

  4. In the profile designer screen, in the Attributes section, do the following:
    Use this | To do this
    Name | Type the programmatic name of the property. The name can contain a maximum of 127 alphanumeric characters and the underscore (_) symbol. The name cannot contain spaces.
    Display Name | Type the name you want displayed in Business Desk. The display name can contain a maximum of 127 Unicode characters.
    Description | Type a description for the property. The description can contain a maximum of 127 Unicode characters.
    Type | Select the property type from the drop-down list. The default property type is string.
    Type Reference | Required for site term and profile types. Click the ellipsis [...] button to select the site term or profile you are adding to the property definition. This feature is available only if you have selected the site term or profile for the property type.

  5. In the profile designer screen, in the Advanced Attributes section, click Active to indicate that this property is available in Business Desk. Inactive properties are not displayed in Business Desk.

  6. In the Map to Data box, click the ellipsis [...] button to open the Data Source Picker dialog box.

  7. In the Data Source Picker dialog box, expand the data source that contains the data object that contains the data member with which you want to map the property.

  8. Expand the data object that contains the data member with which you want to map the property, select the data member, and then click OK.

  9. In the profile designer screen, in the Advanced Attributes section, do the following:
    Use this | To do this
    Key Type | Select a key type from the drop-down list. Each profile definition requires a property that is a primary key and a property that is a join key, or a property that is a dual key (both primary and join).
    Required | Specifies that this property is required on your Web site and in Business Desk. However, this attribute is not enforced by the Profiles resource. This attribute is read-only if you have selected a key type.
    Exported | Select this option to specify that this property is imported into the Data Warehouse. You can export only mapped properties. You cannot export properties that are multi-valued and of the type Boolean or properties of type binary, long string, or password.
    Defer Cache | Select this option to specify that this property will not be loaded initially when the profile is retrieved, but will be loaded when this particular property is accessed.
    Multi-valued | Select this option to enable the collection of multiple values that are associated with this property. This value is not available if you have selected a key type for the property.
    Searchable | Select this option to specify that this property is indexed in the underlying data store and is available for searching using the Find By function.
    RDN | Type the Relative Distinguished Name (RDN) for a directory store. Set this value if the property maps to an RDN attribute of an LDAP class in the underlying store.
    Hashing Key | This value is read-only. It indicates that this property will be used to distribute profile instances across multiple partitions.

  10. Click Apply.

  11. To save the profile definition, click [image] on the toolbar.

The profile definition is saved with the new property.

To add a new property group to a profile definition

  1. Expand Commerce Server Manager, expand Global Resources, expand Profiles, expand Profile Catalog, expand Profile Definitions, and then click the profile definition that you want to add a property group to.

  2. In the profile designer screen, click Add.

  3. In the Add dialog box, select the Add a new group option, and then click OK.

  4. In the profile designer screen, in the Attributes section, do the following:
    Use this | To do this
    Name | Type the programmatic name for the property group. The name can contain a maximum of 127 alphanumeric characters and the underscore (_) symbol. The name cannot contain spaces.
    Display Name | Type the name you want displayed in Business Desk. The display name can contain a maximum of 127 Unicode characters.
    Description | Type a description of the property. The description can contain a maximum of 127 Unicode characters.

  5. Click Apply.

  6. To save the profile definition, click [image] on the toolbar.

The profile definition is saved with the new property group. You can move properties into the group or add new properties to the group.

To add a custom attribute to a property

  1. Expand Commerce Server Manager, expand Global Resources, expand Profiles, expand Profile Catalog, expand Profile Definitions, and then click the profile definition that contains the property to which you want to add a custom attribute.

  2. In the profile designer screen, in the Properties list, select the property to which you want to add a custom attribute.

  3. In the profile designer screen, in the Custom Attributes section, click New.

  4. In the profile designer screen, in the Custom Attributes section, do the following:
    Use this | To do this
    Name | Type a programmatic name for the custom attribute. The name can contain a maximum of 127 alphanumeric characters and the underscore (_) symbol. The name cannot contain spaces.
    Display Name | Type the name you want displayed for the attribute. The display name can contain a maximum of 127 Unicode characters.
    Description | Type a description for the attribute. The description can contain a maximum of 127 Unicode characters.
    Value | Type the value of the attribute.

  5. Click Accept, and then click Apply.

  6. To save the profile definition, click Save on the toolbar.

The profile definition is saved with the custom attribute.

See Also

Profile Definitions

Adding a New Data Member

Adding a New Profile Definition

Adding a Profile Definition to a Profile Definition

Adding Site Terms


Validating Profile Definitions

You use the Profiles resource to verify that the data members you use to map profile definitions with are valid. Validating profile definitions ensures that the data collected with them on your Web site will be stored in existing database columns (or LDAP attributes).

Note

  • The validation routines attempt to write and then read back data for each property in the profile definition. The validation routines are not affected by constraints that may exist in the underlying data store. Therefore, these routines may attempt to write data that violates a constraint. In that case, you will receive a validation warning. You should carefully examine the warning descriptions to determine the validity of the profile.

To validate a profile definition

To validate all profile definitions in a site

To validate a profile definition

  1. Expand Commerce Server Manager, expand Global Resources, expand Profiles, expand Profile Catalog, expand Profile Definitions, right-click the profile definition that you want to validate, and then click Validate this Profile.

    If the profile definition is valid, the Valid Profile dialog box appears. Click OK.

    If the profile definition is not valid, the Invalid Profile dialog box appears.

  2. To continue the validation operation, click Yes, and then click OK to close the Invalid Profile dialog box.

    Or, to stop the validation operation, click No, and then click OK to close the Invalid Profile dialog box.

To validate all profile definitions in a site

  1. Expand Commerce Server Manager, expand Global Resources, expand Profiles, expand Profile Catalog, and then right-click Profile Definitions.

  2. Click Validate All Profiles.

    If all the profile definitions are valid, the Valid Profile dialog box appears. Click OK.

    If a profile definition is not valid, the Invalid Profile dialog appears.

  3. To continue the validation operation (skipping the invalid profile definition), click Yes, and then click OK to close the Invalid Profile dialog box.

    Or, to stop the validation operation, click No, and then click OK to close the Invalid Profile dialog box.

See Also

Adding a New Profile Definition

Adding a New Data Member

Adding Properties to Profile Definitions

Managing Profile Definitions

Managing Profile Properties


Adding a Profile Definition to a Profile Definition

You can use the Profiles resource to associate profiles. You can also perform this task using the Profile Designer module in Commerce Server Business Desk. For more information, see Adding a Profile Definition to a Profile Definition.

For example, you can add three properties to the User Object profile definition, and use them to reference three instances of the Address profile definition (for example, billing, shipping, and home address). This would allow you to use the Address profile definition to collect user address information on your Web site, while having the name of the address profile for the user stored in the user profile, so that you can present the data in the profiles together on your Web site and in reports.

To add a profile definition to a profile definition

  1. Expand Commerce Server Manager, expand Global Resources, expand Profiles, expand Profile Catalog, expand Profile Definitions, and then click the profile definition that you want to add a profile definition to.

  2. In the profile designer screen, in the Properties list, expand the property group that you want to add the new property to, and then click Add.

  3. In the Add -- Web Page Dialog dialog box, select Add a new property, and then click OK.

  4. In the profile designer screen, in the Attributes section, do the following:
    Use this | To do this
    Name | Type the programmatic name for the property. The name can contain a maximum of 127 alphanumeric characters and the underscore (_) symbol. The name cannot contain spaces.
    Display Name | Type the display name you want displayed in Business Desk. The display name can contain a maximum of 127 Unicode characters.
    Description | Type a description for the property. The description can contain a maximum of 127 Unicode characters.
    Type | Select Profile from the Type drop-down list.
    Type Reference | Click the ellipsis [...] button to open the Profile Selection dialog box. In the Select a Profile list, expand the Profile Catalog, and then select the profile definition you want to add to the property.

  5. Click OK, and then click Apply.

    The profile definition is assigned to the property.

  6. To save the profile definition, click Save on the toolbar.

The profile definition is saved with the property change.

See Also

Profile Definitions

Adding Properties to Profile Definitions

Adding Site Terms

Profile Objects

Profile Schema


Adding Site Terms

You can use the Profiles resource to add new site terms to Commerce Server 2000. You can also perform this task using the Site Terms Editor module in Commerce Server Business Desk. For more information, see Adding a Site Term.

When you add a new site term to Commerce Server, you define values, called terms, for the site term. You use site terms to list specific values for a profile property. After you create a site term, you can assign it as the value of a profile property. For example, you create a Favorite color site term with the values blue, green, and purple. Then, you define a "favorite color" profile property of the type site term, and assign the Favorite color site term to it. When users select a color for the favorite color property, they are limited to the choices listed in the Favorite color site term. You use the site terms editor screen in the Profiles resource to add new site terms.

You must have access to the log file in the Profiles folder before you can save changes to site terms. The business manager must also have access to the log file in the Profiles folder to be able to save any changes made in the Site Terms Editor module.

You can create site term groups to help you organize site terms in the site terms editor screen. For example, in addition to Favorite color, you can create the following site terms with corresponding values and make them a site term group containing user preferences:

  • Brand (name brand, generic)

  • Quality (lowest price, best quality)

  • Purchase (online, catalog, in store)

To add a site term

To add a site term group

To add a site term

  1. Expand Commerce Server Manager, expand Global Resources, expand Profiles, expand Profile Catalog, and then click Site Terms.

  2. In the site terms editor screen, in the Site term structure list, select the site term group in which you want to create the new site term, and then click Add.

  3. In the Add dialog box, select the Add new site term option, and then click OK.

  4. In the site terms editor screen, in the Site Term Attributes section, do the following:
    Use this | To do this
    Name | Type the programmatic name for the site term. The name can contain a maximum of 127 alphanumeric characters and the underscore (_) symbol. The name cannot contain spaces.
    Display Name | Type the name you want displayed for the site term. The display name can contain a maximum of 127 Unicode characters.
    Description | Type a description for the site term. The description can contain a maximum of 127 Unicode characters.

  5. To add a value to the site term, in the Terms section, click New, and then do the following:
    Use this | To do this
    Term Name | Type the programmatic name for the first term. The name can contain a maximum of 127 alphanumeric characters and the underscore (_) symbol. The name cannot contain spaces.
    Display Name | Type the name you want displayed for the term. The display name can contain a maximum of 127 Unicode characters.

  6. To accept the term, click Accept.

  7. To add an additional term to the site term, click New, type the term name and display name for the new term, click Accept, and then click Apply.

  8. To save the site terms, click Save on the toolbar.

The terms are saved with the new site term you created.

To add a site term group

  1. Expand Commerce Server Manager, expand Global Resources, expand Profiles, expand Profile Catalog, and then click Site Terms.

  2. In the site terms editor screen, in the Site term structure list, click Add.

  3. In the Add dialog box, select Add new group, and then click OK.

  4. In the site terms editor screen, in the Site Term Attributes section, do the following:
    Use this | To do this
    Name | Type the programmatic name for the site term group. The name can contain a maximum of 127 alphanumeric characters and the underscore (_) symbol. The name cannot contain spaces.
    Display Name | Type the name you want displayed for the site term group. The display name can contain a maximum of 127 Unicode characters.
    Description | Type a description for the site term group. The description can contain a maximum of 127 Unicode characters.

  5. Click Apply.

  6. To save the site terms group, click Save on the toolbar.

See Also

About the Profiles Resource

Adding a Site Term to a Profile Definition

Managing Site Terms


Adding a Site Term to a Profile Definition

You can use the Profiles resource to add a site term to a profile definition. You can also perform this task using the Profile Designer module in Commerce Server Business Desk. For more information, see Adding a Site Term to a Profile Definition.

When you assign a site term to a profile property, users on your Web site get a drop-down list of the site term values for the property. The selection a user makes from the site term drop-down list on your Web site is stored in the profile for that user as a type string.

To add a site term to a profile definition

  1. Expand Commerce Server Manager, expand Global Resources, expand Profiles, expand Profile Catalog, expand Profile Definitions, and then click the profile definition that you want to add a site term to.

  2. In the profile designer screen, in the Properties list, expand the property group that contains the property you want, and then select the property you want to assign the site term to.

  3. In the profile designer screen, in the Attributes section, select Site Term from the Type drop-down list.

  4. In the Type Reference box, click the ellipsis [...] button.

  5. In the Site Term Selection dialog box, in the Select a Site Term list, expand the site term group that contains the site term you want to assign to the property, and then select the site term.

  6. Click OK, and then click Apply.

    The site term is assigned to the property.

  7. To save the profile definition, click Save on the toolbar.

The profile definition is saved with the property change.

See Also

About the Profiles Resource

Adding Properties to Profile Definitions

Adding Site Terms

Managing Site Terms


Example: Creating a Profile Definition with Two Data Sources

One advantage to using Active Directory to store user profile data is that it provides more secure and specific user authentication. It is best to store only non-volatile data in Active Directory and to store frequently updated data in SQL Server.

The example in this section provides a scenario for creating a user profile definition that stores data in both a SQL Server database and an Active Directory database. This example is meant only to describe the process; it does not describe an actual profile you should use. You should design your profile definitions based on your business requirements.

This example presumes that you have installed and configured Active Directory domain controllers for your Commerce Server 2000 site.

For information about planning for Active Directory, see Planning for Active Directory Integration.

This section contains:

  • Step 1: Create the ProfileService_ADSource Data Source

  • Step 2: Add the AD User Object

  • Step 3: Add Data Members to the AD User Object

  • Step 4: Create the AD-SQL User Profile Definition

  • Step 5: Add Property Groups to AD-SQL User

  • Step 6: Add SQL Server Properties to AD-SQL User


Step 1: Create the ProfileService_ADSource Data Source

To add a new LDAPv3-Compliant Source data source

  1. Expand Commerce Server Manager, expand Global Resources, expand Profiles, expand Profile Catalog, right-click Data Sources, and then click New Data Source.

  2. In the New Data Source dialog box, do the following:
    Use this | To do this
    Name | Type UPM_ADSource.
    Display Name | Type ProfileService_ADSource.
    Description | Type Active Directory data source.

    The following figure shows the New Data Source dialog box.

    New Data Source dialog box

    Click the illustration to enlarge or reduce.

  3. Click Next.

  4. In the Data Source dialog box, in the Source Type drop-down list, select LDAPv3-Compliant Source, and then click Next.

  5. In the Partitions dialog box, make sure the Partitioned Data Source check box is not selected, and then click Add.

  6. In the Partition dialog box, click Edit.

  7. In the LDAP Connection String dialog box, do the following:
    Use this | To do this
    Server | Type the name of the Active Directory domain controller. In this example, the name is MSCS01.
    Port | Leave blank (unless you are using a value other than 389).

  8. Click OK.

  9. In the Partition dialog box, make sure that the Default Partition check box is not selected. The following figure shows the Partition dialog box.
    Partition dialog box

    Click the illustration to enlarge or reduce.

  10. In the Partition dialog box, do the following:
    Use this | To do this
    User Name | Type your Microsoft Windows domain and user name for the Active Directory domain. Type it in the form domain\username.
    Password | Type your Windows domain password.

  11. Click Next.

  12. In the System Attributes dialog box, do the following:
    Use this | To do this
    Parent URL | Type the location on the Active Directory server where you want your Active Directory data to be stored relative to the root.
    Domain Name | Type the domain name of the Active Directory server.

Note

  • Do not change the default settings for the other options in the dialog box.

  • However, you might want to select the Use the same credentials for all users option. This option forces the Profiles resource to use the credentials you entered in Step 6 whenever it communicates with the Active Directory server. If you do not select this option, the Profiles resource uses the credentials of the process in which it is currently running.

    The following figure shows the System Attributes dialog box.

    System Attributes dialog box

    Click the illustration to enlarge or reduce.

  13. Click Next.

  14. In the Custom Attributes dialog box, click Finish.

  15. In the Partitions dialog box, click Finish.

The ProfileService_ADStore partition appears as a new node under Data Sources in Commerce Server Manager.


Step 2: Add the AD User Object

You create a profile data object to map a profile property to the Active Directory user class.

To add a new data object

  1. Expand Commerce Server Manager, expand Global Resources, expand Profiles, expand Profile Catalog, expand Data Sources, expand the ProfileService_ADSource data source you created in the previous procedure, right-click Data Objects, and then click New Data Object.

  2. In the New Data Object dialog box, do the following:
    Use this | To do this
    Object Name | Select user. This is the Active Directory user class.
    Display Name | Type AD User Object.

    The following figure shows the New Data Object dialog box.

    New Data Object dialog box

    Click the illustration to enlarge or reduce.

  3. Click OK.

The AD User Object data object is added to the ProfileService_ADSource data source.


Step 3: Add Data Members to the AD User Object

You create a profile data member to map a profile property attribute to a column in a table in the database you mapped the data source to. In this example, we will add nine data members to the AD User Object data object created in the previous procedure. These members are for the user name, user password, and common name.

To add data members

  1. Expand Commerce Server Manager, expand Global Resources, expand Profiles, expand Profile Catalog, expand Data Sources, expand ProfileService_ADSource, right-click AD User Object, and then click New Data Member.

  2. In the New Data Member dialog box, do the following:
    Use this | To do this
    Member Name | Select cn.
    Display Name | Type Common Name.

    The following figure shows the New Data Member dialog box.

    New Data Member dialog box

    Click the illustration to enlarge or reduce.

  3. Click Add.

    By default, the cn data member is marked as Required, Indexed, and Primary key.

  4. Repeat this procedure to add the following data members:
    Member name | Display name | Type
    GivenName | First Name | String
    Initials | Initial | String
    sn | Last Name | String
    StreetAddress | Street Address | String
    l | City | String
    St | State/Province | String
    PostalCode | Postal Code | String
    co | Country | String

  5. Click Finished.

When you add these data members, your screen should look like the following figure.

Click the illustration to enlarge or reduce.


Step 4: Create the AD-SQL User Profile Definition

You use the AD User Object data object to create your custom profile definition. This profile definition will collect user profile information. Most of the properties will be mapped to a SQL Server database. The user name and password will be mapped to Active Directory.

You create this multiple-source profile by selecting the properties you want and mapping them to data members from different data sources.

To create a new profile definition

  1. Expand Commerce Server Manager, expand Global Resources, expand Profiles, expand Profile Catalog, expand Data Sources, expand ProfileService_ADSource, expand Data Objects, right-click AD User Object, point to New, and then click New Profile.

  2. In the New Profile Definition dialog box, do the following:
    Use this | To do this
    Name | Type AD_SQL_User.
    Display Name | Type AD-SQL User.
    Description | Type User profile definition using AD and SQL sources.

    The following figure shows the New Profile Definition dialog box.

    New Profile Definition dialog box

    Click the illustration to enlarge or reduce.

  3. Click Next.

  4. In the Custom Attributes dialog box, click Finish. (No custom attributes are created for this example.)

The new profile definition appears in the list of available profile definitions in Commerce Server Manager.


Step 5: Add Property Groups to AD-SQL User

To make your profile definition easier to read, you can create separate groups for your Active Directory and SQL Server properties. Before you add the SQL Server properties to your AD-SQL User profile definition, create the data groups.

To add data groups to a profile

  1. Expand Commerce Server Manager, expand Global Resources, expand Profiles, expand Profile Catalog, expand Profile Definitions, and then click AD-SQL User. The profile designer screen appears in the right pane.
    AD-SQL User Profile definition

    Click the illustration to enlarge or reduce.

  2. Click Add.

  3. In the Add -- Web Page dialog box, select Add a new group, and then click OK.

  4. In the Attributes section, do the following:
    Use this | To do this
    Name | Type ADGroup.
    Display Name | Type Active Directory.

    The following figure shows the Attributes section.

    AD-SQL User Profile definition with new property group

    Click the illustration to enlarge or reduce.

  5. Click Apply.

  6. In the Properties list, select Active Directory, the group you just created, and then click the Up Arrow button at the bottom of the dialog box. Keep clicking it until Active Directory is moved to the top of the Properties list, above all of the properties.

  7. Click the directional arrow to the left of Active Directory so that it points down. This expands the node, and prepares the group to accept properties.

  8. Click the first property underneath Active Directory. If you followed the preceding procedures exactly, this will be the Common Name property.

  9. Click the Up Arrow button at the bottom of the dialog box. The property name appears indented under Active Directory. This places the property in the Active Directory group.

  10. For each of the remaining properties, select its name and click the Up Arrow button. Your Properties list should look similar to the following figure when all of the properties are placed in the group.
    AD-SQL User Profile definition advanced attributes

    Click the illustration to enlarge or reduce.

  11. To add the SQL Server group to the property definition, click the Add button.

  12. In the Attributes section, do the following:
    Use this | To do this
    Name | Type SQLGroup.
    Display Name | Type SQL Server.

    The Attributes section should look like the following figure.

    AD-SQL User Profile definition with properties

    Click the illustration to enlarge or reduce.

  13. Click Apply.

  14. To move the SQL Server group name to the left, click the Down Arrow at the bottom of the dialog box.

The properties you added are organized in the new property groups.


Step 6: Add SQL Server Properties to AD-SQL User

You have created a profile definition named AD-SQL User that has two property groups: Active Directory and SQL Server. You have already included the Active Directory properties. Next, you need to add the SQL Server properties.

To add SQL Server User Object properties to the AD-SQL User profile definition

  1. Expand Commerce Server Manager, expand Global Resources, expand Profiles, expand Profile Catalog, expand Profile Definitions, and then click AD-SQL User.

  2. In the profile definition screen, in the Properties list, click Common Name. The property attributes appear to the right.

  3. In the Advanced Attributes section, do the following:
    Use this | To do this
    Key Type | Select Dual (Primary and Join). When using multiple data sources in a profile definition, it is necessary to create a join key that maps to both sources.
    Map to Data | Click the ellipsis [...] button. In the Data Source Picker dialog box, expand ProfileService_ADSource, and then expand AD-SQL User. Select ProfileService_SQLSource, and then select User Object.

  4. Hold down the CTRL key, and select both u_logon_name (located under User Object), and cn (located under AD-SQL User), and then click OK to close the Data Source Picker dialog box.

    Both properties appear in the Map to Data box.

  5. In the Advanced Attributes section, select the RDN box, and then click Apply.

    Here, the join key properties are designated as the Relative Distinguished Name (RDN) for the profile. The RDN must exist to create a valid profile that is mapped to an LDAPv3 source, such as Active Directory. (This is not required for OLE DB sources, such as SQL Server.)

  6. In the Properties list, click the directional arrow to the left of SQL Server, and then click Add.

  7. In the Add -- Web Page dialog box, select Add a new property, and then click OK.

  8. In the Properties list, select New Property 1.

    Add the properties in the following New Properties table to the AD-SQL User profile definition.

    Name | Display name | Type | Map to data
    u_user_security_password | Password | String | u_user_security_password
    i_account_status | Account Status | Number | i_account_status
    u_user_catalog_set | Catalog Set | String | u_user_catalog_set
    d_data_registered | Date Registered | Date/ Time | d_date_registered
    i_partner_desk_role | Partner Service Role | Number | i_partner_desk_role
    d_date_last_changed | Date Last Changed | Date/ Time | d_date_last_changed

  9. In the Attributes section, do the following:
    Use this | To do this
    Name | Type the programmatic name for the property from the Name column in the previous table.
    Display Name | Type the display name for the property from the Display name column in the previous table.
    Type | Select from the drop-down list the property type for the property from the Type column in the previous table.

  10. In the Advanced Attributes section, click the Map to Data ellipsis [...] button. Navigate to SQL Server User Object, and then select the data member for the property from the Map to data column in the previous table.

  11. To apply the changes you made to the property, click Apply.

  12. Repeat Steps 7 through 12 until you have added all of the properties in the New Properties table. The properties designer screen should look like the following figure.
    AD-SQL User Profile definition with new property group

    Click the illustration to enlarge or reduce.

  13. To save the profile definition, click [image] on the toolbar.

If you used the AD-SQL User profile definition on your Web site, it would store data in both a SQL Server database and an Active Directory database.

See Also

About the Profiles Resource

Adding a New Data Source

Adding a New Profile Definition

Managing Data Sources

Managing Profile Definitions


Managing Data Sources

You use the Profiles resource to modify the data sources you created. For example, you make changes in the data store that your profile properties map to, and you need to edit or delete obsolete data objects and data members. Or, you create a new data source and you want to delete the old one. You can change and delete data sources, data objects, and data members.

Consider the following restrictions on modifying your data sources:

  • You can only add partitions to a data source that has never been partitioned. You must add partitions to a source before you use it to store data. If you partition a source that contains data, the existing data will be lost.

  • You cannot delete data source partitions, but you can modify them. You must be careful when you modify the partitions of a data source that contains data because changes can result in data loss or corruption.

  • When you delete a data source, you cannot recover it. All of the data objects and data members associated with the data source are also deleted. You must re-map the profile definitions mapped with the deleted data members to the data storage with existing data members.

  • When you delete a data object, you cannot recover it. All of the data members associated with the deleted data object are also deleted. You must re-map the profile definitions mapped with the deleted data members to the data storage with existing data members.

  • When you delete a data member, you cannot recover it. You must re-map the profile definitions mapped with the deleted data member to the data storage with an existing data member.

To change the properties of a data source

To delete a data source

To change the display name and description of a data object

To delete a data object

To change the display name and description of a data member

To delete a data member

To change the properties of a data source

  1. Expand Commerce Server Manager, expand Global Resources, expand Profiles, expand Profile Catalog, expand Data Sources, right-click the data source you want to change, and then click Properties.

  2. In the <data source> Properties dialog box, on the General tab, do the following:
    Use this | To do this
    Display Name | Edit the name for the data source. The display name can contain a maximum of 127 Unicode characters.
    Description | Edit the description for the data source. The description can contain a maximum of 127 Unicode characters.

  3. To save your changes and return to Commerce Server Manager, click OK.

The data source is saved with your changes. You can change the connection string of an existing partition, or add a new partition that is the same type as the data source (LDAP or OLE DB). To add a new partition or edit an existing partition for an OLE DB-ANSI Provider, see To add a new SQL Server data source. To add a new partition or edit an existing partition for an LDAPv3-Compliant Source, see To add a new LDAPv3-Compliant Source data source.

To delete a data source

  1. Expand Commerce Server Manager, expand Global Resources, expand Profiles, expand Profile Catalog, expand Data Sources, right-click the data source you want to delete, and then click Delete.

  2. In the Delete Data Source confirmation dialog box, click Yes.

The data source, all of its data objects, and all of its data members are deleted.

To change the display name and description of a data object

  1. Expand Commerce Server Manager, expand Global Resources, expand Profiles, expand Profile Catalog, expand Data Sources, expand the data source that contains the data object you want to change, expand Data Objects, right-click the data object you want to change, and then click Properties.

  2. In the <data object> Properties dialog box, on the Identity tab, do the following:
    Use this | To do this
    Display Name | Edit the name for the data object. The display name can contain a maximum of 127 Unicode characters.
    Description | Edit the description for the data object. The description can contain a maximum of 127 Unicode characters.

  3. Click OK.

The display name and description of the data object are changed.

Note

  • You can change the display name of a data object; however, you cannot change the programmatic name of a data object.

To delete a data object

  1. Expand Commerce Server Manager, expand Global Resources, expand Profiles, expand Profile Catalog, expand Data Sources, expand the data source that contains the data object you want to delete, expand Data Objects, right-click the data object you want to delete, and then click Delete.

  2. In the Delete Data Object confirmation dialog box, click Yes.

The data object is deleted from the data source.

Caution

  • You cannot recover a data object after you delete it.

To change the display name and description of a data member

  1. Expand Commerce Server Manager, expand Global Resources, expand Profiles, expand Profile Catalog, expand Data Sources, expand the data source that contains the data object that contains the data member you want to change, expand Data Objects, and then click the data object that contains the data member you want to change.

  2. In the data member list, right-click the data member you want to change, and then click Properties.

  3. In the <data member> Properties dialog box, on the General tab, do the following:
    Use this | To do this
    Display Name | Edit the name for the data member. The display name can contain a maximum of 127 Unicode characters.
    Description | Edit the description for the data member. The description can contain a maximum of 127 Unicode characters.

  4. Click OK.

Note

  • You can change the display name of a data member; however, you cannot change the programmatic name of a data member.

To delete a data member

  1. Expand Commerce Server Manager, expand Global Resources, expand Profiles, expand Profile Catalog, expand Data Sources, expand the data source that contains the data object that contains the data member you want to delete, expand Data Objects, and then click the data object that contains the data member you want to delete.

  2. In the data member list, right-click the data member you want to delete, and then click Delete.

  3. In the Delete Data Member confirmation dialog box, click Yes.

The data member is deleted from the data source.

Caution

  • You cannot recover a data member after you delete it.

See Also

About the Profiles Resource

Adding a New Data Source

Adding a New Data Object

Adding a New Data Member

Example: Creating a Profile Definition with Two Data Sources


Managing Profile Definitions

You can use the Profiles resource to change the display name and description for a profile definition and to add custom attributes to a profile definition. To create a new profile definition, you can copy an existing profile definition and use the profile designer screen to change the name and attributes of the new profile definition.

Commerce Server 2000 provides you with several profile definitions when you unpack the Blank Solution Site that you can copy to create new profile definitions to suit your needs. You can also delete a profile definition that no longer meets your needs, and delete a custom attribute from a profile definition. You cannot recover a custom attribute after you have deleted it; if you delete a custom attribute by mistake, you must recreate it.

To change a profile definition

To copy a profile definition

To delete a profile definition

To delete a custom attribute from a profile definition

To change a profile definition

  1. Expand Commerce Server Manager, expand Global Resources, expand Profiles, expand Profile Catalog, expand Profile Definitions, right-click the profile definition you want to modify, and then click Properties.

  2. In the Properties dialog box, on the General tab, do the following:
    Use this | To do this
    Display Name | Change the name for the profile definition. The display name can contain a maximum of 127 Unicode characters.
    Description | Change the description for the profile definition. The description can contain a maximum of 127 Unicode characters.

  3. In the Properties dialog box, on the Custom Attributes tab, do the following:
    Use this | To do this
    New | Click to open the Custom Attribute dialog box and add a new custom attribute.
    Edit | Click to open the Custom Attribute dialog box and edit the specified custom attribute.
    Delete | Click to delete the selected custom attribute.

  4. In the Custom Attributes dialog box, do the following:
    Use this | To do this
    Display Name | Type the name you want displayed or change the name for the attribute. The display name can contain a maximum of 127 Unicode characters.
    Description | Type or change the description for the attribute. The description can contain a maximum of 127 Unicode characters.
    Value | Type or change the value of the attribute.

Note

  • You can change the display name of a profile definition; however, you cannot change the programmatic name of a profile definition.
  5. To save the changes and return to the Properties dialog box, click OK.

  6. To save your changes and return to Commerce Server Manager, click Apply, and then click OK.

The profile definition is saved with the changes.

To copy a profile definition

  1. Expand Commerce Server Manager, expand Global Resources, expand Profiles, expand Profile Catalog, expand Profile Definitions, right-click the profile you want to copy, and then click Make a Copy of This Profile.

  2. In the Copy Profile Definition dialog box, do the following:
    Use this | To do this
    Name | Type a programmatic name for the profile definition. The name can contain a maximum of 127 alphanumeric characters and the underscore (_) symbol. The name cannot contain spaces.
    Display Name | Type the name you want displayed for the profile definition. The display name can contain a maximum of 127 Unicode characters.
    Description | Type a description for the profile definition. The description can contain a maximum of 127 Unicode characters.

  3. Click Next.

  4. In the Custom Attributes dialog box, click New.

  5. In the Custom Attribute dialog box, do the following:
    Use this | To do this
    Name | Type a programmatic name for the attribute. The name can contain a maximum of 127 alphanumeric characters and the underscore (_) symbol. The name cannot contain spaces.
    Display Name | Type the name you want displayed for the attribute. The display name can contain a maximum of 127 Unicode characters.
    Description | Type a description for the attribute. The description can contain a maximum of 127 Unicode characters.
    Value | Type the value of the attribute.

  6. To save the profile definition, click OK.

  7. To save the profile definition and return to Commerce Server Manager, click Finish.

The new profile definition is saved.

To delete a profile definition

  1. Expand Commerce Server Manager, expand Global Resources, expand Profiles, expand Profile Catalog, expand Profile Definitions, right-click the profile definition you want to delete, and then click Delete.

  2. In the Delete Profile confirmation dialog box, click Yes.

The profile definition is deleted from the Profiles resource.

Caution

  • If you delete a profile definition by mistake, you must recreate it. You cannot recover a profile definition after you have deleted it.

To delete a custom attribute from a profile definition

  1. Expand Commerce Server Manager, expand Global Resources, expand Profiles, expand Profile Catalog, expand Profile Definitions, right-click the profile definition from which you want to delete a custom attribute, and then click Properties.

  2. In the Properties dialog box, on the Custom Attributes tab, select the attribute you want to delete, and then click Delete.

The custom attribute is deleted from the profile definition.

See Also

About the Profiles Resource

Adding a New Profile Definition


Managing Profile Properties

You can use the Profiles resource to change profile properties to update the data you want to collect from your Web site. For example, you create a profile definition with a property that you use to collect data about the states in which the users who visit your Web site live. When you view the data collected with that profile property, you discover that a property of the type string is not the best way to collect useful location data from your users. You use the profile designer screen to modify the attributes of the property so that it collects data that is more useful.

You can delete properties and property groups if you do not need them in a profile definition. For example, you add seven properties to a profile definition, and you find that you need only six of them on your Web site. When you delete a property group, all properties in that group are also deleted.

You can move properties and property groups up and down in the Properties list to improve organization. For example, you added three property groups to a property definition. You can move the existing properties up and down in the Properties list until they are in the property group you created for them.

You can edit or delete any custom attribute from a property. You can edit a custom attribute if you need to adjust the display name, description, or value of the attribute. If you delete a custom attribute by mistake, you must recreate it. You cannot recover a custom attribute after you delete it.

To change a profile property

To organize profile properties

To delete a property from a profile definition

To change a custom attribute of a profile property

To delete a custom attribute from a profile property

To change a profile property

  1. Expand Commerce Server Manager, expand Global Resources, expand Profiles, expand Profile Catalog, expand Profile Definitions, and then click the profile definition that contains the property you want to change.

  2. In the Properties list, expand the property group that contains the property you want to change, and then click the property you want to change.

    Or, click the property group you want to change.

  3. In the profile designer screen, in the Attributes section, do the following:
    Use this | To do this
    Display Name | Edit the name you want displayed in Commerce Server Business Desk. The display name can contain a maximum of 127 Unicode characters.
    Description | Edit the description for the property. The description can contain a maximum of 127 Unicode characters.
    Type | Select the property type. The default property type is string. The property type of this attribute must be the same type as the data member this attribute is mapped to.
    Type Reference | Click the ellipsis [...] button to select the site term or profile you are adding to the property definition. This feature is only available if you have selected the type site term or profile.

  4. In the profile designer screen, in the Advanced Attributes section, click Active if you want this property to be available in Business Desk. Inactive properties are not displayed in Business Desk.

  5. In the Map to Data box, click the ellipsis [...] button to open the Data Source Picker dialog box, and then select the data member the property maps to.

  6. In the Data Source Picker dialog box, expand the data source that contains the data object that contains the data member with which you want to map the property.

  7. Expand the data object that contains the data member with which you want to map the property, and then select the data member.

  8. Click OK.

  9. In the profile designer screen, in the Advanced Attributes section, do the following:
    Use this | To do this
    Key Type | Select a key type from the drop-down list. Each profile definition requires a property that is a primary key and a property that is a join key, or a property that is a dual key (both primary and join).
    Required | Specifies that this property is required on your Web site and in Business Desk. However, this attribute is not enforced by the Profiles resource. This attribute is read-only if you have selected a key type.
    Exported | Select this option to specify that this property will be imported into the Commerce Server Data Warehouse. You can export only mapped properties. You cannot export properties that are multi-valued and of the type Boolean or properties of type binary, long string, or password.
    Defer Cache | Select this option to specify that this property will not be loaded initially when the profile is retrieved, but will be loaded when this property is accessed.
    Multi-valued | Select this option to enable the collection of multiple values that are associated with this property. This value is not available if you have selected a key type for the property.
    Searchable | Select this option to designate that this property is indexed in the underlying data store and is available for searching through the Find By function.
    RDN | Type the Relative Distinguished Name (RDN) for a directory store. Set this value if this property maps to an RDN attribute of an LDAP class in the underlying store.
    Hashing Key | Select this option to indicate that this property will be used to distribute profile instances across multiple data source partitions. This property is read-only for non-partitioned data sources. You must query on this key to retrieve profiles.

  10. Click Apply.

  11. To save the profile definition, click [image] on the toolbar.

The profile definition is saved with the changes.

To organize profile properties

  1. Expand Commerce Server Manager, expand Global Resources, expand Profiles, expand Profile Catalog, expand Profile Definitions, and then click the profile definition that contains the properties you want to organize.

  2. In the Properties list, select the property or property group you want to move, and then use the Up and Down Arrow buttons to move the property or property group up or down in the list.

  3. To save the profile definition, click Save on the toolbar.

The profile definition is saved with the changes you made to the order of the property groups and properties.

To delete a property from a profile definition

  1. Expand Commerce Server Manager, expand Global Resources, expand Profiles, expand Profile Catalog, expand Profile Definitions, and then click the profile definition that you want to delete a property from.

  2. In the Properties list, select the property or property group you want to delete, and then click Remove.

  3. In the Delete confirmation dialog box, click OK.

  4. To save the profile definition, click on the toolbar.

The profile definition is saved. It no longer contains the property or property group that you deleted.

To change a custom attribute of a profile property

  1. Expand Commerce Server Manager, expand Global Resources, expand Profiles, expand Profile Catalog, expand Profile Definitions, and then click the profile definition that contains the property in which you want to change a custom attribute.

  2. In the Properties list, select the property that contains the custom attribute you want to change.

  3. In the profile designer screen, in the Custom Attributes section, click Edit.

  4. In the profile designer screen, in the Custom Attributes section, do the following:
    Use this | To do this
    Name | Edit the programmatic name for the attribute. The name can contain a maximum of 127 alphanumeric characters and the underscore (_) symbol. The name cannot contain spaces.
    Display Name | Edit the name you want displayed for the attribute. The display name can contain a maximum of 127 Unicode characters.
    Description | Edit the description for the attribute. The description can contain a maximum of 127 Unicode characters.
    Value | Edit the value of the attribute.

  5. Click Accept, and then click Apply.

  6. To save the profile definition, click Save on the toolbar.

The profile definition is saved with the changes.

To delete a custom attribute from a profile property

  1. Expand Commerce Server Manager, expand Global Resources, expand Profiles, expand Profile Catalog, expand Profile Definitions, and then click the profile definition that contains the property you want to delete a custom attribute from.

  2. In the Properties list, select the property that contains the custom attribute you want to delete.

  3. In the profile designerscreen, in the Custom Attributes section, select the custom attribute you want to delete, and then click Remove.

    The custom attribute is deleted from the profile property.

  4. Click Apply.

  5. To save the profile definition, click Save on the toolbar.

The profile definition is saved with the changes.

Caution

  • You cannot recover a custom attribute after you delete it.

See Also

About the Profiles Resource

Adding Properties to Profile Definitions


Managing Site Terms

You can use the Profiles resource to change and delete site terms to better suit your needs. For example, you can create a Favorite color site term and then change the colors it lists when the seasons change to better match your inventory.

To change a site term

To delete a site term

To change a site term

  1. Expand Commerce Server Manager, expand Global Resources, expand Profiles, expand Profile Catalog, and then click Site Terms.

  2. In the Site term structure list, expand the site term group that contains the site term you want to change.

  3. In the profile designer screen, modify the attributes and terms of the site term as needed, click Accept, and then click Apply.

  4. To save the site term, click Save on the toolbar.

The site term is saved with your changes.

To delete a site term

  1. Expand Commerce Server Manager, expand Global Resources, expand Profiles, expand Profile Catalog, and then click Site Terms.

  2. In the Site term structure list, expand the site term group that contains the site term you want to delete, select the site term, and then click Remove.

  3. In the Delete confirmation dialog box, click OK.

    The site term is deleted.

  4. Click Accept, and then click Apply.

  5. To save the changes, click Save on the toolbar.

The site term is saved with your changes.

See Also

About the Profiles Resource

Adding Site Terms

Adding a Site Term to a Profile Definition


Using BizTalk Server and Commerce Server

By integrating Microsoft BizTalk Server 2000 with your Microsoft Commerce Server 2000 installation, you can contract with vendors to receive catalogs of their products, and then fill orders for products that are sold on your site. Although it is not required that both you and your vendors install BizTalk Server, this section explains how to set up BizTalk Server systems for both you and your vendors.

It is recommended that you install Commerce Server and BizTalk Server on the same computer. However, you can install BizTalk Server on a separate computer using, for example, Message Queuing.

This section contains:

  • About BizTalk Server. Describes the components of Commerce Server that work with BizTalk Server and provides an overview of steps for orders and catalog exchange.

  • Configuring Commerce Server to Work with BizTalk Server. Explains how to configure Commerce Server to integrate it with BizTalk Server.

  • Setting Up the Source Server. Explains how to set up source and sender organizations for catalog or purchase order exchange.

  • Setting Up the Destination Server. Explains how to configure the destination and receiver organizations on BizTalk Server.

  • Setting Up Your Catalogs for BizTalk Server. Explains how to configure BizTalk Server for catalog exchange.

For more information about integrating BizTalk Server and Commerce Server, see Integrating with BizTalk Server. In addition, see the Microsoft BizTalk Server 2000 documentation and the Commerce Server 2000 Resource Kit.

For programming samples, see "Designing Solutions with BizTalk Server 2000" in the BizTalk Server Software Development Kit (SDK). For example, the SDK includes samples for dividing orders by vendor, transforming orders in Extensible Markup Language (XML), and using a BizTalk Server component to send orders to BizTalk Server.


About BizTalk Server

BizTalk Server 2000 provides a gateway for sending business documents between your company and your trading partners (also known as vendors). For example, if your company uses BizTalk Server, you can trade catalogs, orders, documents, and other electronic forms with your trading partners. BizTalk Server manages the data translation, encryption, digital signatures, and document tracking services for many different transport mechanisms.

You can use BizTalk Server and Commerce Server together to process orders that users place on your Commerce Server Web site. For example, assume you are selling computer hardware on your site. Your company manufactures some of this hardware, and some of it is supplied to you by trading partners. Using BizTalk Server, you can create a trading agreement for each trading partner who supplies the hardware that you sell on your site. When a user visits your site and places an order for one of the products supplied by a trading partner, Commerce Server processes the order and sends it to BizTalk Server, and then BizTalk Server sends the order to the trading partner to be filled.

Catalogs for Multiple Vendors

Vendor ID

Using BizTalk Server to Exchange Catalogs

Sending Orders to BizTalk Server

Processing Received Orders

Catalogs for Multiple Vendors

Before you can use BizTalk Server to transmit orders to your trading partners, you must first organize the catalogs of those trading partners whose products will appear on your site. Each of your trading partners can send you one or more catalogs of their products. Depending on how you set up your site, you can present these catalogs on your Web site as one catalog, or as multiple catalogs. Maintaining multiple catalogs is helpful when, for example, you are targeting several groups of users with different catalog content, such as senior operations management and hobbyists.

Vendors send you their catalogs using e-mail or BizTalk Server, and then you import the catalog to your Commerce Server Catalogs database using the Catalog Editor module in Commerce Server Business Desk. For information about importing catalogs, see Importing a Catalog.

Vendor ID

When you set up an agreement with a vendor, the vendor ID is automatically made available to Commerce Server. The vendor ID is the organization name that you specify for the vendor when you create a destination organization for the source server. For more information, see Creating Source and Destination Organizations on the Source Server.

Commerce Server displays the vendor ID in Business Desk. It displays those trading partners (organizations) that support the same document type as your organization, and thus have compatible document routing. You can then use Business Desk to associate the vendor ID with the catalog.

More than one catalog can be associated with a given vendor. You can also specify a vendor at the product level; however, if you do this you must also customize _additem.asp page (if you are developing with the Retail Solution Site).

If you name a vendor "Default," Commerce Server recognizes your own site as the vendor. For instructions about adding the vendor ID to a catalog, see Setting Up Your Catalogs for BizTalk Server.

Note

  • When a user orders an item from your Web site, the item must exist in the catalog of the destination organization. If the destination organization does not have the item in its catalog, BizTalk Server will not be able to process the purchase order on the destination server. It will write an error message to the event log on the destination server.

Using BizTalk Server to Exchange Catalogs

Using BizTalk Server you can exchange catalogs that are used by Commerce Server with your trading partners. After a catalog is converted to an Extensible Markup Language (XML) document, it is processed by BizTalk Server to save the XML catalog file in a shared folder on the destination computer on which Commerce Server is installed. If the destination computer is on a LAN, then BizTalk Server does not need to be installed on the destination computer. If you are sending the catalog using HTTP, then BizTalk Server must be installed on the destination computer.

After an XML catalog file is saved on the destination computer, you use Business Desk to import the catalog from the shared folder on the destination computer and then publish the catalog to the Web site. You can edit the newly imported catalog, if necessary, using the Catalog Editor module in Business Desk to make any changes. For information about importing a catalog using Business Desk, see Importing a Catalog.

You can set up BizTalk Server to automatically incorporate an incoming catalog to Commerce Server.

The following figure shows how an XML catalog file is processed.

A figure showing how catalogs are processed using BizTalk Server
Drops the XML document into a shared folder
Your Commerce Server Site
BizTalk Server
Receives XML document
Publish to Web site
Commerce Server database for catalogs
Import an XML catalog file using Business Desk
XML document sent from vendor

Sending Orders to BizTalk Server

The following figure shows how Commerce Server processes an order and then sends it to BizTalk Server.

A figure showing how Commerce Server processes an order and sends it to BizTalk Server
Commerce Server database for orders
Vendors
Order Form
User places order and checks out
Add vendor name
Business Desk
Web Site
Checkout Pipeline
BizTalk Server sends XML document to vendor
XMLTransforms converts order form to XML document using schema
Splitter creates a collection of vendor IDs and attaches it to order form
Commerce Server database for catalogs

Users perform the following steps to create and process an order:

  1. Users add items to their baskets.

    Commerce Server reads the Commerce Server database and retrieves the vendor name for the products.

  2. Users proceed to checkout, and the Commerce Server Checkout pipeline processes the order.

    For each line item (product) in the order, the Splitter component indicates whether that product is supplied by your company or by a vendor with whom you have a trading agreement. The Splitter component creates a list of the vendors, and attaches it to the order form.

  3. Commerce Server determines whether the BizTalk Options property (in the App Default Config resource) is set to 1.

    If the BizTalk Options property is set to 1, Commerce Server reads the list of vendors and bundles the line items for each vendor.

  4. Commerce Server converts the order form into one or more XML documents to be sent to BizTalk Server.

    When Commerce Server converts the order form (using the XMLTransforms process), it creates one XML document for each vendor.

    To convert the order, Commerce Server uses the schema called POSchema.xml, which is associated with the site. If you add one or more fields to the order form, by default Commerce Server does not include the new fields in the XML document that is sent to BizTalk Server. To add the new fields on the order form, you must edit POSchema.xml, an XDR (XML Data-Reduced) format file, and re-associate the XML file with the document in BizTalk Server. You must also transfer the XML file to BizTalk Server and re-associate it. You can edit POSchema.xml using BizTalk Editor.

  5. Commerce Server sends the XML documents to BizTalk Server.

Processing Received Orders

You can submit orders to BizTalk Server in several different ways, depending on your needs. You can use mapping to submit orders, you can use a variety of protocols to submit orders, or your trading partner can create a Commerce Server site or a non-Commerce Server site to receive the submitted orders.

If you choose to have your trading partner set up a Commerce Server site to receive orders, you can set up the site using the _recvpo.asp page that receives XML documents from BizTalk Server. When an XML document is received by _recvpo.asp, the XMLTransforms process is started and converts the XML document back to an order form. Commerce Server then runs a pipeline on the order form. After the pipeline processes the order form, the order is saved to the Commerce Server database. By using _recvpo.asp, you can use Commerce Server objects to redirect the XML to your order management system.

The following figure shows how an XML document is sent from your BizTalk Server and processed by the Commerce Server site of the vendor.

A figure showing how an XML document is sent from BizTalk Server and processed by Commerce Server
Commerce Server Site of Vendor
Order Processing Pipeline
Processes the Order
Transforms XML document into
Order Form
XMLTransforms
_recvpo.asp
BizTalk Server
of Vendor ReceiveStandard.asp
XML document sent from your
BizTalk Server

You can also set up Commerce Server to process and send order forms to a queue, and then set up either your BizTalk Server (or the BizTalk Server at the vendor installation) to poll the queue. If you use this configuration, you can install BizTalk Server and Commerce Server on separate servers. The following figure shows this configuration.

A figure that shows how you can use BizTalk Server and Message Queuing
-Dead queue
-Receiver queue
Message
Queuing
-Send queue
Order Form
Polls queue
Commerce
Server
BizTalk
Server
Writes response to Receiver or Dead queues

See Also

Integrating with BizTalk Server

Programmer's Reference

Splitter


Configuring Commerce Server to Work with BizTalk Server

You use the App Default Config resource to set properties that enable Commerce Server 2000 and BizTalk Server 2000 to work together.

To configure Commerce Server to work with BizTalk Server

  1. Click Start, point to Programs, point to Microsoft Commerce Server, and then click Commerce Server Manager.

  2. Expand Commerce Server Manager, expand Commerce Sites, expand the site you want to use with BizTalk Server (for example, Retail), and then expand Site Resources.

  3. In the left pane, right-click App Default Config, and then click Properties.

  4. In the App Default Config Properties dialog box, on the Properties tab, do the following:
    Use this | To do this
    BizTalk Catalog Doc Type | Type the document definition name that is required by BizTalk Server for catalogs (for example, CatalogTransferDoc).
    BizTalk Options | Type 1 to enable integration with BizTalk Server for document exchange; type 0 to disable integration.
    BizTalk PO Doc Type | Type the document definition name that is required by BizTalk Server for purchase orders (for example, PurchaseOrder).
    BizTalk Source Org Qualifier | Type the alias qualifier for this site in BizTalk Server (for example, MyCompany).
    BizTalk Source Org Qualifier Value | Type the alias value for this site in BizTalk Server (for example, Sender).
    BizTalk Submit Type | Type 1 to submit documents to BizTalk Server asynchronously.

  5. If BizTalk Server is not installed on the same computer as Commerce Server, on the Connection Strings tab, click Modify. In the Data Link Properties dialog box, specify the connection string to the BizTalk server.

  6. Click OK.

Note

  • After you change a property value in Commerce Server Manager, you must unload the application from memory on each Web server for the change to take effect. For instructions, see Unloading an Application from Memory.

See Also

Setting Up the Source Server

Setting Up the Destination Server

Setting Up Your Catalogs for BizTalk Server


Setting Up the Source Server

To set up a messaging configuration between two organizations, you must set up the source server and the destination server. For example, your BizTalk Server is the source server, and the vendor BizTalk Server is the destination server.

Perform the steps described in this section to set up purchase order exchange on the source server. For instructions about setting up the destination server, see Setting Up the Destination Server.

This section contains:

  • Example: Configuring the Source Server for Exchanging Catalogs

  • Example: Configuring the Source Server for Exchanging Purchase Orders

  • Copying and Importing Required Files for the Source Server

  • Creating Source and Destination Organizations on the Source Server

  • Creating Document Definitions on the Source Server

  • Creating Envelopes on the Source Server

  • Creating a Messaging Port on the Source Server

  • Creating a Channel on the Source Server


Example: Configuring the Source Server for Exchanging Catalogs

The following tables list sample values for the App Default Config and BizTalk Server properties needed to configure a source server for catalog exchange.

Sample Values for App Default Config Properties

Set this | To
BizTalk Catalog Doc Type | CatalogTransferDoc
BizTalk Options | 1
Biztalk Source Org qualifier | MyCompanyCatalog
Biztalk Source Org Qualifier Value | CatalogSender
BizTalk Submit Type | 1

Sample Values for Source Organization Properties

Set this | To
Organization Name | Home Organization
Customer Name | MyCompanyCatalog
Qualifier | MyCompanyCatalog
Value | CatalogSender
Application Name | CatalogApplication

Sample Values for Destination Organization Properties

Set this | To
Organization Name | CatalogDestination
Customer Name | MyCompanyCatalog
Qualifier | MyCompanyCatalog
Value | CatalogReceiver

Sample Values for Document Properties

Set this | To
Document Name | CatalogTransferDoc
Document Specification | .../Microsoft/CatalogXMLSchema.xml

Sample Values for Assigning a Messaging port to an Organization

Set this | To
Port Name | CatalogPortToDestination
File Address | Drive: <destination server name>\<shared folder>\CatalogSend.xml Use a valid destination server as <destination server name>. Use a valid shared folder on the destination computer as <shared folder>.

Sample Values for Assigning a Channel from an Application

Set this | To
Name | CatalogChannelToSource
Source Application Name | CatalogApplication
Organization Identifier | BizTalkCatalog/CatalogSender (Default)
Inbound Document | CatalogTransferDoc
Outbound Document | CatalogTransferDoc
Advanced Properties | Click Advanced, and then click Properties. In the Advanced Properties dialog box, set the fully qualified user and password, and then select the type of action to overwrite.

See Also

Configuring Commerce Server to Work with BizTalk Server

Setting Up the Source Server

Setting Up the Destination Server

Setting Up Your Catalogs for BizTalk Server


Example: Configuring the Source Server for Exchanging Purchase Orders

The following tables list examples of the values you enter in App Default Config and BizTalk Server to configure a source server for purchase order exchange.

Sample Values for App Default Config Properties

Set this | To
BizTalk Options | 1
BizTalkPO Doc Type | PurchaseOrder
BizTalk Source Org qualifier | MyCompany
BizTalk Source Org Qualifier Value | Sender
BizTalk Submit type | 1

Sample Values for Source Organization Properties

Set this | To
Organization Name | Home Organization
Customer Name | MyCompany
Qualifier | MyCompany
Value | Sender
Application Name | POApplication

Sample Values for Destination Organization Properties

Set this | To
Organization Name | Destination
Customer Name | MyCompany
Qualifier | MyCompany
Value | Receiver

Sample Values for Document Properties

Set this | To
Document Name | PurchaseOrder
Document Specification | .../Microsoft/POSchema.xml

Sample Values for Envelope Properties

Set this | To
Envelope Name | POEnvelope

Sample Values for Messaging port to an Organization

Set this | To
Port Name | OutPortToDestination
HTTP Address | http://<destination server name>/Retail/ReceiveStandard.asp Use a valid destination server as <destination server name>.
Envelope | POEnvelope
Envelope Identifier | MyCompany / Receiver (Default)

Sample Values for Channel from an Application

Set this | To
Name | OutChannelToDestination
Source Application Name | POApplication
Organization Identifier | BizTalk/Sender (Default)
Inbound Document | PurchaseOrder
Outbound Document | PurchaseOrder

See Also

Configuring Commerce Server to Work with BizTalk Server

Setting Up the Source Server

Setting Up the Destination Server

Example: Configuring the Source Server for Exchanging Catalogs

Example: Configuring the Destination Server for Purchase Order

Setting Up Your Catalogs for BizTalk Server


Copying and Importing Required Files for the Source Server

Both the source and destination servers must contain the same POSchema.xml and CatalogXMLSchema.xml files.

Note

  • The source and destination servers must have the same catalogs of products; otherwise the purchase order submission will fail. For information about setting up your catalogs, see Setting Up Your Catalogs for BizTalk Server.

To copy POSchema.xml to the source server

To import CatalogXMLSchema.xml into BizTalk Editor

To copy POSchema.xml to the source server

  • Copy the POSchema.xml file located in <drive:>\inetpub\wwwroot\<site name> to the path <drive:>\Program Files\Microsoft BizTalk Server\BizTalkServerRepository\DocSpecs\Microsoft.

To import CatalogXMLSchema.xml into BizTalk Editor

  1. Open BizTalk Editor. Click Start, point to Programs, point to Microsoft BizTalk Server 2000, and then click BizTalk Editor.

  2. In BizTalk Editor, on the Tools menu, click Import.

  3. Select XDR Schema, and then click OK.

  4. In the Import XDR Schema dialog box, in the Look in box, navigate to <drive>:\Program Files\Microsoft Commerce Server 2000, select CatalogXMLSchema.xml, and then click Open.

  5. On the File menu, click Store to WebDAV.

  6. In the Store to WebDAV dialog box, in the File name box, type CatalogXMLSchema.xml, and then click Save.

  7. Close the BizTalk Editor.

The CatalogXMLSchema.xml file is imported into BizTalk Editor and stored in Distributed Authoring and Versioning (WebDAV). The file is now a specification, that has the appropriate header information and specified structure so it can be used for catalog exchange.

See Also

Copying Required Files for the Destination Server

Setting Up Your Catalogs for BizTalk Server


Creating Source and Destination Organizations on the Source Server

The source BizTalk Server is the supplier. An organization can be the source or the destination in a messaging port, distribution list, or channel. An organization can represent an external trading partner, your own company, or a business unit within a trading partner or your company. Each organization has unique identifiers that identify it to BizTalk Server 2000 and to other trading partner organizations.

On the source server, you must create both a source organization and a destination organization. A source organization is a trading partner organization that has been designated in a channel as the source of documents. A destination organization is a trading partner organization designated in a messaging port as the destination for documents.

To create a source organization on the source server

To create a destination organization on the source server

To create a source organization on the source server

  1. On the source BizTalk Server, click Start, point to Programs, point to Microsoft BizTalk Server 2000, and then click BizTalk Messaging Manager.

  2. In BizTalk Messaging Manager, in the Configuration Options dialog box, select the Don't show this dialog box again checkbox, and then click OK. Click Cancel to close the dialog box.

  3. In the BizTalk Messaging Manager, in the left pane, in the Search for other items area, click Organizations, and then click Search Now to display the list of available organizations.

  4. In the list of available organizations, double-click Home Organization.

  5. In the Organization Properties dialog box, on the Identifiers tab, click Add.

  6. In the New Identifier dialog box, verify the Custom option is selected, and then type MyCompany.

  7. In the Qualifier box, type MyCompany.

  8. In the Value box, type the name of the sender (for example, Sender).

The Value must be the same as the value entered in the Commerce Server App Default Config Properties dialog box, in the BizTalk Source Org Qualifier Value box. If the values are different, the purchase order submission fails and no error message appears.

For information about setting App Default Config properties, see Configuring Commerce Server to Work with BizTalk Server.

  9. Select the Set as default check box to specify the sender (for example, Sender) as the default organization, and then click OK.

You must designate a default organization before you can create a messaging port. The default organization can serve as either the source or the destination for each new messaging port. You can designate a different default organization at any time and then create messaging ports that use the new default organization.

  10. On the Applications tab, click Add, and in the New Application dialog box, type the application name (for example, POApplication for purchase orders and CatalogTransferDoc for catalog transfers), and then click OK.

  11. In the New Application dialog box, click OK.

  12. In the Organization Properties dialog box, click OK.

The source organization and sender on the source BizTalk Server are created. For example, the source organization is "Home Organization" and the sender is "Sender." You have specified the sender as the default organization.

To create a destination organization on the source server

  1. In BizTalk Messaging Manager, on the File menu, point to New, and then click Organization.

  2. In the New Organization dialog box, on the General tab, type the name of the destination organization (for example, DestinationOrg).

The name that you type here is the name that is displayed on Commerce Server Business Desk when you associate a vendor with a catalog. The name appears in a list of available vendors from which you can select the vendor you want.

  3. In the Comments box, type any necessary comments about the destination organization.

  4. On the Identifiers tab, click Add.

  5. In the New Identifier dialog box, verify the Custom option is selected, and then type MyCompany.

  6. In the Qualifier box, type MyCompany.

  7. In the Value box, type the name of the receiver (for example, Receiver), and then click OK.

  8. In the New Organization dialog box, click OK.

The destination organization and receiver on the source BizTalk Server are created. For example, "Destination" is the destination organization and "Receiver" is the receiver.

See Also

Configuring Commerce Server to Work with BizTalk Server

Creating Document Definitions on the Source Server


Creating Document Definitions on the Source Server

A document definition represents a business document in a messaging port, channel, or distribution list. A document definition provides a pointer to a specification that defines the document. A document definition can be associated with any number of messaging ports, channels, and distribution lists.

To create a document definition with an associated XML file

  1. On the source BizTalk Server, click Start, point to Programs, point to Microsoft BizTalk Server 2000, and then click BizTalk Messaging Manager.

  2. In BizTalk Messaging Manager, on the File menu, point to New, and then click Document Definition.

  3. In the New Document Definition dialog box, in the Document definition name box, type a name for the document definition (for example, PurchaseOrder or CatalogTransferDoc).

The Document definition name must be the same as the value entered in the Commerce Server App Default Config Properties dialog box, in the BizTalk PO Doc type box. If the values are different, the purchase order submission fails.

For information about setting App Default Config properties, see Configuring Commerce Server to Work with BizTalk Server.

  4. Select the Document specification checkbox, and then click Browse.

  5. In the Select a Document Specification from the WebDAV Repository dialog box, double-click the Microsoft folder.

  6. Select the .xml file (for example, POSchema.xml), and then click Open.

  7. In the New Document Definition dialog box, click OK.

The purchase order is created with an associated custom Extensible Markup Language (XML) file.

See Also

Configuring Commerce Server to Work with BizTalk Server

Creating Envelopes on the Source Server


Creating Envelopes on the Source Server

An envelope contains a header and sometimes a footer that prefixes or encapsulates electronic business data for transporting the data to a destination organization. BizTalk Server 2000 uses the envelope properties specified in a messaging port to determine the envelope format that is used to prepare documents for transport.

To create an envelope for the source server

  1. On the source BizTalk Server, click Start, point to Programs, point to Microsoft BizTalk Server 2000, and then click BizTalk Messaging Manager.

  2. In BizTalk Messaging Manager, on the File menu, point to New, and then click Envelope.

  3. In the New Envelope dialog box, in the Envelope name box, type the name of the envelope (for example, POEnvelope), and then click OK.

If you do not assign a custom Extensible Markup Language (XML) file to the envelope you just created, then the default XML file is assigned to the envelope.

See Also

Configuring Commerce Server to Work with BizTalk Server

Creating a Messaging Port on the Source Server


Creating a Messaging Port on the Source Server

A messaging port is a set of rules, configured by BizTalk Messaging Manager, with which you can direct how documents are enveloped, secured, and transported to a designated destination organization. The documents that a port transports originate from the source that is specified in an associated channel. A channel is a set of properties that you can use to provide BizTalk Server with the rules for processing a document that it receives.

In a messaging port, you designate a destination organization or destination application for the documents.

To create a messaging port on the source server

  1. On the source BizTalk Server, click Start, point to Programs, point to Microsoft BizTalk Server 2000, and then click BizTalk Messaging Manager.

  2. In BizTalk Messaging Manager, on the File menu, point to New, point to Messaging Port, and then click To an Organization.

  3. In the New Messaging Port Wizard, in the General Information screen, in the Name box, type the name of the port (for example, OutPortToDestination), and then click Next.

  4. In the Destination Organization screen, select the Organization option, and then click Browse to the right of the Name box.

  5. In the Select an Organization dialog box, select a destination organization (for example, DestinationOrg), and then click OK.

  6. Click Browse to the right of the Address box.

  7. In the Primary Transport dialog box, in the Transport type box, select HTTP from the drop-down list.

  8. In the Address box, type http://<destination server name>/<site name>/ReceiveStandard.asp, and then click OK.

This is the URL for the vendor to which you are sending purchase orders.

  9. Click Next.

  10. In the Envelope Information screen, in the Envelope information box, select POEnvelope from the drop-down list, and then click Next.

  11. In the Security Information screen, verify the Create a channel for this messaging port box is checked.

  12. In the Channel type box, select From an application from the drop-down list, and then click Finish.

  13. In the General Information screen, click Cancel.

The messaging port between your source organization and the destination organization is created.

See Also

Creating a Channel on the Source Server


Creating a Channel on the Source Server

A channel is a set of properties that you use to provide BizTalk Server 2000 with the rules for processing a document that it receives. After a channel processes a document, the document is passed to its associated messaging port or distribution list to be transported to the specified destination. You can create one or more channels for a messaging port or distribution list.

To create a channel on the source server

  1. On the source BizTalk Server, click Start, point to Programs, point to Microsoft BizTalk Server 2000, and then click BizTalk Messaging Manager.

  2. In BizTalk Messaging Manager, in the left pane, click the Messaging Ports link in the Search for other items area, and then click Search Now.

  3. Select the messaging port that the channel will be associated with (for example, OutPortToDestination).

  4. On the File menu, point to New, point to Channel, and then click From an Application.

  5. In the New Channel Wizard, in the General Information screen, in the Name box, type the name of the channel (for example, OutChannelToDestination), and then click Next.

  6. In the Source Application screen, verify the Application option is selected.

  7. In the Name box, select the name of the application from the drop-down list (for example, POApplication for purchase order and CatalogTransferDoc for catalog transfer).

  8. In the Organization identifier box, verify <source organization>/ <identifier value> (Default) as the identifier, (for example, My Company / Sender (Default) and then click Next.

  9. In the Inbound Document screen, click Browse to the right of the Inbound document definition name box.

  10. In the Select a Document Definition dialog box, select the document definition (for example, PurchaseOrder), and then click OK.

  11. In the Inbound Document screen, click Next.

  12. In the Outbound Document screen, click Browse to the right of the Outbound document definition name box.

  13. In the Select a Document Definition dialog box, select the document definition (for example, PurchaseOrder), and then click OK.

  14. In the Outbound Document screen, click Next.

  15. In the Document Logging screen, click Next.

  16. In the Advanced Configuration screen, click Advanced.

  17. In the Override Messaging Port Defaults dialog box, click Properties.

  18. In the BizTalk SendHTTPX Properties dialog box, in the User name box, type the fully qualified user. For example, REDMOND\<user name>.

  19. In the Password box, type the user password, and then click OK.

  20. In the Override Messaging Port Defaults dialog box, click OK.

  21. In the Advanced Configuration screen, click Finish.

A channel from the Home Organization for the messaging port that you created in the procedure, "To create a messaging port on the source server," is created.

See Also

Setting Up the Destination Server


Setting Up the Destination Server

To set up a messaging port between two organizations, you must set up the source server and the destination server. For example, your BizTalk Server is the source server and the vendor BizTalk Server would be the destination server.

Perform the steps described in this section to set up purchase order exchange on the destination server. For instructions about setting up the source server, see Setting Up the Source Server.

This section contains:

  • Example: Configuring the Destination Server for Purchase Orders

  • Copying Required Files for the Destination Server

  • Creating Document Definitions on the Destination Server

  • Creating a Messaging Port on the Destination Server

  • Creating a Channel on the Destination Server


Example: Configuring the Destination Server for Purchase Orders

The following tables list examples of the values you enter in BizTalk Server to configure a destination server for purchase order exchange.

Sample Values for Destination Organization Properties

Set this | To
Organization Name | Home Organization
Customer Name | MyCompany
Qualifier | MyCompany
Identifier Value | Receiver
Application Name | POApplication

Sample Values for Source Organization Properties

Set this | To
Organization Name | Source
Customer Name | MyCompany
Qualifier | MyCompany
Identifier Value | Sender

Sample Values for Document Properties

Set this | To
Document Name | PurchaseOrder
Document Specification | .../Microsoft/POSchema.xml

Sample Values for Assigning a Messaging Port to an Application

Set this | To
Port Name | InPortFromSource
Application Name | POApplication
HTTP Address | http://<destination server name>/Retail/_recvpo.asp Use a valid destination server as <destination server name>.
Envelope | POEnvelope
Envelope Identifier | MyCompany / Receiver (Default)

Sample Values for Assigning a Channel from an Organization

Set this | To
Name | InChannelFromSource
Source Application Name | POApplication
Organization Identifier | MyCompany/Sender (Default)
Inbound Document | PurchaseOrder
Outbound Document | PurchaseOrder

See Also

Configuring Commerce Server to Work with BizTalk Server

Setting Up the Source Server

Setting Up the Destination Server

Setting Up Your Catalogs for BizTalk Server

Example: Configuring the Source Server for Exchanging Catalogs


Copying Required Files for the Destination Server

Both the source and destination servers must contain the same POSchema.xml file.

Note

  • The source and destination servers must have the same catalogs of products; otherwise the purchase order submission will fail. For information about setting up your catalogs, see Setting Up Your Catalogs for BizTalk Server.

To copy ReceiveStandard.asp to the destination server

  • Copy the ReceiveStandard.asp file located in <drive:>\Program Files\Microsoft BizTalk Server\SDK\Samples to the path <drive:>\inetpub\wwwroot\<site name>.

To copy POSchema.xml to the destination server

  • Copy the POSchema.xml file located in <drive:>\inetpub\wwwroot\<site name> to the path <drive:>\Program Files\Microsoft BizTalk Server\BizTalkServerRepository\DocSpecs\Microsoft.

See Also

Copying Required Files for the Source Server

Setting Up Your Catalogs for BizTalk Server


Creating a Destination Organization on the Destination Server

The destination BizTalk Server is the vendor. An organization can be the source or the destination in a messaging port, distribution list, or channel. An organization can represent an external trading partner, your own company, or a business unit within a trading partner or your company. Each organization has unique identifiers that identify it to BizTalk Server 2000 and to other trading partner organizations.

To support basic authentication, you use the ReceiveStandard.asp file that is shipped with BizTalk Server. The ReceiveStandard.asp page collects information and submits it to BizTalk server. To implement a secure Web site, you must set privileges on ReceiveStandard.asp.

On the destination server, you must create both a source organization and a destination organization.

To set privileges on ReceiveStandard.asp

To create a destination organization on the destination server

To create a source organization

To set privileges on ReceiveStandard.asp

  1. Click Start, point to Programs, point to Administration Tools, and then click Internet Services Manager.

  2. Expand the <server name>, expand the default website, select the site (for example, Retail), and then right-click ReceiveStandard.asp.

  3. In the File Security tab, in the Anonymous access and authentication control section, click Edit.

  4. In the Authentication Methods dialog box, in the Anonymous access section, click Edit.

  5. In the Anonymous User Account dialog box, in the Username box, type the Windows user name of the account used to access this computer. In the Password box, type the Windows user account password.

  6. In the Anonymous User Account dialog box, click OK.

  7. In the Authentication Methods dialog box, click OK.

  8. In the ReceiveStandard.asp Properties dialog box, click OK.

  9. Close Internet Services Manager.

ReceiveStandard.asp is set up for secure operations. Access to the site is locked and the receiver of a purchase order exchange or catalog exchange will need to know the user account and password.

To create a destination organization on the destination server

  1. On the destination BizTalk Server, click Start, point to Programs, point to Microsoft BizTalk Server 2000, and then click BizTalk Messaging Manager.

  2. In BizTalk Messaging Manager, in the Configuration Options dialog box, click Cancel to close the dialog box.

  3. In the left pane, in the Search for other items area, click Organizations, and then click Search Now to display the list of available organizations.

  4. In the list of available organizations, double-click Home Organization.

  5. In the Organization Properties dialog box, on the Identifiers tab, click Add.

  6. In the New Identifier dialog box, verify the Custom option is selected, and then type MyCompany.

  7. In the Qualifier box, type MyCompany.

  8. In the Value box, type the name of the source organization (for example, Receiver).

  9. Select the Set as default check box to set the source organization as the default organization, and then click OK.

You must designate a default organization before you can create a messaging port. The default organization can serve as either the source or the destination for each new messaging port. You can designate a different default organization at any time and then create messaging ports that use the new default organization.

  10. On the Applications tab, click Add.

  11. In the New Application dialog box, type the application name (for example, POApplication), and then click OK.

  12. In the New Organization dialog box, click OK.

The source organization on the destination server is created and specified as the default organization.

To create a source organization

  1. In BizTalk Messaging Manager, on the File menu, point to New, and then click Organization.

  2. In the New Organization dialog box, on the General tab, in the Organization name box, type the name of the destination organization (for example, Source).

  3. In the Comments box, type any necessary comments about the destination organization.

  4. On the Identifiers tab, click Add.

  5. In the New Identifier box, select the Custom option, and then type MyCompany.

  6. In the Qualifier box, type MyCompany.

  7. In the Value box, type the name of the receiver (for example, Sender), and then click OK.

  8. In the New Organization dialog box, click OK.

The destination organization is created.

See Also

Creating Document Definitions on the Destination Server


Creating Document Definitions on the Destination Server

A document definition represents a business document in a messaging port, channel, or distribution list. A document definition provides a pointer to a specification that defines the document. A document definition can be associated with any number of messaging ports, channels, and distribution lists.

The destination BizTalk Server is the vendor.

To create a document definition with an associated XML file

  1. On the destination BizTalk Server, click Start, point to Programs, point to Microsoft BizTalk Server 2000, and then click BizTalk Messaging Manager.

  2. In BizTalk Messaging Manager, on the File menu, point to New, and then click Document Definition.

  3. In the New Document Definition dialog box, in the Document definition name box, type a name for the document definition (for example, PurchaseOrder).

  4. Select the Document specification dialog box, and then click Browse.

  5. In the Select a Document Specification from the WebDAV Repository dialog box, double-click the Microsoft folder.

  6. Select an Extensible Markup Language (XML) file (for example, POSchema.xml), and then click Open.

  7. In the New Document Definition dialog box, click OK.

A purchase order is created with an associated custom XML file.

See Also

Creating a Messaging Port on the Destination Server


Creating a Messaging Port on the Destination Server

The destination BizTalk Server is the vendor.

To create a messaging port on the destination server

  1. On the destination BizTalk server, click Start, point to Programs, point to Microsoft BizTalk Server 2000, and then click BizTalk Messaging Manager.

  2. In BizTalk Messaging Manager, on the File menu, point to New, point to Port, and then click To an Application.

  3. In the New Messaging Port Wizard, in the General Information screen, in the Name box, type the name of the port (for example, OnPortFromSource), and then click Next.

  4. In the Destination Application screen, select the Application option, and then in the Name box, select the name of the application (for example, POApplication) from the drop-down list.

  5. In the Primary Transport section, click Browse to the right of the Address box.

  6. In the Primary Transport dialog box, in the Transport type box, select HTTP from the drop-down list.

  7. In the Address box, type http://<destination server name>/<site name>/_recvpo.asp, and then click OK.

  8. Click Next.

  9. In the Envelope Information screen, leave the Envelope information box blank because the default XML file is being used.

  10. Click Next.

  11. In the Security Information screen, verify the Create a channel for this messaging port check box is selected.

  12. In the Channel type box, select From an application from the drop-down list, and then click Finish.

  13. In the General Information screen, click Cancel.

The messaging port between the Home organization and the destination organization is created.

See Also

Creating a Channel on the Destination Server


Creating a Channel on the Destination Server

A channel is a set of properties that you can use to provide BizTalk Server 2000 with the rules for processing a document that it receives. After a channel has processed a document, it is passed to its associated messaging port or distribution list to be transported to the specified destination. You can create one or more channels for a messaging port or distribution list.

The destination BizTalk Server is the vendor.

To create a channel on the destination server

  1. On the destination BizTalk Server, click Start, point to Programs, point to Microsoft BizTalk Server 2000, and then click BizTalk Messaging Manager.

  2. In BizTalk Messaging Manager, in the left pane, click the Messaging ports link in the Search for other items area, and then click Search Now.

  3. Select the port that the channel will be associated with (for example, SubmitPort).

  4. On the File menu, point to New, point to Channel, and then click From an Organization.

  5. In the New Channel Wizard, in the General Information screen, in the Name box, type the name of the channel (for example, InChannelFromSource), and then click Next.

  6. In the Source Organization screen, verify the Organization option is selected.

  7. Click Browse, to the right of the Name box.

  8. In the Select an Organization dialog box, select the destination organization (for example, MySupplier), and then click OK.

  9. In the Organization identifier box, verify <source organization>/ <identifier value> (Default) as the identifier, and then click Next.

  10. In the Inbound Document screen, click Browse to the right of the Inbound document definition name box.

  11. In the Select a Document Definition dialog box, select the document definition (for example, PurchaseOrder), and then click OK.

  12. In the Inbound Document screen, click Next.

  13. In the Outbound Document screen, click Browse to the right of the Outbound document definition name box.

  14. In the Select a Document Definition dialog box, select the document definition (for example, PurchaseOrder), and then click OK.

  15. In the Outbound Document screen, click Next.

  16. In the Document Logging screen, click Next.

  17. In the Advanced Configuration screen, click Finish.

The channel between the Home Organization/application and the Home organization for the source/sender messaging port is created.


Setting Up Your Catalogs for BizTalk Server

When you set up an agreement with a vendor, the vendor ID is made available to Commerce Server. The vendor ID is the organization name that you specify for the vendor when you create a destination organization for the source server. For more information, see Creating Source and Destination Organizations on the Source Server.

Commerce Server displays the vendor ID in Commerce Server Business Desk. It displays those trading partners (organizations) that support the same document type as your organization, and thus have compatible document routing. You can then use Business Desk to associate the vendor ID and the catalog.

More than one catalog can be associated with a given vendor. You can also specify a vendor at the product level; however, if you do this you must also customize _additem.asp.

If you name a vendor Default, Commerce Server recognizes your own site as the vendor.

Note

  • When a user orders an item from your Web site, the item must exist in the catalog of the destination organization. If the destination organization does not have the item in its catalog, BizTalk Server will not be able to send the purchase order from your site to the vendor. It will write an error message to the event log instead.

To associate a catalog with a vendor

  1. From Commerce Server Business Desk, in Catalogs, click Catalog Editor.

  2. In the Catalogs screen, select the catalog you want to add the vendor ID to, and then click Open on the toolbar.

  3. In the Catalog Editor - <catalog name> screen, in the Vendor ID box, click the ellipsis button [...] to display a list of vendor identifications. Select the appropriate vendor identification for this catalog.

    Commerce Server updates the list of vendors automatically each time you create another agreement with a vendor using BizTalk Server.

  4. To save your change to the catalog and return to the Catalogs screen, click Save and go back on the toolbar.

See Also

Example: Configuring the Source Server for Exchanging Catalogs

Creating a New Catalog

Sending a Catalog to a Trading Partner


Monitoring Commerce Server Sites

Microsoft Windows 2000 Server and Commerce Server 2000 provide a set of monitoring tools that system administrators can use to monitor the performance of their Commerce Server sites. The tools provided by Windows 2000 Server and Commerce Server help you to analyze site usage. You can use the results of these analyses to fine-tune site performance and accommodate growth.

Planning for and configuring your monitoring tools are the initial steps for monitoring your sites. After you have a monitoring plan in place, see Optimizing Commerce Server for more information about fine-tuning the performance of your sites.

This document assumes you have knowledge of Event Viewer and System Monitor. For more information about Event Viewer and System Monitor, see Windows 2000 Server Help.

This section contains:

  • About Site Monitoring. Describes monitoring tools you can use.

  • Setting Up Your Monitoring Configuration. Describes how to plan for and configure your monitoring tools.

  • Monitoring Production Servers. Describes ways to monitor production servers.

  • Using Performance Monitoring Tools. Describes the tools available for monitoring server performance.

  • Using the Event Viewer Snap-In. Describes how to use the Event Viewer snap-in and the different types of event logs and Windows 2000 events.

  • Performance Monitoring Counters. Describes performance counters and explains how to set them up. Lists the counters provided with Commerce Server.


About Site Monitoring

You can monitor Commerce Server sites using Microsoft Windows 2000 System Monitor, Performance Logs and Alerts, and other similar tools to predict where bottlenecks are going to occur in your system. (A bottleneck is hardware or software that is operating at maximum capacity.)

When you monitor a system running under Windows 2000 Server, you monitor the behavior of its objects. Windows 2000 uses objects to identify and manipulate system resources, and contains objects that represent individual processes, sections of shared memory, and physical devices.

The Windows 2000 Performance tool is composed of two parts: System Monitor and Performance Logs and Alerts. System Monitor collects data on object activity, object demand, and the amount of space used by the objects. System Monitor also groups counters by object type. A unique set of counters exists for the process, memory, cache, hard disk, and other object types that produce statistical information.

Commerce Server provides more than 200 extensible counters as tools for monitoring. Extensible counters are performance monitor counters that come with applications other than Windows 2000 or that you can build yourself with information from the Windows 2000 Software Developer Kit (SDK).

To optimize site performance, you must know exactly which counters your system is using, what exactly is being measured, and how the measurement is determined. This information is particularly important when you receive unexpected data or inconsistent results. For more information about monitoring configurations, see "Setting Up Your Monitoring Configuration" in Windows 2000 Server Help.

See Also

Commerce Server Performance Counters

Setting Up Performance Counters


Setting Up Your Monitoring Configuration

You begin monitoring your sites by planning for capacity and by configuring your monitoring tools to keep monitoring overhead low. You should create monitoring configurations that can be saved and copied to other computers using the System Monitor in the Microsoft Management Console (MMC). A monitoring configuration will help you highlight data center issues and visualize traffic flow through your system. Creating this configuration can also help you to understand any site software issues and to see how the software is interrelated.

In planning your configuration, do the following:

  • Configure Performance Logs and Alerts to report data for the recommended counters at regular intervals, such as every 10 to 15 minutes.

  • Retain logs over extended periods of time.

  • Store resulting data in a database, and query the data in order to analyze it and report on overall performance assessment, trend analysis, and capacity planning.

Capacity Planning

Keeping Monitoring Overhead Low

Capacity Planning

Capacity planning is the process of planning for application, hardware, and network requirements to support expected site traffic and to achieve site performance goals. You determine capacity by measuring the number of users to your site, determining how much demand each user places on the server, and then calculating the computing resources (CPU, RAM, disk space, bandwidth and utilization, and network bandwidth) necessary to support current and future usage levels.

To ensure adequate capacity, you must calculate how much computing hardware you need to handle the load that thousands or hundreds of thousands of users can put on your site. These calculations can help you find weak areas that can cause performance degradation. You can resolve weak areas by adding hardware or by redesigning dynamic pages or other CPU-intensive tools.

Keeping Monitoring Overhead Low

  • Commerce Server performance counters and tools are designed for minimal performance overhead. However, performance tool operation is affected by file sizes and disk space taken up by log files, which contributes to overhead.

  • You can reduce file size and related disk space usage by extending the update interval. Also, you can log data to a disk other than the one you are monitoring. Frequent logging also adds demand on disk input and output (I/O).

Increases in Monitoring Overhead

  • If monitoring overhead is a concern, run only Performance Logs and Alerts and do not use a System Monitor graph for monitoring your site. You may find that overhead increases under each of the following conditions:
    • You are running System Monitor in graph view.

    • You have selected an option other than the default (current value) for a report view.

    • You are sampling data at very frequent intervals (less than three seconds apart).

Monitoring Recommendations

For diagnostic purposes, do the following before starting System Monitor or Performance Logs and Alerts on the computer you are using for monitoring:

  • Stop screen-saver programs.

  • Turn off services that are not essential or relevant to monitoring.

  • Run the System Monitor from a remote machine. By making this change, you move the majority of the CPU and I/O cost to the remote computer.

  • Increase the paging file to physical memory size plus 100 MB.

  • Use a private administrative network. During remote logging, frequent updating can slow performance due to network transport. Using a private administrator network, which is typically done with another network interface card (NIC), solves this issue. You can also reduce the sample of data collection. For example, if you are sampling data at three-second intervals, sample at five-second intervals. Also, you can use two network interfaces/computers so that each network segment is doing different operations. For example, one computer may be dedicated for updating news and another may be dedicated for updating stock trading transactions.

Additional recommendations

The following are additional recommendations for using performance tools with minimal overhead:

  • Analyzing performance results and establishing a performance baseline. Review logged data by graphing it using the System Monitor display or exporting it for printing. For detailed information about specific performance counters, see Commerce Server Performance Counters.

  • Setting alerts. Set alerts according to the counter values you consider unacceptable, as defined by your baseline evaluation.

  • Reducing counters. Reduce the number of performance counters to only those you need. For a list of recommended counters, see Hardware Performance Counters and Commerce Server Performance Counters.

  • Planning. Monitor trends for capacity planning and add or upgrade components as needed. Maintain logged data in a database and observe changes to identify changes in resource requirements. After you observe changes in activity or resource demand, you can identify where you may require additional resources.

See Also

Optimizing Commerce Servers


Monitoring Production Servers

If you manage a Web farm of computers running Commerce Server 2000, you can monitor system performance with Windows 2000 System Monitor or other similar tools to predict where bottlenecks are going to occur. You can effectively monitor your production servers by running calibration tests, updating usage profiles, and monitoring performance counters for Commerce Server.

Run Calibration Tests

Update Usage Profiles

Monitor Commerce Server Performance Counters

Run Calibration Tests

A Compaq RAID array, or similar disk subsystem has very different performance characteristics depending upon the actual hardware setup. As a best practice, you should calibrate the subsystem to determine the following elements:

  • Maximum physical disk reads per second

  • Maximum physical disk writes per second

  • Maximum disk bytes per second

Modern disk subsystems have tiers of complexity. For single disk drives or simple SCSI solutions, the % Disk Time counter is an accurate reflection of the capacity of the physical disk. For more complex multi-disk configurations, the disk queue can grow to the number of active spindles in the array before any items are actually waiting to be transferred.

For the newest Low Voltage Differential (LVD) or Fibre Channel disk systems, the issues are more complex. For these high-end systems, you should observe performance and capacity with the tools the vendor supplies. In addition, there is a maximum bandwidth limit in the system bus of the server and the SCSI or Fibre Channel interface. The total disk throughput should be compared to these limitations.

Update Usage Profiles

The usage profile is a statistical model of an average user interaction and the maximum number of concurrent users that the site needs to support at its peak. An important part of site monitoring is to monitor users to determine if user behavior has changed. Watching growth trends in user activity is critical. More important, however, is to give this data to the developers, testers, and capacity planners so they can plan for future hardware and software requirements.

You use the User Profile Management performance counters to update and monitor user behavior.

Monitor Commerce Server Performance Counters

Review the list of Commerce Server performance counters. Begin by adding the counters from this list to the System Monitor. You can add other counters later. The following figure shows the System Monitor with Catalog and User Profile Management performance counters added.

(Art Order) System Monitor performance console

Click the illustration to enlarge or reduce.

See Also

Using Performance Monitoring Tools

Hardware Performance Counters

Commerce Server Performance Counters


Using Performance Monitoring Tools

The Windows 2000 Performance tool is composed of two parts: System Monitor and Performance Logs and Alerts. With System Monitor, you can collect and view real-time data about memory, disk, processor, network, and other activity in graph, histogram, or report form. Through Performance Logs and Alerts you can configure logs to record performance data and set system alerts to notify you when the value for a specified counter is above or below a defined threshold. This section focuses on System Monitor. (For information about using Performance Logs and Alerts, open Commerce Server Manager, right-click Performance Logs and Alerts, and then click Help.)

This section contains:

  • System Monitor

  • Other Performance Monitoring Tools

For more information about the Performance tool, see Windows 2000 Server Help.


System Monitor

You use System Monitor to measure the performance of your own computer or other computers on a network. System Monitor uses a series of counters that track data, such as the number of processes waiting for disk time, the number of network packets transmitted per second, and the percentage of processor utilization. With this data, you can create charts, set alerts, and format reports that enable you to gauge and tune system performance. Data can be displayed as it is collected, stored in log files for later use and comparison, or both.

See Also

Commerce Server Performance Counters


Other Performance Monitoring Tools

You can use the various server and resource monitoring tools, available in Microsoft Windows 2000 Server and Microsoft Visual Studio, for monitoring Commerce Server 2000 sites.

Health Monitor

Internet Protocol Security (IPSec) Monitor

Microsoft Web Application Stress Tool

Network Monitor

SQL Server Profiler

Visual Studio Analyzer

Health Monitor

Health Monitor is a service that is available in Microsoft Application Center 2000. Health Monitor displays events and threshold breaches by running an agent on each monitored server and tracking values in the Windows Machine Interface (WMI). For more information about Application Center, see Microsoft Application Center 2000 Help.

Internet Protocol Security (IPSec) Monitor

Windows 2000 provides the Internet Protocol Security (IPSec) Monitor to confirm whether your secured communications are successful. It displays the active security associations on local or remote computers. For example, you can use IPSec Monitor to determine whether there has been a pattern of authentication or security association failures, possibly indication incompatible security policy settings.

Microsoft Web Application Stress Tool

The Microsoft Web Application Stress (WAS) tool is a simulation tool developed by Web testers to realistically reproduce multiple browsers requesting pages from a Web application. Microsoft has made the tool easy to use by masking some of the complexities of Web server testing. This makes the WAS tool useful for anyone interested in gathering performance data on a Web site.

The WAS tool is a consolidation of many of the best features developed in WAS over the years, as well as a few new features. In addition, the current version covers the most needed features for stress testing three-tiered, personalized, and ASP page sites running on Windows 2000.

Network Monitor

Network Monitor (Netmon.exe) is a Windows 2000 administrative tool you can use to track network traffic. You use Network Monitor to capture network traffic for display and analysis. You can use this tool to perform tasks such as analyzing previously captured data in user-defined methods, extracting data from defined protocol parsers, and analyzing real-time traffic on your network.

Network Monitor is useful for capturing packets between browsers, Web servers, and SQL Server. It provides valuable timing information as well as packet size, network utilization, and many other statistics that can be valuable for managing system performance. It is not installed by default, but you can install it by using the Add/Remove Programs option in the Control Panel.

SQL Server Profiler

SQL Server Profiler is a tool that captures Microsoft SQL Server events from a server. The events are saved in a trace file that you can analyze or use to replay a specific series of steps later when you are trying to diagnose a problem. You can use SQL Server Profiler to:

  • Step through problem queries to find the cause of the problem.

  • Find and diagnose slow-running queries.

  • Capture the series of SQL statements that lead to a problem. The saved trace can then be used to replicate the problem on a test server where the problem can be diagnosed.

  • Monitor the performance of SQL Server to tune database performance.

Visual Studio Analyzer

You can use Visual Studio Analyzer, a tool in Microsoft Visual Studio 6.0 Enterprise Edition, to analyze performance, isolate page faults, and understand the structure of your distributed applications. You can use Visual Studio Analyzer with applications and systems built with any of the Visual Studio tools.

Several Microsoft technologies, such as Component Object Model (COM), Active X Data Objects (ADO), and COM+, are shipped with the ability to provide information to Visual Studio Analyzer. If your applications use any of these technologies, you can get detailed information about this use in Visual Studio Analyzer. In addition, you can customize your own applications to provide information to Visual Studio Analyzer.


Using the Event Viewer Snap-In

Commerce Server 2000 generates events in the Event Viewer snap-in so system administrators can verify that Commerce Server is performing correctly. Event Viewer tracks informational, warning, and error events. The logs in Event Viewer provide an audit record of all Commerce Server events and all Microsoft Windows events, which includes processes such as logon times and connection times.

Windows 2000 records events in three kinds of logs:

  • Application log. Contains events logged by applications or programs. For example, a database program might record a file error in the application log. Your site developer decides which events to record. Use this log to verify the import or export of a catalog.

  • System log. Contains events logged by the Windows 2000 system components. For example, the failure of a driver to load during startup is recorded in the system log. The event types logged by system components are predetermined by Windows 2000.

  • Security log. Records security events such as valid and invalid logon attempts as well as events related to resource use, such as creating, opening, and deleting files. Your system administrator can specify what events are recorded in the security log. For example, if you have enabled logon auditing, attempts to log on to the system are recorded in the security log.

This section contains:

  • Windows Events


Windows Events

Windows events and Performance Logs and Alerts are recorded in the EventLog service. The EventLog service starts automatically when you start Windows 2000. All users can view application and system logs, however, only administrators have access to security logs.

By default, security logging is turned off. You can use Group Policy to enable security logging. The system administrator can also set auditing policies in the registry that cause the system to halt when the security log is full.

Event Viewer displays the following types of events:

  • Error. A significant problem, such as loss of data or loss of functionality. For example, if a service fails to load during startup, an error will be logged.

  • Warning. An event that is not necessarily significant, but may indicate a possible impending problem. For example, when disk space is low, a warning will be logged.

  • Information. An event that describes the successful operation of an application, driver, or service. For example, when a network driver loads successfully, an information event will be logged.

  • Success audit. An audited security access attempt that succeeds. For example, the successful attempt by a user to log on the system will be logged as a success audit event.

  • Failure audit. An audited security access attempt that fails. For example, if a user tries to access a network drive and fails, the attempt will be logged as a failure audit event.

The following figure shows how the event viewer appears with some of the events and alerts.

(Art Order) Event Viewer

Click the illustration to enlarge or reduce.


Performance Monitoring Counters

System Monitor uses Performance Logs and Alerts to collect data called performance counters. A performance counter is a data item associated with a performance object. For each counter you select, System Monitor presents a value corresponding to a particular aspect of the performance defined for the performance object.

Performance counters allow you to monitor specific aspects of work performed on your site by a system or service. System Monitor groups counters by object type. A unique set of counters exists for Commerce Server processes, memory, cache, hard disk, and other object types that produce statistical information. For more information about Performance Logs and Alerts, see Windows 2000 Server Help.

This section contains:

  • Setting Up Performance Counters

  • Hardware Performance Counters

  • Commerce Server Performance Counters

  • Monitoring the Predictor Resource


Setting Up Performance Counters

You use the System Monitor to set up performance counters.

To set a performance counter

  1. Click Start, point to Programs, point to Microsoft Commerce Server, and then click Commerce Server Manager.

  2. Click System Monitor to open the performance console.

  3. In the performance console, click the plus sign (+) on the System Monitor toolbar to add performance counters to your server.

  4. In the Add Counters dialog box, do the following:
    Use this | To do this
    Use local computer counters | Select to specify that the selected counters be used on any computer on which the performance console is run.
    Select counters from computer | Select to specify that the selected counters be used on a specific computer on the network.
    Performance object | Select the performance object to which this counter applies. For example, the Predictor resource performance counters are listed under the CS2000: Marketing and Catalog performance object.
    All counters | Select to include all counters for the selected performance object.
    Select counters from list | Select to specify that you want to select individual counters for the selected performance object.
    All instances | Select to specify that all instances for the selected counter be displayed.
    Select instances from list | Select to specify that System Monitor use all instances selected from the list.

  5. As an optional step, click Explain to open a drop-down box containing descriptive data about each performance counter.

  6. Click Add to add all counters you have selected, and then click Close.

The performance counters you selected now appear and begin running in the System Monitor performance console. The following figure shows the Add Counters dialog box with CS2000: Pipelines counters exposed.

(Art Order) Performance Counter dialog box

Click the illustration to enlarge or reduce.


Hardware Performance Counters

The following table describes the hardware performance counters you should monitor. You can find these counters in Microsoft Windows 2000 System Monitor. Each server in your data center should be monitored with performance counters and the results should be viewed collectively. The counters in the System and Memory objects can be used to monitor capacity.

Performance object | Counter name | Description
Network Segment | Bytes received per second Bytes sent per second | If a network card approaches its maximum capacity, another should be added. If this value approaches the capacity of the network, then a higher bandwidth network might be necessary.
Inetinfo Instance (in the Process object) | Virtual bytes | Monitor this for memory leaks or size approaching maximum available RAM. This counter measures the virtual memory allocations.
 | Working set | Should be well within the hardware capacity you have available, which means less than the physical RAM.
Memory | Available bytes | Should be greater than 4 MB.
 | Pages per second | Should be less than one page per second. If the system is actually out of memory, this is the biggest indicator of the problem.
Physical Disk | Disk Writes/second Disk Reads/second | Combined, these two counters should be well under the maximum capacity for the disk device.
 | % Disk Time | The percentage of elapsed time that the selected disk drive is busy servicing read or write requests.
SQL Server | IO transactions/sec | Indicates how much activity the SQL Server actually performs.
 | Compiles/sec Recompiles/sec | Indicates the efficiency of the queries that SQL Server is executing. Reducing this number is key to reducing the CPU load on the SQL Server.
System | Context switches/sec | If this rate is greater than 5,000 context switches per CPU, then another server should be added to horizontally scale the system.
 | %Total Processor | Peak utilization can be 100 percent, but utilization should not be sustained at a level past the capacity of your processor. All of the server elements can be scaled horizontally.
Web | Total connections | The number of active Transmission Control Protocol (TCP) connections to the server.
 | Get requests/sec | The number of Hypertext Transfer Protocol (HTTP) requests that are received at the server. This is the primary indicator of traffic to a Web site.
 | Non-anonymous users per second | Tracks the number of authenticated user requests at a site.
Active Server Pages | Requests per second | Rate that Active Server Pages (ASP) are processing requests. Includes both successful and failed requests.
 | Requests executing | The average number of requests running at a time during the sample period. Internet Information Services (IIS) 5.0 has many threads that can simultaneously process requests.
 | Request wait time | Should be very close to zero (less than 100 milliseconds) because this is the amount of time a request sits in the queue before it begins processing. You do not want users to experience long wait times to process their checkout transactions.
 | Requests queued | There should not be a significant queue except at peak periods.

Bytes received per second

Compare the Bytes received per second counter to the total bandwidth of your network adapter card to determine whether your network connection is creating a bottleneck. To allow room for spikes in traffic, you should usually use no more than 50 percent of capacity. If this number is very close to the capacity of the connection, and processor and memory use are moderate, then the connection might be a problem.

Requests executing

If the number for the Requests executing counter is always greater than one (1), there could be a problem in an ASP page or object that is causing a request to hang. If this number is never greater than one, even during peak periods, you might have accidentally left ASP bugging on in your site.


Commerce Server Performance Counters

The following table lists the performance counters available in Commerce Server 2000. It is recommended that you run these counters in System Monitor, located in the Console Root in Commerce Server Manager.

Performance object | Counter name | Description
CS2000: User Profile Management | AuthMgr: AnonTickets/sec | The number of tickets, or property/value pairs, set for anonymous users per second at a particular commerce site.
 | AuthChecks Failed/sec | The number of failed authentication checks per second at a particular commerce site.
 | AuthMgr: AuthChecks Succeeded/sec | The number of successful authentication checks per second at a particular commerce site.
 | AuthMgr: AuthMgr Objects/sec | The number of Authentication Manager objects created per second at a particular commerce site.
 | AuthMgr: AuthTickets/sec | The number of authenticated tickets set per second at a particular commerce site.
 | AuthMgr: Custom Properties/sec | The number of custom properties set per second at a particular commerce site.
 | AuthMgr: Get_Custom-Properties/sec | The number of Get_Custom-Properties set per second at a particular commerce site. The GetProperty() counter fetches the custom property values from the user cookie.
 | AuthMgr: Total AnonTickets | The total number of tickets, or property/value pairs, set for anonymous users at a particular commerce site.
 | AuthMgr: Total AuthChecks Failed | The total number of failed authentication checks at a particular commerce site.
 | AuthMgr: Total AuthChecks succeeded | The total number of successful authentication checks at a particular commerce site.
 | AuthMgr: Total AuthMgr Objects Created | The total number of Authentication Manager objects created at a particular commerce site.
 | AuthMgr: Total AuthTickets | The total number of authenticated tickets at a commerce site.
 | AuthMgr: Total Custom-Properties | The total number of Custom-properties set at a particular commerce site.
 | AuthMgr: Total Get_Custom-Properties | The total number of GetCustom-properties set at a particular commerce site.
 | AuthFilter: Token-Cache-Entries (total) | The total number of Token-Cache entries in Windows Authentication mode.
 | AuthFilter: Token-Cache-Size (bytes) | The size, in bytes, of Token-Cache in Windows Authentication mode.
 | AuthFilter: Token-Cache Entries (Active) | The current number of active Token-Cache entries in Windows Authentication mode.
 | AuthFilter: WindowsAuth-Cache-Hits | The total number of password cache hits in Windows Authentication mode.
 | AuthFilter: WindowsAuth-Cache-Hits/sec | The number of password cache hits per second in Windows Authentication mode.
 | AuthFilter: WindowsAuth-Cache-Misses | The total number of password cache misses in Windows Authentication mode.
 | AuthFilter: WindowsAuth-Cache-Misses/sec | The number of password cache misses per second in Windows Authentication mode.
 | AuthFilter: Total Successful Windows-AuthChecks | The total number of successful Windows Authentication checks by the authentication Internet Server Application Program Interface (ISAPI) filter. This is the total number of times the filter passed the credentials to Internet Information Services (IIS) 5.0 and returned successfully.
 | AuthFilter: Successful Windows-AuthChecks/sec | The number of successful Windows Authentication checks per second.
 | AuthFilter: Total Failed Windows-AuthChecks | The total number of failed Windows Authentication checks.
 | AuthFilter: Failed Windows-AuthChecks/sec | The number of failed Windows Authentication checks per second.
 | AuthFilter: Total AutoCookies | The total number of AutoCookies generated.
 | AuthFilter: AutoCookies/sec | The number of AutoCookies generated per second.
 | AuthFilter: Total Requests Failed | The number of failures caused by a full filter-cache, or because an error occurred and a filter redirected to an error page.
 | UPM: Object Reads | The total number of profile objects retrieved.
 | UPM: Object Reads/sec | The number of profile objects retrieved per second.
 | UPM: Object Creations | The total number of profile objects created.
 | UPM: Object Creations/sec | The number of profile objects created per second.
 | UPM: Object Deletes | The total number of profile objects deleted.
 | UPM: Object Deletes/sec | The number of profile objects deleted per second.
 | UPM: Object Modifies | The total number of profile objects modified.
 | UPM: Object Modifies/sec | The number of profile objects modified per second.
 | UPM: Cache Objects | The total number of cache objects.
 | UPM: Cache Hit Rate/sec | The number of cache hits per second.
 | UPM: Cache Miss Rate/sec | The number of cache misses per second.
 | UPM: Background Thread State | The value for this counter is either 1 (On) or 0 (Off), indicating whether the background thread is currently active.
 | UPM: No. of Cache Purges | The number of times the foreground thread purged entries from the profile object cache to search for a free block of memory.
 | UPM: DTS Records Exported/sec | The number of Data Transformation Services (DTS) records exported per second.
 | UPM: DTS Records Exported | The total number of DTS records exported.
 | UPM: DTS Export Errors | The total number of DTS errors that occurred during export. This is a cumulative number of field mismatches and objects that could not be recorded by the Data Warehouse.
Catalog | Catalog Queries per second | The number of queries made to the catalog system per second. Query and FreeTextSearch are used to record the values for the performance monitor counters. No other methods record the counters.
Data Warehouse and Analysis | CatImport: Total Catalogs | Total number of catalogs imported during this DTS import task.
 | CatImport: Total Categories | Total number of categories imported during this DTS import task.
 | CatImport: Total Products | Total number of products imported during this DTS import task.
 | UImport: Free hit buffers | The number of currently available empty hit buffers.
 | UImport: Used hit buffers | The number of currently filled hit buffers.
 | UImport: Hits per second | The rate per second at which the import task is processing hits.
 | UImport: Current visits | The total number of active visits recorded while the logs are processed.
 | UImport: Commerce events | The total number of Commerce Server events that occurred for the import task.
 | UImport: Decoded cookies | The total number of UPM-decoded cookies encountered while the import task was running.
 | UImport: Query strings | The total number of query strings processed while the import task was running.
 | Total IPs resolved | Total number of Internet Protocols (IPs) resolved during this DTS IP Resolution task.
 | Total IPs unresolved | Total number of IPs unresolved during this DTS IP Resolution task.
 | Provider: Total SetColumns | The total number of times SetColumns() has been called.
 | Provider: Committed rows per second | The number of rows stored per second.
CS2000: Marketing and Catalog | DML: Direct Mail errors per second | The number of errors returned by Direct Mailer per second.
 | DML: Direct Mail jobs running | The total number of Direct Mailer jobs currently running.
 | DML: Mail Messages sent/second | The number of mail messages sent, by all Direct Mailer jobs per second.
 | DML: Total Direct Mail errors | The total number of errors returned by all Direct Mailer jobs.
 | DML: Total messages sent | The total number of mail messages sent by all Direct Mailer jobs.
 | EEE: Evaluations/second | The number of expressions evaluated per second.
 | EEE: Expression Cache Size | The total number of expressions currently in the expression cache.
 | EEE: Property Cache Hits | The total number of property cache hits since the server started.
 | EEE: Property Reads | The total number of properties read by the Expression Evaluator since the server started.
 | EEE: Property Reads/second | The number of properties read per second by the Expression Evaluator.
 | EEE: Result Cache Hits | The total number of cache hits since the server started.
 | EEE: Total Evaluation Errors | The total number of evaluation errors returned.
 | EEE: Total Evaluations | The total number of evaluations returned since the server has been up, including both successful and erroneous evaluations.
 | LRUCache: Cache size | The total number of entries in the cache. Cache size can grow to 10 percent more than the size set by the user, at which time a flush will occur to bring the cache size back to the preset limit. LRUCache counters are grouped by site, not by the individual cache.
 | LRUCache: Flushes/sec | The number of items flushed out of the cache per second to accommodate new items added to the cache. Records items flushed by the LRU algorithm and items flushed manually.
 | LRUCache: Hits/sec | The number of cache hits per second for the cache.
 | LRUCache: Misses/sec | The number of cache misses per second for the cache.
 | Predictor: Total Model Loads | The number of models loaded since the service was last restarted.
 | Predictor: Client Avg Prediction Time | The average elapsed time required for a prediction to be returned.
 | Predictor: Client Model Loads From File | The number of times an analysis model is loaded from a file.
 | Predictor: Total Client Predictions | The total number of predictions.
CS2000: Pipelines | Average execution time | The average execution time in microseconds for the particular component of the pipeline.
 | Errors total | The total number of Error Level 3 failures returned by the particular pipeline component (PIPEERRORLEV_FAIL) or FAILED HRESULT.
 | Errors per second | The number of errors generated by the particular pipeline component per second.
 | Execution total | The total number of times the particular pipeline component has been executed.
 | Executions per second | The number of executions made by the particular pipeline component per second.
 | Warning total | The total number of Error Level 2 warnings returned by the particular pipeline component (PIPEERRORLEV_WARN).
 | Warnings per/second | The number of warnings returned by the pipeline component per second.

Notes

  • For the Data Warehouse and Analysis object, Data Warehouse performance counters are used only when importing data groups such as DTS tasks, users, and catalogs. For this reason, the Data Warehouse performance counters need to be set up as anonymous servers.

  • For the CS2000: Pipelines object, one instance of each pipeline counter exists for the entire pipeline.

AuthChecks Failed/sec

The AuthChecks Failed/sec counter is the number of failed authorization checks per second. This counter rate is incremented when the IsAuthenticated() function fails. It can fail when there is no AuthTicket in the cookie or when the AuthTicket that is in the cookie has expired.

AuthFilter: Token-Cache-Size

The Token-Cache-Size counter is the number of user tokens stored in the filter cache. This number can be changed in the SiteConfig object in the Microsoft Management Console (MMC). You would change this number if the server has sufficient Random Access Memory (RAM) and the site is frequently visited by a large number of diverse users in a short period of time.

Catalog Queries per Second

The Catalog Queries per second counter is the rate of queries per second through the CS2000: Marketing and Catalog object on a server. These queries include all category and product related queries as well as free text search. You can reduce queries made to the Product Catalog System by using a product cache or search cache to improve performance. Free text search can also be tracked with the Microsoft search>queries/sec counter.

The catalog query rate is the uncached rate. If this rate is high, then the application code should be changed to take advantage of a local caching mechanism, such as the LRUCache counter.

DML: Direct Mail Jobs Running

The Direct Mail jobs running counter measures the concurrent job count. There is no specific synchronization method in this service. More concurrent jobs may or may not generate more throughput.


Monitoring the Predictor Resource

You can use performance counters to monitor the performance of the Predictor resource. The Predictor resource has four performance counters, one (the Client Avg Prediction Time counter) that allows you to measure how fast predictions are occurring, and three others that count how often certain operations on the PredictorClient object are being called.

Predictor resource performance counters are only available on computers where the PredictorClient object is used, such as your Web servers. Each counter is aggregated on a per-site basis, so that if you have multiple instances of the PredictorClient object active in a single site, the total number of counters will be totals for the entire site.

The following table lists the performance counters available in the Predictor resource.

Counter | Description
Client Avg Prediction Time | Use this counter to determine the average time it takes for a prediction to be returned. You are provided with an estimate of how much time is being spent each time you call the PredictorClient object. You can also use this counter without inserting timing code on the Active Server Page (ASP) page. Other uses for this counter are to test how asking for more predictions (by increasing the value for the lMaxPredictions object) affects performance, or to compare the performance of the Predict method on the PredictorClient object for different models. This counter makes measurements in milliseconds.
Client Model Loads From File | Use this counter to determine the number of times an analysis model is loaded from a file using the LoadModelFromFile method.
Total Client Model Loads from Database | Use this counter to determine the total number of times an analysis model is loaded from a server using the LoadModelFromDB method.
Total Client Predictions | Use this counter to determine the total number of client predictions. This counter is useful for keeping track of how often the Predict method on the PredictorClient object is being called.

See Also

Commerce Server Performance Counters

Hardware Performance Counters


Optimizing Commerce Server

You analyze and optimize the system performance of Microsoft Commerce Server 2000 to ensure that your Web site can handle necessary levels of Internet traffic. To optimize your system, you must first analyze your current system and transactions, and then determine how many users concurrently use your site during normal and peak periods. You can then begin making adjustments in your system to optimize performance.

This section contains:

  • Analyzing Your Current System. Describes how to analyze your system and improve site capacity.

  • Using Transaction Cost Analysis. Describes how to measure the cost of different types of Web transactions on your site in order to increase performance.

  • Managing Performance. Describes tuning and optimizing methods for Commerce Server performance.

  • Troubleshooting Performance. Lists common problems that may occur while using Commerce Server optimization tools. Provides additional resources for troubleshooting other areas of Commerce Server.

  • Additional Optimizing Information. Lists online and print resources as well as tools for optimizing Commerce Server.


Analyzing Your Current System

Analyzing your current system configuration can help you better understand how it affects overall system performance. After you have analyzed your site, you can use the information you gathered to tune and scale all areas of your site. For example, you may want to change the configuration, adjust the way the software works, or improve the hardware.

As you tune and scale your site, you may need to make changes to your current configuration. You must know the current configuration of your system in order to accurately determine the affect a change in configuration has on performance. Analysis of the baseline configuration of your system should include an assessment of the following:

  • Hardware: Inventory each computer configuration, including boards, peripherals (excluding mouse or keyboard), and network devices. Create a system diagram to show how parts are logically connected and what purpose they serve. For example, indicate whether a server is a Web server or a database server. The following figure shows an example hardware diagram.
Hardware configuration diagram
Seagate ST32272A 2.2-GB Drive Seagate ST38422A 8.6-GB Drive
Seagate ST32272A 2.2-GB Drive Seagate ST38422A 8.6-GB Drive
2 LDAP Servers
2x PII 400, 512 MB 100-MB NIC
Compaq
RAID Array 3000
SQL Server
4x Xeon 400, 512 MB 100-MB NIC
Seagate ST32272A
2.2-GB Drive
Web Servers
2xPII 400, 512 MB 2x100-MB NIC
NLB
Windows 2000
Internet
Client
NLB
NLB
100 Base T
T1 Connection
Web Servers
2xPII 400, 512 MB 2x100-MB NIC

  • Software. Describe the software used on each computer and how it interacts with software on other computers. When documenting the software installed on each computer, include the following:
    • Build numbers.

    • Logical interface between applications. For example, if an application is retrieving data from a table in a database, describe that relationship.

    • Service packs.

    • Setup options used when installing the software.

    • System settings, such as virtual memory configuration.

    In addition to describing your software configuration, create a software diagram. The following figure shows an example software diagram.

Software configuration diagram
NLB
3 Browse Servers
Internet Explorer 5.5 Windows 2000
Commerce Server 2000
2 LDAP Servers Internet Explorer 5.5 Commerce Server 2000 Windows 2000
Windows 2000
SQL Server 2000
3 Shop Servers
Internet Explorer 5.5
Windows 2000
Commerce Server 2000
Windows 2000
Internet
Client
NLB
NLB
100 Base T
T1 Connection

  • Content. Describe the content that has been added to each type of server since Commerce Server 2000 was installed. For example, you should document each file and the directory structure in which files are stored on Web servers and database servers. You should also document information, such as permission settings, for the file system, database scripts, configuration files, data files, and so on.

  • Load balancing. Describe any places where you are using Network Load Balancing (NLB). For example, have you scaled your site across multiple servers using NLB or hardware load balancing?


Using Transaction Cost Analysis

Transaction cost analysis (TCA) is a method of measuring site capacity. TCA can measure the performance cost of a transaction, how much traffic your Web site can handle, and the cost of performing various types of transactions on your site. You use TCA to measure the capacity of your site and then use the results to increase the capacity of each system component. You can also compare server transactions with one another to determine which ones are putting the greatest demands on your system.

The term transaction in TCA refers to work done by a server or servers (Web servers, middle–tier servers, and SQL Servers) to fulfill a user request. For example, a user request for a product description page stored in a database is a transaction, as is a request to add an item to a shopping basket. This term does not refer to e-commerce transactions in which money is exchanged.

Analyzing Traffic

Creating a Usage Profile

Measuring Site Capacity

Increasing Web Site Capacity

Increasing Middle-Tier Capacity

Increasing Database Capacity

Analyzing Traffic

After you have analyzed your current system and documented your hardware and software, you must determine how many users typically use the site concurrently. This data usually comes from:

  • Market analysis. Analysis of a new site. You may have commissioned a market analysis report to predict how much traffic your site can expect to receive at the time it is deployed and afterward. Use this report as the baseline configuration for your TCA.

  • Site usage analysis. Analysis of an existing site. Analyze your Web server log files to see how many hits your site receives at any given time, as well as usage trends that might indicate whether parts of the site have become more or less popular over time. When calculating how many concurrent users your site currently supports, remember to base your calculations on peak usage, rather than on typical usage.

Creating a Usage Profile

After you know how many users are using your site, you must then determine how they use it so that you can estimate how much demand a typical user places on the system. You should create a usage profile so that you will have a baseline to start from.

You need to analyze the usage log files of your site to create a usage profile. If you have logs gathered over a long period of time (at least a week) use them to get accurate averages. First, identify the operations that a user can do (browse, search, and so on). Next, gather the following data:

  • Number of users to the site

  • Number of hits each page receives (which pages have been visited)

  • Time spent on each page

  • Session length

  • Peak periods of activity

You can use the number of visits to each page to profile typical user operations for your site. The following table shows a usage profile with typical shopper operations for an e-commerce retailer.

Shopper operation | Operations per session | Operations per second (transaction frequency) | Percentage of total
Add Item | 0.24 | 0.00033 | 2.00
Add Item + Checkout | 0.02 | 0.00003 | 0.17
Add Item + Delete | 0.04 | 0.00006 | 0.33
Basket | 0.75 | 0.00104 | 6.25
Default (home page) | 1.00 | 0.00139 | 8.33
Listing | 2.50 | 0.00347 | 20.83
Lookup | 0.75 | 0.00104 | 6.25
New | 0.25 | 0.00035 | 2.08
Product | 4.20 | 0.000583 | 35.00
Search | 1.25 | 0.00174 | 10.42
Welcome | 1.00 | 0.00139 | 8.33

Measuring Site Capacity

The following table lists three tiers of servers that you need to consider when measuring site capacity.

Tier | Type of server
Top tier | Web servers
Middle tier | Business or other application servers, content servers
Bottom tier | Database servers

Increasing Web Site Capacity

After measuring the capacity of your system, you may discover that your current system cannot handle the amount of traffic that you are currently experiencing on your Web site. Or, you may be concerned about an upcoming surge in traffic for a new marketing initiative or a seasonal surge, such as Back-to-School or Christmas.

To prevent a lapse in performance, you need to test the expected traffic level on your Web servers to accurately determine where to scale servers to meet the anticipated load. (Performing calculations to determine how many servers to add may work, as long as capacity problems are isolated to one tier.) You can use System Monitor to monitor the counter values for different server objects. You can use the specific Commerce Server performance counters to view the server objects important to your business. For more information about System Monitor, see Windows 2000 Server Help.

To increase capacity, you should determine which resources are depleted. Doing an accurate TCA will also help increase capacity. You can scale the Web servers vertically by increasing the memory, CPU, or network capacity. Another way to increase the capacity of the Web servers is to add more servers to the load-balanced cluster. However, it is critical to have a strong understanding of the capacity of the whole Web farm before making a decision to scale a single component.

See Also

Using Transaction Cost Analysis

Commerce Server Performance Counters

Increasing Middle-Tier Capacity

You can use middle-tier servers for a variety of purposes, such as running applications or storing content. To evaluate performance of your middle tier you should monitor the following performance counters:

  • Memory

  • System

  • Physical disk

If the values for these counters are inadequate, then you should scale this tier. For example, when monitoring the Bytes received per second counter, you should compare this counter to the total bandwidth of your network adapter card to determine whether your network connection is creating a bottleneck. It is recommended to use 50 percent or less of existing capacity to increase room for spikes in visitor traffic. If this number is very close to the capacity of the connection, and processor and memory use are moderate, then the connection might be the problem.

Network Load Balancing (NLB) brings together several computers running server programs using the TCP/IP networking protocol. You can use NLB with a group of Terminal servers to scale the performance of a single Terminal server by distributing its client requests across multiple servers. However, there are limitations when using load balancing with Terminal servers. This is because individual users can connect to different Terminal servers within a group, or user sessions might become broken when redistributed to another Terminal server. You must ensure that user information and preferences remain accessible to users in order to use Terminal Services with load balancing.

You may also want to incorporate documentation that discusses performance issues specific to the technologies you are using on this tier to find ways to increase middle-tier capacity. For example, Windows 2000 Server Help provides information about using Network Load Balancing (NLB) to permit access to additional servers, which could increase capacity.

For more information about NLB, see "Network Load Balancing and Terminal Services" and "Component Services (COM+)" in Windows 2000 Server Help.

Increasing Database Capacity

In order to increase your database capacity, you must first monitor the following performance counters:

  • Memory

  • System

  • Physical disk

  • SQL Server

After monitoring these counters, you will have a better idea if you need to add memory, physical disk space, or servers. You can increase database capacity by adding a new server. It is easier to add a new server than to move an application that is sharing a database server to a new server. However, increasing capacity is not always a simple matter of adding another server. Review the documentation for your database application for guidelines on scaling the database.


Managing Performance

Managing the performance of your Commerce Server 2000 site largely consists of finding and removing bottlenecks. A bottleneck is hardware or software that is operating at maximum capacity. As the load approaches maximum capacity, the bottleneck begins to restrict the flow of work through the system. Performance tools can help you determine what hardware or software has reached a bottleneck. You can then improve the hardware, change configuration, or tune the software to improve overall performance.

Performance is only one factor in optimizing your Commerce Server site. Other important factors include ease of development and maintenance, time to market, availability of good programming tools, and in-house site developer expertise. Optimizing for performance can affect any of these other factors.

Web development is driven by a business case that determines priorities. For example, project goals might specify a particular programming language or data-access technology, and such decisions always affect performance to some degree. It is extremely important to determine a necessary level of performance appropriate to your Web site, then develop the site and manage it to that level of performance.

Web sites often run on multiple physical tiers, each of which has its own hardware, system software, and application software. As a result, Web applications can have many types of performance problems: hardware (client computer, Web server, database server, the network), system software (operating systems, networking software, system services), client applications, browsers, logical database, physical database, data access, and so on.

You can use the following questions to help determine your performance tuning goals:

  • Will the performance of this site meet our goals today and in the future?

  • Can we expect our current configuration to become a bottleneck?

  • How many users can our site support?

Monitoring performance regularly is the only way to be sure that the site is meeting specified performance goals. Regular performance monitoring can provide an early warning when a change degrades performance. You can collect performance data using existing system tools, having the site monitor report on its own performance, or by building special client applications to drive the system.

When you tune performance, you should measure system performance first to see if it meets your goals. If performance doesn’t meet your goals, find the bottleneck, remove it, and then repeat the process until you reach your performance goal. You can always increase performance further, but when site performance meets your goals, additional tuning is generally not cost-effective.

This section contains:

  • Tuning Your System

  • Monitoring and Maintaining Logs

  • Monitoring Performance Counters

See Also

Monitoring Commerce Server Sites


Tuning Your System

Maintaining a Web site requires that you keep your system tuned for maximum performance. Review the latest tuning guidelines for your technology periodically to ensure that your computer systems are running as efficiently as possible. You can find information about tuning your system in the Commerce Server 2000 Resource Kit.


Monitoring and Maintaining Logs

Monitoring your system logs on a regular basis can help you avoid catastrophic failures and prepare you for unexpected increases in server activity.

  • At least twice a day, use Event Viewer to review event activity and inform interested parties about any anomalies.

  • At least once a week, analyze the Internet Information Services (IIS) 5.0 logs for changes in user-access trends. Ensure that the traffic to your Web site is within the system limitations. You might also want to reconfigure your Web pages or product offerings based on the trend analysis.

  • Back up and truncate your database logs on a regular schedule. You should copy database logs to an external backup device, such as a tape drive, before deleting them.

  • Enlist help from an external analysis agent, such as Keynote Systems, to monitor the page latency of your site from many remote locations.

See Also

Monitoring Commerce Server Sites

System Monitor

Using the Event Viewer Snap-In


Monitoring Performance Counters

Performance counters allow you to monitor specific aspects of work performed on your system. System Monitor groups counters by object type. A unique set of counters exists for Commerce Server processes, memory, cache, hard disk, and other object types that produce statistical information. For more information about Commerce Server performance counters and how they are used, see Monitoring Commerce Server Sites. For more information about System Monitor, see Windows 2000 Server Help.

See Also

Monitoring Commerce Server Sites

Hardware Performance Counters

Commerce Server Performance Counters

Setting up Performance Counters


Troubleshooting Performance

This topic describes methods you can use to troubleshoot Commerce Server and improve system performance.

This section contains:

  • Stopping Unnecessary Applications

  • Monitoring Production Servers

  • Using Consistent Server Configurations

  • Testing Tips

  • Migrating from Site Server

  • Tuning Windows 2000 Servers

  • Finding Specific Performance Problems

  • Using Memory

  • Monitoring Key Performance Counters

  • Turn Off Anonymous Profiling

  • Changing IIS Performance Tab Settings

  • Disable Debug Trace Messages


Stopping Unnecessary Applications

If an application is not needed to perform the primary functions of a server, do not install it. Even installing an application temporarily and then uninstalling it can cause problems if there is an incompatible dynamic-link library (DLL) on your server. You should stop any applications that are not needed.


Monitoring Production Servers

It is recommended that you use a separate server that is not part of the run-time services to monitor the production servers in your Web farm. It is important to monitor your servers from a separate server because you do not want the process of monitoring to affect the performance or operation of a production server. If you use a separate server, you will get a more accurate measurement of the true performance of your production servers.

In addition, monitoring user traffic should take place on a separate administrative network—separate from the network that handles the actual data processing traffic. System Monitor, as well as other monitoring tools, can aggregate the data from many servers into one collective view with this process. It also reduces the disk input/output (I/O) on the Web and database servers, which is necessary to log this information.


Using Consistent Server Configurations

Servers that perform the same function should have the same software configuration. For example, all Web servers should have the same software configuration (but not necessarily the same configuration as the database servers). Having the same software configuration provides the following benefits:

  • Identical and expectable performance — assuming the hardware is also consistent.

  • Upgrading software is easier.

  • Any improvements made to one server should improve all servers.


Testing Tips

Always perform real-world testing in a test environment with the production configuration before making changes to your production site to improve performance. Performing module tests or tests on development systems will not give you the same results as testing the full configuration under normal and peak traffic. You must not change anything on production without a full test. The following are basic guidelines for testing:

  • Test each Web page to ensure that the content is correct, the links work, the results you want are returned, and the performance is what you expect.

  • Test the system using peak traffic conditions to ensure that it can handle the maximum amount of traffic you have on the system. Use tools such as Microsoft Web Application Stress (WAS) and System Monitor to assist you.

  • Verify response time by bringing up the most complex Web pages under normal traffic, while accessing your Web site remotely using different speed connections.


Migrating from Site Server

If your Web site is based on Site Server 3.0 Commerce Edition (SSCE), you need to plan how to migrate your application. Site Server works on the Microsoft Windows 2000 platform with the use of Site Server 3.0 Commerce Edition Service Pack 4. For a detailed, step-by-step description of how to migrate from Site Server 3.0 or Site Server 3.0 Commerce Edition to Commerce Server 2000, see the Commerce Server 2000 Resource Kit. This resource kit also contains tools that will help you complete the migration.

To understand how to properly prepare for migration, see Migrating from Site Server 3.0.


Tuning Windows 2000 Servers

To tune Microsoft Windows 2000 servers, make the following adjustments:

  • If you have installed additional components, such as Chat services, Bulletin Board Systems, or other unnecessary components, uninstall them according to the software uninstall instructions.

  • Change the performance of foreground and background programs. For more information, see the following To change performance to Background services procedure.

  • Maximize throughput for network applications. For more information, see the following To maximize throughput for network applications procedure.

To change performance to Background services

  1. On the Windows 2000 desktop, right click My Computer and select Properties.

  2. Click on the Advanced tab and then click the Performance Options button.

  3. Under Application response, click Background services.

  4. Click OK, and then click OK again.

To maximize throughput for network applications

  1. On the Windows 2000 Desktop, right click My Network Places and select Properties.

  2. Right click on Local Area Connection and select Properties.

  3. Under Components checked are used by this connection, select File and Printer Sharing for Microsoft Networks.

  4. Click the Properties button and select Maximize data throughput for network applications.

  5. Click OK, and then click OK again.

Also, consider the following:

  • Commerce Server 2000 and Active Server Pages (ASP) tend to use up the CPU resources.

  • SQL Server is likely to use up the memory or disk resources first.

  • Hypertext Transfer Protocol (HTTP) uses more network resources than anything else.


Finding Specific Performance Problems

System throughput problems usually occur when the demand for resources exceeds supply. Isolating performance problems starts with determining how users, Commerce Server 2000, and the operating system interact with each resource. You can learn a lot about a system by seeing how various applications use memory.

To begin this task, generate detailed success criteria for concurrent users in the planning phase of the Web site architecture. Determine a usage profile for a typical user visit based upon previous experience or user analysis. This data should provide a download size, throughput, and latency goal for each page.

Site developers should test the ASP pages that they create with a load simulation tool, such as the Microsoft Web Application Stress (WAS) tool, and track these results versus goals. When these pages pass the single server configuration goal, you should plan a milestone for distributed server testing that is more similar to the data center configuration. In particular, you should have the client simulator, Web server, and back-end systems on separate computers. The Web server and back-end systems should be symmetric multiprocessing (SMP) servers if they are going to be deployed as such in the data center.

Next, you should attempt to reduce page request latency. The first item to look at for performance improvements is the requests to the SQL Servers. The SQL Server Profiler tool that comes with Microsoft SQL Server 2000 has a wizard that recommends indices for tuning the database. This tool can be very useful to test frequent page operations. If you are using Microsoft Active Directory server you may also want to monitor its activity. The NTDS object performance counters on the Active Directory server will help define the use of this server component.

After you understand how the data is accessed, you should investigate the page logic. There are a number of tips for tuning that are specific for Active Server Pages (ASP) programming. Each ASP page can realize a significant throughput gain by following these steps correctly.

If the page latency is too long because there are too many calls for data, you can use the Commerce Server LRUCache object. This object can reduce expensive calls for data by retaining the rendered HTML fragment, thus eliminating the query to the back-end server.

Finally, for small tweaks in performance and throughput, try tuning the registry settings within Internet Information Services (IIS) 5.0 and Microsoft Windows 2000. Be aware that these changes will not have the same impact on performance as changing the algorithm or access methods in the site code. For example, you can tune performance on the IIS server by changing the IIS Performance tab settings to More than 100,000 and confirming that ASP debugging is not enabled.

See Also

Changing IIS Performance Tab Settings

Commerce Server Performance Counters

Other Performance Monitoring Tools


Using Memory

Memory usage is perhaps the most important factor in system performance. When memory demand exceeds supply, Microsoft Windows 2000 Server moves blocks of code and data, called pages, from random access memory (RAM) to disk to free up space for a process. Some paging is acceptable because it enables Windows 2000 Server to use more memory than actually exists in physical memory (RAM). Constant paging, however, is a drain on system performance.

When you start Windows 2000 Server, it automatically creates a paging file (Pagefile.sys) on your system. Windows 2000 Server uses the paging file to provide virtual memory. The recommended size for the paging file is equivalent to the amount of RAM available on your system plus 12 megabytes (MB). However, the size of the file also depends on the amount of free space available on your hard disk when the file is created. For information about scalability, see the Commerce Server 2000 Resource Kit.


Monitoring Key Performance Counters

You can discover system bottlenecks by monitoring key performance counters during peak periods. For information about the Commerce Server performance counters you should monitor, see Commerce Server Performance Counters.

See Also

Setting Up Performance Counters


Turn Off Anonymous Profiling

Commerce Server 2000 makes profiling of the guest user easy. However, the cost of tracking all guest users at very large Web sites can be costly. Carefully weigh the benefits gained from creating cookies and unique instances in your databases and Microsoft Active Directory servers before implementing this feature. Many of the benefits gained from this feature can be realized by more careful analysis of the Commerce Server reports.

See Also

Commerce Server Reports


Changing IIS Performance Tab Settings

You can change the Microsoft Internet Information Services (IIS) 5.0 Performance tab settings to increase performance.

To change the IIS Performance Tab settings

  1. Click Start, point to Programs, point to Administrative Tools, and then click Internet Services Manager.

  2. In the Internet Information Services screen, expand the nodes to the following path: Internet Information Services/<Server Name>/Default Web Site.

  3. Right-click Default Web Site and select Properties.

  4. Click the Performance tab.

  5. Move the Performance Tuning slider to the right to More than 100,000, and then click OK.


Disable Debug Trace Messages

One simple change you can make to improve performance is to ensure that debug trace messages are disabled in your production system. Tracing can sometimes result in 10 to 15 percent degradation in throughput for some scenarios.

To disable debug trace messages

  1. Click Start, and then click Run.

  2. In the Run dialog box, in the Open box, type Regtrace.exe, and then click OK.

  3. In the Trace Settings dialog box, select the Traces tab, clear the check boxes for all levels of tracing, and then click OK.

Note

  • It is not sufficient to select No Tracing on the Output tab. You must first clear the check boxes for all trace levels.

See Also

Using regtrace.exe with a debugger

Performance Optimizing Tools


Additional Optimizing Information

There are additional resources available for you to use to help you optimize the performance and capacity of your Commerce Server 2000 site.

This section contains:

  • Performance Optimizing Tools

  • Web-based Information

  • Published Books


Performance Optimizing Tools

Microsoft offers a numbers of tools for performance tuning and testing. Some of these tools are included with Microsoft Windows 2000 and Internet Information Services (IIS) 5.0, others are on the Windows 2000 Server Resource Kit companion CD, and others are available on the Microsoft Web site (www.microsoft.com). For example, the System Monitor (formerly known as Performance Monitor) is built into Windows 2000 and is essential to monitoring nearly every aspect of server performance.

The following section lists brief descriptions of performance optimizing tools and how to access them.

  • Microsoft Web Application Stress Tool. A simulation tool developed by Web testers to realistically reproduce multiple browsers requesting pages from a Web application. Microsoft has made the tool easy to use masking some of the complexities of Web server testing. This makes the tool useful for anyone interested in gathering performance data on a Web site. The tool is a consolidation of many of the best features developed over the years, as well as a few new features. This version covers the most needed features for stress testing three-tiered, personalized Active Server Pages (ASP) Web sites running on Microsoft Windows 2000.

    To download WAS see, http://webtool.rte.microsoft.com.

  • Network Monitor. A tool that captures network traffic for display and analysis. You can use Network Monitor to perform tasks such as analyzing previously captured data in user-defined methods, extracting data from defined protocol parsers, and analyzing real-time traffic on your network. Network Monitor is useful tool for capturing packets between browsers, Web servers, and SQL Server. It provides valuable timing information as well as packet size, network utilization, and many other statistics that can be valuable for managing system performance.

  • SQL Server Profiler. A tool that captures SQL Server events from a server. The events are saved in a trace file that you can analyze later or use to replay a specific series of steps when trying to diagnose a problem. You can use SQL Server Profiler to:
    • Step through problem queries to find the cause of the problem.

    • Find and diagnose slow-running queries.

    • Capture the series of SQL statements that lead to a problem. The saved trace can then be used to replicate the problem on a test server where it can be diagnosed.

    • Monitor the performance of SQL Server to tune workloads.
  • System Monitor. A tool you can use to collect and view extensive data about the way in which hardware resources are used and the activity of system services. You can use System Monitor to:
    • Collect and view real-time performance data on a local computer or from several remote computers.

    • View data in a counter log that is either being collected currently or was collected previously.

    • Present data in a printable graph, histogram, or report view.

    • Incorporate System Monitor functionality into Microsoft Word or other applications in the Microsoft Office suite by means of automation.

    • Create HTML pages from performance views.

    • Create reusable monitoring configurations that can be installed on other computers using the Microsoft Management Console (MMC).
  • Visual Studio Analyzer. A tool you can use to analyze performance, isolate faults, and understand the structure of your distributed applications. You can use Visual Studio Analyzer with applications and systems built with any of the Visual Studio tools. Several Microsoft technologies, such as Component Object Model (COM), Microsoft ActiveX Data Objects (ADO), and COM+, are shipped with the ability to provide information to Visual Studio Analyzer. If your applications use any of these technologies, you can get detailed information about this use from Visual Studio Analyzer. In addition, you can customize your own applications to provide information to Visual Studio Analyzer.

  • Process and Thread Status (Pstat.exe). A tool that shows the status of all running processes and threads. You can find this tool on the Windows 2000 Server Resource Kit companion CD.

  • Process Tree (Ptree.exe). A tool that allows you to query the process inheritance tree and delete processes on local or remote computers. You can find this tool on the Windows 2000 Server Resource Kit companion CD.

  • HTTP Monitoring Tool. A tool that monitors HTTP activity on your servers and can notify you if there are changes in the amount of activity. You can find this tool on the Windows 2000 Server Resource Kit companion CD.

  • NetStat. A command line tool that detects information about the current network connections of your server. You can find NetStat on the Windows 2000 Server Resource Kit companion CD.

See Also

Commerce Server Performance Counters

Setting Up Performance Counters


Web-based Information

The following table describes documentation that you can find on the Web to help you optimize the performance and capacity of your Commerce Server 2000 site.

Title | Description
Microsoft Developer Network (MSDN) | Contains information about Commerce Server 2000 and other Microsoft .NET Enterprise Servers. You may find it helpful to visit this site on a regular basis. Search MSDN, and enter Commerce Server 2000 to find related documents and white papers. www.msdn.microsoft.com
The Art and Science of Web Server Tuning with Internet Information Services 5.0 | A white paper which describes the issues and approaches involved in tuning a Web server when running Internet Information Services (IIS) 5.0 on Windows 2000 Server. It discusses the importance of monitoring and testing, as well as potential hardware, software, and tool issues that may arise. There is a section on new or changed IIS and Windows 2000 settings and features, and there are a number of appendixes that list useful tips, registry and metabase settings, and resources for your reference. While this document is written specifically for IIS 5.0, much of this material may also be useful for IIS 4.0 administrators. www.microsoft.com/windows2000/library/operations/web/tuning.asp
Commerce Server Software Development Kit (SDK) | Contains technical information for developers creating programs or intelligent Web pages that must integrate with the Commerce Server application programming interface (API). The SDK contains a guide for programmers and references to various Commerce Server and commerce technologies. It also includes samples and header files that you can use to create your own programs.
TechNet | Contains technical information and tools designed to help you plan, develop, deploy, and manage your e-commerce Web sites. For information about Commerce Server, select Commerce Server from the Navigate by Product menu on the left side of the screen. www.microsoft.com/technet/
Newsgroups | Use peer-to-peer newsgroups to talk about Commerce Server with other administrators, developers, and Microsoft Most Valuable Professionals (MVPs). Microsoft does not monitor or support the content of these newsgroups or sites. www.microsoft.com/commerceserver/support/NewsGrps.htm
Microsoft Support | A list of support options available for Commerce Server. www.microsoft.com/commerceserver/support/
Microsoft Servers site | A guide to the full range of Microsoft server products for IT professionals, developers, and Internet professionals. www.microsoft.com/servers/


Published Books

The Commerce Server 2000 Resource Kit book contains technical information and tools designed to help you plan, develop, deploy, and manage your e-commerce Web site. It is available from Microsoft Press.


User Interface Reference

This section contains the context-sensitive help topics for resources available from Commerce Server Manager, and for Commerce Server Site Packager. These topics are available from the user interface by pressing the F1 key or by clicking Help in Commerce Server Manager dialog boxes.

This section contains:

  • Data Warehouse UI Help. Provides dialog box help for the Data Warehouse.

  • DTS Task UI Help. Provides dialog box help for the Commerce Server DTS tasks.

  • Predictor Resource UI Help. Provides dialog box help for the Predictor resource.

  • Profiles Resource UI Help. Provides dialog box help for the Profiles resource.

  • Site Packager UI Help. Provides dialog box help for Commerce Server Site Packager.


Data Warehouse UI Help

This section contains the context-sensitive help topics for the Commerce Server Data Warehouse resource. These topics are available from the Data Warehouse resource user interface by clicking Help in Data Warehouse resource dialog boxes.

This section contains:

  • Data Warehouse Properties, Connection Tab

  • Data Warehouse Properties, Time Tab


Data Warehouse Properties, Connection Tab

The following table shows the options and functions available on the Connection tab of the Data Warehouse Properties dialog box.

Use this | To do this
SQL Server Authentication | Select this option to use a supplied user name and password to authenticate your logon information.
User ID | Type the User ID to use for authentication when you log on.
Password | Type the password to use for authentication when you log on.
Server | View the name of the connected server.
Database | View the name of the connected database.
OLAP Server Properties: Server | View the name of the connected OLAP server.
OLAP Server Properties: Database | View the name of the connected OLAP database.

See Also

Configuring the Data Warehouse Resource


Data Warehouse Properties, Time Tab

The following table shows the options and functions available on the Time tab of the Data Warehouse Properties dialog box.

Use this | To do this
Adjust time zone to | Select a time zone from the drop-down list.
Start day of the week | Select the start day of the week from the drop-down list.

See Also

Configuring the Data Warehouse Resource


DTS Task UI Help

This section contains the context-sensitive help topics for the Commerce Server Data Transformation Services (DTS) tasks. These topics are available by clicking Help in Commerce Server DTS task dialog boxes.

This section contains:

  • Import Web Server Logs

  • Advanced Web Log Import Properties, Excludes Tab

  • Excludes

  • Advanced Web Log Import Properties, Inferences Tab

  • Advanced Web Log Import Properties, Query Strings Tab

  • Query Strings

  • Advanced Web Log Import Properties, Default Files Tab

  • Advanced Web Log Import Properties, Log Files Tab

  • Catalog Import Properties

  • Transaction Import Properties, General Tab

  • Transaction Import Properties, Import Options Tab

  • Delete Task

  • IP Resolution Properties

  • Campaign Import Properties

  • User Import Properties

  • Synchronize DW Properties

  • Prepare Reports Properties

  • Web Server Log Files


Import Web Server Logs

The following table shows the options and functions available in the Import Web Server Logs dialog box.

Use this | To do this
Description | Type a description for the import task.
Site name | Select the Web site from the drop-down list that contains the Web server log you are importing.
Application | Click to sort the list of log files by application.
Machine (Computer) | Click to sort the list of log files by computer.
IIS Web Site | Click to sort the list of log files by IIS Web site.
Log File Path | Click to sort the list of log files by log file path.
Log file path | Type the path for the Web log file you want to import or click the ellipsis [...] button to browse for the log file path.
View Log Files | Click to open the Web Server Log Files dialog box, select the Web log files you want to import from the Web Server Log Files list, and then click OK to return to the Import Web Server Logs dialog box.
Import all log files since last import | Select to specify that all log files created since the last import are to be imported.
Import log files based on date/time range | Select to specify that only log files created between the start date/time and end date/time will be imported.
Start date/time | Type the date and time for the beginning of the range from which log files will be imported. This option is only available if you select the Import log files based on date/time range option.
End date/time | Type the date and time for the beginning of the range from which log files will be imported. This option is only available if you select the Import log files based on date/time range option.
Advanced | Click to open the Advanced Web Log Import Properties dialog box.

See Also

Importing Web Log File Data

Configuring Web Log Import Properties

Data Warehouse Components

Configuring the Data Warehouse Resource


Advanced Web Log Import Properties, Excludes Tab

The following table shows the options and functions available on the Excludes tab of the Advanced Web Log Import Properties dialog box.

Use this | To do this
Filter excludes by Select an exclusion type from the drop-down list to display only that type of exclusion. Exclusiontypes can be:
  • Hosts

  • File types

  • File expressions

  • Crawlers

For more information about exclude categories, see Excludes.
Include default crawler list for the exclude criteria | Select to include the default crawler list in the exclude criteria.
Exclude Type | Click to sort the excludes list by exclude type.
Exclude | Click to sort the excludes list by the criteria for the exclude type.
Application | Click to sort the exclusion list by application.
Add | Click to open the Excludes dialog box to add a new exclude.
Remove | Click to remove the selected exclude.
Properties | Click to open the Excludes dialog box in which you can view the properties of the selected exclude.

See Also

Excludes

Configuring Web Log Import Properties

Data Warehouse Components


Excludes

The following table shows the options and functions available in the Excludes dialog box.

Use this | To do this
Select exclude category Select the type of import exclusion you want to add from the drop-down list. You can exclude the following types of data:
  • Hosts

  • File types

  • File expressions

  • Crawlers

For more information about exclude categories, see Excludes.
Name | Type a name that Commerce Server can use to search the log files. Do not include spaces in the name you type.
All applications within a site | Select to exclude the data from all applications within a site.
Selected applications within a site | Select to select which applications within the site to exclude the data from.
Select all | Select to exclude the data from all of the applications listed.
Deselect all | Select to cancel the selection of all of the applications listed.

See Also

Excludes

Configuring Web Log Import Properties

Data Warehouse Components


Advanced Web Log Import Properties, Inferences Tab

The following table shows the options and functions available on the Inferences tab of the Advanced Web Log Import Properties dialog box.

Use this | To do this
Minutes of idle time to allow before visit ends | Type the number of minutes of idle time before a visit is considered ended. The default time is 30 minutes.
Use Commerce Server identification cookies for inferences | Select to use Commerce Server Identification cookies to distinguish individual users.
Use usernames for inferences | Select to use user names to distinguish individual users.
Use custom cookie identifiers | Select to use custom cookies to distinguish individual users.
Enter new custom cookie identifier | Type the identifier of the custom cookie you want to use.
Add | Click to add the new custom cookie identifier to the inference list.
Remove | Click to remove the selected line from the inference list.

See Also

Inferences

Configuring Web Log Import Properties

Data Warehouse Components


Advanced Web Log Import Properties, Query Strings Tab

The following table shows the options and functions available on the Query Strings tab of the Advanced Web Log Import Properties dialog box.

Use this | To do this
Save query string with URI | Select to save the query string with the Uniform Resource Identifier (URI).
Query String | Click to sort the list by query string name.
Application | Click to sort the list by application name.
Add | Click to open the Query Strings dialog box in which you can add a new query string.
Remove | Click to delete the specified query string.
Properties | Click to open the Query Strings dialog box in which you can edit the specified query string.

See Also

Query Strings

Configuring Web Log Import Properties

Data Warehouse Components


Query Strings

The following table shows the options and functions available on the Query Strings dialog box.

Use this | To do this
Name | Type a name for the query string.
All applications within a site | Select to import the query string from all applications within a site.
Selected applications within a site | Select to select which applications within the site to import the query string for.
Select data type | Select the data type from the drop-down list for the query. Data types to choose from are: String (default), Integer, Date/Time, and Real.
Multivalue data type | Select if the query will use a multivalued data type.

See Also

Query Strings

Configuring Web Log Import Properties


Advanced Web Log Import Properties, Default Files Tab

The following table shows the options and functions available on the Default Files tab of the Advanced Web Log Import Properties dialog box.

Use this | To do this
Truncate top level directory from file system paths | Select to display file name strings without their top-level directories.
Directory index file | Type the name of the file you want to designate as a directory index file.
Add | Click to add the new directory index file to the default file list.
Remove | Click to remove the selected directory index file from the default file list.

See Also

Default Files

Configuring Web Log Import Properties


Advanced Web Log Import Properties, Log Files Tab

The following table shows the options and functions available on the Log Files tab of the Advanced Web Log Import Properties dialog box.

Use this | To do this
Number of minutes that records must overlap | Type the number of minutes that records must overlap. The default overlap is 30 minutes.
If overlap is detected Select an action to take if an overlap is detected:
  • Import all records. Imports all requests, including overlapping requests.

  • Stop the import. Does not import the log file if overlapping requests are detected.

  • Stop all imports. Stops all log file imports if overlapping requests are detected.

  • Discard records and proceed (default). Discards all overlapping requests and imports the remaining requests.
When import is completed Select an action to take with the open visits at the end of your import process:
  • Store open visits for the next import (default setting). Reconstructs the actual visit as if there were one seamless log file. This option takes slightly more time because the open visits must be called up from the cache at each new import. You must import log files in chronological order for this option to work correctly.

  • Commit open visits to database. The visit count will be higher at the opening and closing of the log file period because visits that span those two periods will be counted twice.

  • Discard open visits. The report count will be lower at the closing of the log file period because visits that have not been closed will be dropped.
Clear Cache | Click to clear the cache of stored data.

See Also

Log Files

Time Overlaps

Log File Rotation

Configuring Web Log File Import Properties


Catalog Import Properties

The following table shows the options and functions available on the Catalog Import Properties dialog box.

Use this | To do this
Description | Type a description for this import task.
Site name | Select from the drop-down list the site that contains the data you want to import.
Incremental load | Select to only import new catalog data. (Based on a previous import.)
Full load | Select to import all catalog data.

See Also

Importing Catalog Data

Data Warehouse Components


Transaction Import Properties, General Tab

The following table shows the options and functions available on the General tab of the Transaction Import Properties dialog box.

Use this | To do this
Description | Type a description for this import task.
Site name | Select from the drop-down list the site that contains the data you want to import.
Incremental Load | Select to only import new transaction data. (Based on a previous import.)
Full load | Select to import all transaction data.

See Also

Importing Transaction Data

Data Warehouse Components


Transaction Import Properties, Import Options Tab

The following table shows the options and functions available on the Import Options tab of the Transaction Import Properties dialog box.

Use this | To do this
Transaction category Select the transaction category, from the drop-down list, of the dimensions you want to import from the following categories:
  • OrderFormHeader

  • OrderFormLineItems

  • OrderGroupAddresses

  • OrderGroup
Available dimensions | Select the dimension you want to add from the list.
Dimensions to import | Lists the dimensions for the specified transaction type that will be imported.
Add | Click to move the selected dimension from the Available dimensions box to the Dimensions to import box.
Remove | Click to remove selected dimensions from the Dimensions to import box.

See Also

Importing Transaction Data

Data Warehouse Components


Delete Task

The following table shows the options and functions available on the Delete Task dialog box.

Box | To do this
Description | Type a description for the delete task.
Site Name | Select the site from the drop-down list for which you want to delete Web log file data.
Select delete type Choose the delete type from the drop-down list:
  • All. Deletes all data (detailed and summarized) from the Data Warehouse.

  • Web Log Imports. Deletes data from selected Web log files.
Delete all data | Select to delete both summary and detail data from the selected Web log file imports.
Delete detail data | Select to delete only detail data from the selected Web log file imports
Task Id | Select the check boxes in this column to designate which Web log files you want to delete. Click the column heading to sort the Web log file list by Task Id.
Task description | Click the column heading to sort the Web log file list by description.
Status | Click the column heading to sort the Web log file list by status.
Start time | Click the column heading to sort the Web log file list by start time.
Detail level | Click the column heading to sort the Web log file list by detail level.

See Also

Deleting Data from the Data Warehouse


IP Resolution Properties

The following table shows the options and functions available on the IP Resolution Properties dialog box.

Use this | To do this
Description | Type a description for the task.
Site name | Select the site from the drop-down list for which IP Resolution will be performed.
Incremental lookup | Select to resolve only IP addresses that have not already been resolved.
Full lookup | Select to resolve all IP addresses.
Local domain name | Type the local domain name of the Domain Name Server (DNS) used as the primary server used to resolve IP addresses.
Number of days to cache result | Type the number of days to store resolved IP addresses. The default is 30 days. If you increase the default, IP resolution will occur more quickly. However, domain name changes may not be caught.
Number of seconds to wait before timeout | Type the number of seconds the DNS server will be searched before an IP address is marked as unresolved. The default is 60 seconds. If you increase the default, you will resolve more IP addresses, but IP resolution will take longer.
Number of lookup requests to keep in batch | Type the number of IP addresses that will be transferred to your DNS server in a batch. The default is 500; the possible range is 10 to 99,999.

See Also

Performing IP Resolution


Campaign Import Properties

The following table shows the options and functions available on the Campaign Import Properties dialog box.

Use this | To do this
Description | Type a description for this import task.
Site Name | Select from the drop-down list the site that contains the data you want to import.

See Also

Importing Campaign Data

Data Warehouse Components


User Import Properties

The following table shows the options and functions available on the User Import Properties dialog box.

Use this | To do this
Description | Type a description for this import task.
Site name | Select from the drop-down list the site that contains the data you want to import.
Query interval (mins.) | Type the time interval for the import. User data is imported in time intervals to prevent locking the database table. For example, a Web site with 10,000 users would import user data in 15-minute intervals.
Import start date | Select a date from the drop-down calendar on which to begin your import.
Incremental load | Select to only import new users. (Based on a previous import).
Full load | Select to import all user data.

See Also

Importing User Profile Data

Data Warehouse Components


Synchronize DW Properties

The following table shows the options and functions available on the Synchronize DW Properties dialog box.

Use this | To do this
Description | Type a description for this import task.
Site name | Select from the drop-down list the site that contains the data you want to import.

See Also

Synchronizing Site Configuration with the Data Warehouse


Prepare Reports Properties

The following table shows the options and functions available on the Prepare Report Properties dialog box.

Use this | To do this
Description | Type a description for this import task.
Site name | Select from the drop-down list the site that contains the data you want to use in analysis reports..
Incremental | Select to perform incremental cube processing.
Full | Select to perform full cube processing.

See Also

Preparing to Create Reports


Web Server Log Files

The following table shows the options and functions available on the Web Server Log Files dialog box.

Use this | To do this
Application | Check the box in this column next to the site name of the log file you want to import.

See Also

Importing Web Log File Data


Predictor Resource UI Help

This section contains the context-sensitive help topics for the Commerce Server Predictor resource. These topics are available from the Predictor resource user interface by clicking Help in Predictor resource dialog boxes.

This section contains:

  • Predictor on <server name> Properties, General Tab

  • Model Build Properties


Predictor on <server name> Properties, General Tab

The following table shows the options and functions available on the General tab of the Predictor on <Server Name> Properties dialog box.

Use this | To do this
Name | View the name of the Predictor resource.
Host name | View the server name on which the Predictor resource is installed.
Last started | View the date and time the Predictor resource was last started.

See Also

About the Predictor Resource


Model Build Properties

The following table shows the options and functions available on the Model Build Properties dialog box.

Use this | To do this
Name | Type a name for the analysis model.
Build priority Select the build priority you want to set for this analysis model. The default is Normal (which is the build priority for the particular build thread). Selections are:
  • Lowest

  • Below Normal

  • Normal

  • Above Normal

  • Highest
Model type Select an analysis model type to build. Selections are:
  • Prediction. Select this option to build a prediction model to make recommendations on your site.

  • Segment. Select this option to build a segment model to view user segments in the Commerce Server Business Desk Segment Viewer module.
Sample size | Type the number of cases that are to be used to build the analysis model. You can change the default value if necessary. The default is -1 (all data) or 20,000 cases whichever is less.
Measured accuracy sample fraction | Type the fraction of the sample data you want to use to automatically score the accuracy of the model as a number between 0.0 and 1.0. For example, if you type 0.0 as the value of the Measured accuracy fraction, the model will not be scored. If you type 0.4, 40percent of the sample data will be used to score the model (the remaining 60percent is used to build the model).
Measured accuracy maximum predictions | Type the maximum number of recommendations to be presented on your site (used to compute the "Recommendation score"). The default is 10 attributes.
Input attribute fraction | Type the fraction of attributes to be used as input to the predictions as a number between 0.0 and 0.1. For example, specifying an input attribute fraction of 0.05 selects the most significant 5percent of input attributes. The default value is 1.0, which includes all attributes as inputs for prediction. Values less than 1.0 are recommended if the number of attributes is very large, such as product recommendations for a catalog with over 1,000 products.
Output attribute fraction | Type the fraction of attributes to be predicted as a number between 0.0 and 0.1. For example, specifying an output attribute fraction of 0.05 results in trees being built for the most significant 5percent of attributes. (If the output attributes are products, this will return trees for the 5percent most popular products.) The default value is 1.0, which produces trees for all attributes. Values less than 1.0 are recommended if the number of attributes is very large, such as product recommendations for a catalog with over 1,000 products.
Number of segments | Type the maximum number of segments in which to partition the users. This is an initial hint for the algorithm, which may find fewer significant segments than this value. This value is only available if you are building a segment model.
Buffer size | Type the size of the buffer that will be used to read cases during segmentation. The default is 1,000,000 bytes. The buffer size can affect the build time and quality of the model. For example, if the model contains many attributes, you should set a large buffer size. The system resources of the computer running the Predictor resource determine buffer size limitations. This value is only available if you are building a segment model.

See Also

About the Predictor Resource

Predictor Best Practices

Analysis Model Effectiveness


Site Packager Dialog Box Help

This section contains the context-sensitive help topics for the Commerce Server Site Packager. These topics are available from the Site Packager user interface by clicking Help in Site Packager dialog boxes.

This section contains:

  • Welcome

  • Package

  • Unpack

  • Quick Unpack

  • Unpack Method

  • Site Name

  • Select Resources

  • Global Resource Pointers

  • Database Connection Strings

  • Select Applications

  • Select IIS Web Sites and Virtual Directories

  • Master Database

  • New Database

  • Data Warehouse Properties

  • Profiling System

  • Profiling System: Active Directory Data Source

  • Profiling System: OLEDB Data Source

  • Unpacking is Complete!

  • Select Site

  • Profiling System

  • Profiling System


Welcome

The following table shows the options and functions available on the Welcome dialog box.

Use this | To do this
Unpack from a package file | Select to install a Commerce Server application onto a Web server.
Package an existing site | Select to create a package of a Commerce Server application so that you can move it to another Web server.

See Also

Unpacking a Site


Package

The following table shows the options and functions available on the Package dialog box.

Use this | To do this
Site to package | Select the Internet Information Server (IIS) name of the site you want to package.
Package file to create | Type a name for the package file you are creating.

See Also

Packaging a Site


Unpack

The following table shows the options and functions available on the Unpack dialog box.

Use this | To do this
File to unpack | Select the name of the package file you want to unpack.
Quick unpack | Specify that you want to quickly install all applications in this site on the local computer, and all databases on a single local or remote computer.
Custom unpack | Specify that you want Site Packager to prompt you choose all settings for unpacking your site. You can specify which applications to install, and how to configure their databases.


Quick Unpack

The following table shows the options and functions available on the Quick Unpack dialog box.

Use this | To do this
Site name | Type the name you want to give your site. This will be the name of the virtual directory of the site.
IIS Web site | Select the name of the Internet Information Server (IIS) Web site that will host your site. This must be an existing Web site. You can use the IIS snap-in to create a new IIS Web site.
SQL Server computer | Type the name of the SQL server that will host your site databases.
SQL user name | Type the user name of the person with logon privileges to the SQL Server. Use a login that is a member of one of the following SQL Server roles: sysadmin or dbcreator. To avoid OLAP errors, you should avoid special characters (such as #, @, %, and ').
SQL password | Type the password of the user with logon privileges to the SQL Server. To avoid OLAP errors, you should avoid special characters (such as #, @, %, and ').

See Also

Unpacking a Site


Unpack Method

The following table shows the options and functions available on the Unpack Method dialog box.

Use this | To do this
Create a new site | Select to create a new Web site.
Add resources in the package to an existing site | Select to add resources, such as Direct Mailer or Predictor, to an existing Commerce Server site.
Add an application in the package to an existing site | Select to add an application, such as Business Desk, to an existing site.
Add a Web server to an existing application in an existing site | Select to install applications on a Web server that is administered on another server. This option adds a new Web server to your site. This option does not install the Commerce Server administrative tools to the new Web server.

See Also

Example A: Installing on a Four-Computer Clustered Configuration


Site Name

The following table shows the options and functions available on the Site Name dialog box.

Use this | To do this
Site name | Type the name of site you want to create.
Existing sites | View a list of existing sites. You cannot select a name from this list if you are creating a new site.

Notes

  • To avoid unpacking errors, you should avoid special characters (such as #, @, %, and ') and key combinations (such as ALT+number) in your site name. The site name is appended to your database names, and special characters or key combinations can corrupt these names.

  • Do not specify a Site Name of more than 256 single-byte characters or 128 double-byte characters.

  • Do not name your site "Commerce." This is a reserved OLAP database name. Naming your site "Commerce" could lead to the deletion of your OLAP database the next time you unpack a site.

See Also

Example A: Installing on a Four-Computer Clustered Configuration


Select Resources

The following table shows the options and functions available on the Select Resources dialog box.

Use this | To do this
Resources to unpack | Specify which resources you want to unpack. If the resource is included in this list, its settings and schema will be unpacked.
Add | Move items selected in the Available resources list to the Resources to unpack list.
Add All | Move all items in the Available resources list to the Resources to unpack list.
Remove | Move items selected in the Resources to unpack list to the Available resources list.
Remove All | Move all items in the Resources to unpack list to the Available resources list.

Note

  • You must install the Site CS Authentication and Profiles resources together. They do not work unless both are installed.

See Also

Example A: Installing on a Four-Computer Clustered Configuration


Global Resource Pointers

The following table shows the options and functions available on the Global Resource Pointers dialog box.

Use this | To do this
Global resource pointers | Select a global resource pointer you want to configure. The Maps to global resource column indicates whether a new global resource will be created locally, or where the global resource exists.
Existing global resources | Select the location of the global resource you want this computer to use. The list will contain global resources created during Commerce Server Setup.

See Also

Example A: Installing on a Four-Computer Clustered Configuration


Database Connection Strings

The following table shows the options and functions available on the Database Connection Strings dialog box.

Use this | To do this
Resource | Select the resource on which you want to perform an action, such as changing a database server.
Modify | Specify a different server or database for a resource.
Defaults | Return your connection strings to the default settings, which consist of two databases (one for Data Warehouse and one for the other resources) stored locally.
Copy | Copy the selected resources to the Clipboard.
Paste | Paste the selected resources from the Clipboard.
New Database | Create a new database for the selected resource(s). Use this command if you want to put the database on a different computer, or even if you simply want to rename a database.

See Also

Example A: Installing on a Four-Computer Clustered Configuration


Select Applications

The following table shows the options and functions available on the Select Applications dialog box.

Use this | To do this
Applications in the package | Specify which applications you want to unpack. Clear the check boxes for applications you do not want to install.

See Also

Example A: Installing on a Four-Computer Clustered Configuration


Select IIS Web Sites and Virtual Directories

The following table shows the options and functions available on the Select IIS Web Sites and Virtual Directories dialog box.

Use this | To do this
Application | Select the application on which you want to perform an action.
IIS Web site | Select an existing IIS Web site, the location of your site on the server.
Refresh Web Sites | Select to update the list of available IIS Web sites. Select this if you create a new IIS Web site while this dialog box is displayed.
IIS virtual directory | Specify the name of the IIS virtual directory of your site. This name will appear in the URL path of your site.

Note

  • To avoid IIS errors, you should not include special characters (such as #, @, %, and ') in your IIS Web Site and virtual directory names.

  • Site Packager does not support unpacking a site on a remote computer.

  • Site Packager will locate your applications in separate subfolders inside the IIS Web site you specify, and inside the physical folders your IIS Web site point to. It will name those subfolders with the virtual directory name you specify for each application. By default, these virtual directory names are the same as the application names.

See Also

Example A: Installing on a Four-Computer Clustered Configuration


Master Database

The following table shows the options and functions available on the Master Database dialog box.

Use this | To do this
SQL user name | Specify the user name of the person with logon privileges to the SQL Server. To create a new database, you must use a login that is a member of one of the following SQL Server roles: sysadmin or dbcreator. To avoid OLAP errors, you should avoid special characters (such as #, @, %, and ').
SQL password | Specify the password of the user with logon privileges to the SQL Server. To avoid OLAP errors, you should avoid special characters (such as #, @, %, and ').
Test Connection | Test the connection to this computer to the database server specified at the top of the dialog box.


New Database

The following table shows the options and functions available on the New Database dialog box.

Use this | To do this
SQL Server computer | Type the name of the SQL Server cluster.
Database name | Type the name you want for the Data Warehouse database.
SQL user name | To create a new database, you must use a login that is a member of one of the following SQL Server roles: sysadmin or dbcreator. To avoid OLAP errors, you should avoid special characters (such as #, @, %, and ').
SQL password | Type the SQL Server login password. To avoid OLAP errors, you should avoid special characters (such as #, @, %, and ').
Create Database | Click to create the new database on the specified server.

See Also

Example A: Installing on a Four-Computer Clustered Configuration


Data Warehouse Properties

The following table shows the options and functions available on the Data Warehouse Properties dialog box.

Use this | To do this
Name | Type the name you want to give to the global Data Warehouse resource.
Server | Type the name of the SQL Analysis (OLAP) computer.
Database | Type the name of the Analysis (OLAP) database to use.
Test Connection | Test the connection between this computer and the server hosting the Data Warehouse
Skip Resource | Skip the configuration of the local pointer to a global Data Warehouse resource.

See Also

Securing Your Site


Profiling System

The following table shows the options and functions available on the Profiling System dialog box.

Use this | To do this
Profile Schema Definition (*.xml) | Specify the profile schema definition to import into your site.
Site Terms Definition (*.xml) | Specify the site terms definition to import.
Expression Definition (*xml) | Specify the expression definition to import.

See Also

Unpacking a Site


Profiling System: Active Directory Data Source

The following table shows the options and functions available on the Profiling System: Active Directory Data Source dialog box.

Use this | To do this
Domain | Type the Windows domain that contains your site.
User name | Type a valid Windows domain user name. You must type the user name in one of these formats: domain\username username@domain
Password | Type the domain password for the specified user.
Parent URL | Type the location in the directory tree where you want your data to be stored.
Use Simple Bind | Select to send the password in clear text. This option is less secure, but is required by some directory services.
Execution Script | Execute Visual Basic scripts for creating objects in the directory tree pertaining to this site.
Test Connection | Test the validity of the connection to the domain controller.


Profiling System: OLEDB Data Source

The following table shows the options and functions available on the Profiling System: OLEDB Data Source dialog box.

Use this | To do this
Modify | Change the profiling system connection string.
Schema definition scripts | Specify the location of schema definition scripts.
Data population scripts | Specify the location of data population scripts.


Unpacking is Complete!

The following table shows the options and functions available on the Unpacking is Complete! dialog box.

Use this | To do this
View Selected Application | Run the application selected in the IIS applications created during unpacking box.
View Log File | Open the Site Packager log file, which lists all the events that take place while Site Packager runs. Use this to get information if errors occurred.
Finish | Close Site Packager.


Select Site

The following table shows the options and functions available on the Select Site dialog box.

Use this | To do this
Existing sites | Select the name of the site you want to modify.

See Also

Unpacking a Site


Profiling System

The following table shows the options and functions available on the Profiling System dialog box.

Use this | To do this
Profile Schema Definition | Specify the profile schema definition to import into your site.
Site Terms Definition | Specify the site terms definition to import.
Expression Definition | Specify the expression definition to import.


Profiling System

The following table shows the options and functions available on the Profiling System dialog box.

Use this | To do this
Profiling System Connection String | Specify the files to import into the OLEDB data store. Click Modify to specify a different database.
Schema definition scripts (*.sql, *.vbs) | Specify the schema definition scripts to import into your site.
Data population scripts (*.sql) | Specify the data population scripts to import.


Profiles Resource UI Help

This section contains the context-sensitive help topics for the Commerce Server Profiles resource. These topics are available from the Profiles resource user interface by clicking Help in Profiles resource dialog boxes.

This section contains:

  • Profile Catalog Properties, General Tab

  • <Profile Definition> Properties, General Tab

  • <Profile Definition> Properties, Custom Attribute Tab

  • Custom Attributes

  • New Data Source

  • Data Source

  • Partitions

  • Partition

  • System Attributes

  • LDAP Connection String

  • New Data Object

  • New Data Member

  • <Data Member> Properties, General Tab

  • <Data Member> Properties, Properties Tab

  • <Data Object> Properties, Identity Tab

  • New Profile Definition

  • Custom Attribute

  • <Data Source> Properties, General Tab

  • <Data Source> Properties, Data Source Tab

  • <Data Source> Properties, Partitions Tab


Profile Catalog Properties, General Tab

The following table shows the options and functions available on the General tab of the Profile Catalog Properties dialog box.

Use this | To do this
Name | View the programmatic name of the profile catalog.
Display Name | Edit the display name of the profile catalog. The display name can contain a maximum of 127 Unicode characters.
Description | Edit the description of the profile catalog. The description can contain a maximum of 127 Unicode characters.

See Also

Profile Definitions

Sample Profile Definitions

Adding Properties to Profile Definitions

Example: Creating a Profile Definition with Two Data Sources

Managing Profile Definitions


<Profile Definition> Properties, General Tab

The following table shows the options and functions available on the General tab of the <Profile Definition> Properties dialog box.

Use this | To do this
Name | View the programmatic name of the profile definition you are editing.
Display Name | Edit the display name of the profile. The display name can contain a maximum of 127 Unicode characters.
Description | Edit the description of the profile. The description can contain a maximum of 127 Unicode characters.

See Also

Profile Definitions

Sample Profile Definitions

Adding Properties to Profile Definitions

Example: Creating a Profile Definition with Two Data Sources

Managing Profile Definitions


<Profile Definition> Properties, Custom Attribute Tab

The following table shows the options and functions available on the Custom Attributes tab of the <Profile Definition> Properties dialog box.

Use this | To do this
New | Click to open the Custom Attribute dialog box and create a new custom attribute.
Edit | Click to open the Custom Attribute dialog box and edit the selected custom attribute.
Delete | Click to delete the selected custom attribute.

See Also

Profile Definitions

Sample Profile Definitions

Adding Properties to Profile Definitions

Example: Creating a Profile Definition with Two Data Sources

Managing Profile Definitions


Custom Attributes

The following table shows the options and functions available on the Custom Attributes dialog box.

Use this | To do this
New | Click to open the Custom Attribute dialog box and create a new custom attribute.
Edit | Click to open the Custom Attribute dialog box and edit the selected custom attribute.
Delete | Click to delete the selected custom attribute

See Also

Profile Definitions

Sample Profile Definitions

Adding Properties to Profile Definitions

Example: Creating a Profile Definition with Two Data Sources

Managing Profile Definitions


New Data Source

The following table shows the options and functions available in the New Data Source dialog box.

Use this | To do this
Name | Type the programmatic name of the data source. The name can contain a maximum of 127 alphanumeric characters, and the underscore (_) symbol. The name cannot contain spaces.
Display Name | Type the name that will be displayed for the data source. The display name can contain a maximum of 127 Unicode characters.
Description | Type a short description for the data source. The description can contain a maximum of 127 Unicode characters.

See Also

Data Sources

Data Source Partitions

Adding a New Data Source

Example: Creating a Profile Definition with Two Data Sources

Managing Data Sources


Data Source

The following table shows the options and functions available on the Data Source dialog box.

Use this | To do this
Source Type | Select the source type, either LDAPV3-Compliant Source or OLEDB-ANSI Provider.

See Also

Data Sources

Data Source Partitions

Adding a New Data Source

Example: Creating a Profile Definition with Two Data Sources

Managing Data Sources


Partitions

The following table shows the options and functions available in the Partitions dialog box.

Use this | To do this
Partitioned Data-Source | Select to create multiple partitions for this data source.
Number of Partitions | View the number of existing partitions for this data source.
Add | Click to open the Partition dialog box and create a new partition.
Edit | Click to open the Partition dialog box and edit the selected partition.

See Also

Data Sources

Data Source Partitions

Adding a New Data Source

Example: Creating a Profile Definition with Two Data Sources

Managing Data Sources


Partition

The following table shows the options and functions available in the Partition dialog box.

Use this | To do this
Edit | Click to open LDAP Connection String dialog box if LDAP was selected in the Data Source dialog box. Click to open Data Link Properties dialog box if OLE DB was selected in the Data Source dialog box.
Test | Click to test the connection string.
Partition Name | Type a programmatic name for this partition. The partition name can contain 127 alphanumeric characters, and the underscore (_) symbol. The name cannot contain spaces.
Default Partition | Select to designate this partition as the default partition.
LDAPv3 Binding Credentials: User Name | Type the user name for the LDAP source.
LDAPv3 Binding Credentials: Password | Type the password for the LDAP source.

See Also

Data Sources

Data Source Partitions

Adding a New Data Source

Example: Creating a Profile Definition with Two Data Sources

Managing Data Sources


System Attributes

The following table shows the options and functions available in the System Attributes dialog box.

Use this | To do this
Parent URL | Type the location in the directory tree where new objects will be created. This is relative to the root.
Use the same credentials for all users | Select to force the profile service to use the credentials for this partition for all binds.
Allow Simple Bind | Select to force the profile service to send passwords in clear text.
Dynamic Container | Select to connect to a dynamic store such as Internet Locator Service (ILS).
One-Level | Select this option to perform searches in the directory.
Sub-Tree | Select this option to perform subtree searches in the directory.
Domain Name | Type the domain name for the Active Directory server. Use the computer name for non-Active Directory sources.
Discover | Click to retrieve the domain name for the Active Directory server.

See Also

Data Sources

Data Source Partitions

Adding a New Data Source

Example: Creating a Profile Definition with Two Data Sources

Managing Data Sources


LDAP Connection String

The following table shows the options and functions available on the LDAP Connection String dialog box.

Use this | To do this
Server | Type the server name where the LDAP source is located.
Port | Type the port name. The default port is 389.
Connection String | View the connection string.

See Also

Data Sources

Data Source Partitions

Adding a New Data Source

Example: Creating a Profile Definition with Two Data Sources

Managing Data Sources


New Data Object

The following table shows the options and functions available in the New Data Object dialog box.

Use this | To do this
Object Name | Select the data object from the drop-down list that is the name of a table or LDAP class in the underlying data store.
Display Name | Type the name that will be displayed for the data object. The display name can contain a maximum of 127 Unicode characters.
Description | Type a description for the data object. The description can contain a maximum of 127 Unicode characters.
Members in object | View the data members in the selected data object.

See Also

Data Sources

Adding a New Data Source

Adding a New Profile Definition

Example: Creating a Profile Definition with Two Data Sources

Managing Data Sources


New Data Member

The following table shows the options and functions available in the New Data Member dialog box.

Use this | To do this
Member Name | Select a name for the new data member from the list. The new data member name must be unique for the data object. The data member must have the name of a column or LDAP attribute in the underlying data store. The name can contain a maximum of 127 alphanumeric characters and the underscore (_). The name cannot contain spaces.
Display Name | Type the name you want displayed in the application for the data member. The display name can contain a maximum of 127 Unicode characters.
Description | Type a short description for the data member. The description can contain a maximum of 127 Unicode characters.
Type Select the data type for the data member. The following data types are supported:
  • Binary

  • Boolean

  • Currency

  • Date/Time

  • Number

  • String
Multivalued | Select this check box to enable the collection of multiple values that are associated with the data member.
Required | Select this check box if the data member is required. Otherwise, it will be optional.
Indexed | Select this check box if the data will be indexed on this data member.
Primary key | Select this check box to designate this data member the primary key. You must select one data member in each data object to be the primary key.
Add | Click to add the new data member to the data member list.
Finished | Click to close the New Data Member dialog box and update the Commerce Server Manager detail pane.

See Also

Data Sources

Adding a New Data Source

Adding Properties to Profile Definitions

Example: Creating a Profile Definition with Two Data Sources

Managing Data Sources


<Data Member> Properties, General Tab

The following table shows the options and functions available on the General tab of the <Data Member> Properties dialog box.

Use this | To do this
Name | View the programmatic name of the data member. You cannot change the name.
Display Name | Edit the name that will be displayed for the data member. The display name can contain a maximum of 127 Unicode characters.
Description | Edit the description of the data member. The description can contain a maximum of 127 Unicode characters.

See Also

Data Sources

Adding a New Data Source

Adding Properties to Profile Definitions

Example: Creating a Profile Definition with Two Data Sources

Managing Data Sources


<Data Member> Properties, Properties Tab

The following table shows the options and functions available on the Properties tab of the <Data Member> Properties dialog box.

Use this | To do this
Type | Select a new type for the data member from this drop-down list.
Multivalued | Select this check box if the database column (or LDAP attribute) the data member is used to map to is multivalued.
Required | Select this check box if the database column (or LDAP attribute) the data member is used to map to is required.
Index | Select this check box if the database column (or LDAP attribute) the data member is used to map to is indexed.
Primary Key | Select this check box if the database column (or LDAP attribute) the data member is used to map to is a primary key.

See Also

Data Sources

Adding a New Data Source

Adding Properties to Profile Definitions

Example: Creating a Profile Definition with Two Data Sources

Managing Data Sources


<Data Object> Properties, Identity Tab

The following table shows the options and functions available on the Identity tab of the <Data Object> Properties dialog box.

Use this | To do this
Name | View the name of the data object.
Display Name | Edit the display name of the data object. The display name can contain a maximum of 127 Unicode characters.
Description | Edit the description of the data object. The description can contain a maximum of 127 Unicode characters.

See Also

Data Sources

Adding a New Data Source

Adding Properties to Profile Definitions

Example: Creating a Profile Definition with Two Data Sources

Managing Data Sources


New Profile Definition

The following table shows the options and functions available on the New Profile Definition dialog box.

Use this | To do this
Name | Type a programmatic name for the new profile. The name can contain a maximum of 127 alphanumeric characters, and the underscore (_) symbol. The name cannot contain spaces.
Display Name | Type the name that will be displayed for the new profile. The display name can contain a maximum of 127 Unicode characters.
Description | Type a description for the new profile. The description can contain a maximum of 127 Unicode characters.

See Also

Profile Definitions

Sample Profile Definitions

Adding Properties to Profile Definitions

Example: Creating a Profile Definition with Two Data Sources

Managing Profile Definitions


Custom Attribute

The following table shows the options and functions available on the Custom Attribute dialog box.

Use this | To do this
Name | Type a programmatic name for the attribute. The name can contain a maximum of 127 alphanumeric characters, and the underscore (_) symbol. The name cannot contain a space.
Display Name | Type the name that will be displayed for the attribute. The display name can contain a maximum of 127 Unicode characters.
Description | Type a short description for the attribute. The description can contain a maximum of 127 Unicode characters.
Value | Type the value assigned to the attribute.

See Also

Profile Definitions

Sample Profile Definitions

Adding Properties to Profile Definitions

Example: Creating a Profile Definition with Two Data Sources

Managing Profile Definitions


<Data Source> Properties, General Tab

The following table shows the options and functions available on the General tab of the <Data Source> Properties dialog box.

Use this | To do this
Name | View the name of the data source.
Display Name | Edit the name that will be displayed for the data source. The display name can contain a maximum of 127 Unicode characters.
Description | Edit the description of the data source. The description can contain a maximum of 127 Unicode characters.

See Also

Data Sources

Data Source Partitions

Adding a New Data Source

Example: Creating a Profile Definition with Two Data Sources

Managing Data Sources


<Data Source> Properties, Data Source Tab

The following table shows the options and functions available on the Data Source tab of the <Data Source> Properties dialog box.

Use this | To do this
Source Type | Select the source type, eitherLDAPV3-Compliant Source or OLEDB-ANSI Provider.

See Also

Data Sources

Data Source Partitions

Adding a New Data Source

Example: Creating a Profile Definition with Two Data Sources

Managing Data Sources


<Data Source> Properties, Partitions Tab

The following table shows the options and functions available on the Partitions tab of the <Data Source> Properties dialog box.

Use this | To do this
Partitioned Data-Source | Select to create multiple partitions for this data source.
Number of Partitions | View the number of existing partitions for the data source.
Add | Click to open the Partition dialog box and create a new partition.
Edit | Click to open the Partition dialog box and edit the selected partition.

See Also

Data Sources

Data Source Partitions

Adding a New Data Source

Example: Creating a Profile Definition with Two Data Sources

Managing Data Sources


Working with Business Desk

This section describes how to manage your Web site using Commerce Server Business Desk. This section is intended for the business manager, whose responsibilities include choosing and updating site content, and who performs such functions as changing the ads displayed to premier users, updating the catalog and publishing those changes, and running reports to measure how those changes affect site productivity.

This section contains:

  • Getting Started with Business Desk. Describes components of Business Desk, how to customize and configure Business Desk, and explains what you must do first to use Business Desk.

  • Business Desk Tutorial. Explains how to use Business Desk to perform key tasks for managing your business-to-consumer and business-to-business commerce sites.

  • Business Desk Analysis. Explains how to set up and run reports that you use to analyze the activity on your Web site.

  • Business Desk Campaigns. Explains how to create and manage campaigns of different types (ads, discounts, and direct mail) to target different user groups, extend the reach of your business, and increase sales.

  • Business Desk Catalogs. Explains how to create a catalog schema, and how to create and manage a catalog.

  • Business Desk Orders. Explains how to check the status of an order and how to manage order templates, baskets, and the purchase order approval process. Explains how to add, change, and delete different types of data codes.

  • Business Desk Users. Explains how to add new registered users and organizations, how to add properties to profile definitions and how to add site terms.

  • Troubleshooting Business Desk. Explains how to troubleshoot and resolve common problems that you may encounter when using Business Desk.


Getting Started with Business Desk

This section provides information for new users of Commerce Server Business Desk.

This section contains:

  • Business Desk Overview

  • Business Desk Basics

  • What to do First

  • Common Tasks

  • Example: Closing the Loop

  • Using Business Desk Online Help

  • If You Need Additional Help


Business Desk Overview

Commerce Server Business Desk is a Web-based site management tool included with Microsoft Commerce Server 2000. Business Desk hosts business management modules that you use to configure, manage, and analyze your sites. For example, you use Business Desk modules to update pricing information in your catalogs, target new advertisements to specific users, and then run reports to measure how these changes affect site productivity.

Business Desk has two parts: the Business Desk application and the Business Desk client.

  • Business Desk application. The management tool you use to configure, manage, and analyze your site. After you install Commerce Server, you can unpack a Solution Site to install a Business Desk application. Business Desk is accessible from any computer running Microsoft Internet Explorer 5.5, providing you with secure remote access.

  • Business Desk client. The client software that is installed locally on your computer, providing the interface to the Business Desk application. When you first access the Business Desk application (via a URL), the Business Desk client is downloaded and installed onto your computer. It is recommended that the computer on which you run the Business Desk client has a high-speed connection to the Business Desk application.

The following figure shows how you can use Business Desk clients to remotely access the Business Desk application to update a Web site.

Business Desk
Client
Business Desk
Client
Business Desk
Client
Commerce Server Data Center
Business Desk
Application
Your
Web site
New York
Tokyo
Chicago
New York
The Internet
A figure illustrating how a Business Desk client accesses the Business Desk application

This section contains:

  • Business Desk Components

  • Updating Your Web Site with Business Desk

  • Using BizTalk Server

  • Commerce Server Configuration and Business Desk


Business Desk Components

You use modules, the main components of Commerce Server Business Desk, to manage different aspects of your site. The following table lists the Business Desk modules and the categories that contain them, and describes the tasks you can do with each one.

Category | Description
Analysis Reports Completed Reports Segment Viewer | Run and review reports that represent your site activity, and perform predictive analysis. The Analysis modules come with a rich set of reports covering various aspects of your site.
Campaigns Campaign Expressions Campaign Manager List Manager Target Group Reference Tables Publish Campaigns | Create and schedule marketing campaigns. You add customer information and manage campaigns and campaign items. Examples of campaign items are advertising banners, direct mail jobs, and product discounts. Each campaign item can be targeted to specific users thereby creating a highly personalized site.
Catalogs Catalog Designer Catalog Editor Catalog Sets | Import catalogs, create catalogs, add and price products. Create custom catalogs that contain special prices and are displayed only to certain users, for example, members of a club.
Orders Basket Manager Data Codes Order Status Publish Transactions Shipping Methods Tax Rates | Search the Commerce Server database for existing order information, and add, delete, approve, and change order information. Add, delete, and change shipping rates and tax rates.
Users Users Organizations Profile Designer Site Terms Editor Publish Profiles | Create and change users, organizations, and profiles. Create and change site terms.

See Also

Updating Your Web Site with Business Desk

Commerce Server Configuration and Business Desk

Using BizTalk Server

Business Desk Basics

What to do First


Updating Your Web Site with Business Desk

The following figure illustrates how you can use the Commerce Server Business Desk modules to update your Web site. For example, site data is gathered from your Web site and imported into the Data Warehouse, and then you can run analysis reports. You use the Campaigns modules to create and display advertisements, discounts, and promotions. You use the Catalogs modules to update information in your catalog. You use the Orders modules to research user orders. You use the Users modules to reset user passwords, change other user profile information, and determine what profile data to collect.

A figure illustrating how Business Desk modules update your Web Site
Users
Orders
Campaigns
Orders
Profiles
Commerce Server
Data
Warehouse
Register
Users
Business Desk
Commerce Server Databases
Your Web Site
Display Catalogs
Catalogs
Catalogs
Campaigns
Analysis
Record
Activity
Take
Orders
Display
Ads

See Also

Business Desk Components

Commerce Server Configuration and Business Desk

Using BizTalk Server

Business Desk Basics

What to do First


Using BizTalk Server

BizTalk Server 2000 provides a gateway for sending business documents between your company and your trading partners (also known as vendors). For example, if your company uses BizTalk Server, you can trade catalogs, orders, documents, and other electronic forms with your trading partners. BizTalk Server manages the data translation, encryption, digital signatures, and document tracking services for many different transport mechanisms. BizTalk Server manages the data translation, encryption, digital signatures, and document tracking services for many different transport mechanisms.

You can use BizTalk Server and Commerce Server together to process orders that users place on your Commerce Server Web site. For example, assume you are selling computer hardware on your site. Your company manufactures some of this hardware, and some of it is supplied to you by trading partners. Using BizTalk Server, you can create a trading agreement for each trading partner who supplies the hardware that you sell on your site. When a user visits your site and places an order for one of the products supplied by a trading partner, Commerce Server processes the order, sends it to BizTalk Server, and then BizTalk Server sends the order to the trading partner to be fulfilled.

Catalogs from Multiple Vendors

Vendor ID

Catalogs from Multiple Vendors

Before you can use BizTalk Server to transmit orders to your trading partners, you must first organize the catalogs of those trading partners whose products will appear on your site. Each of your trading partners can send you one or more catalogs of their products. Depending on how you set up your site, you can present these catalogs on your Web site as one catalog, or as different catalogs.

A vendor sends you their catalogs using e-mail or BizTalk Server, and then you import the catalog into your Commerce Server database using the Catalog Editor module in Business Desk. For information about importing catalogs, see Importing a Catalog.

Vendor ID

When you set up an agreement with a vendor, the vendor ID is automatically made available to Commerce Server. Commerce Server displays the vendor ID in Commerce Server Business Desk. It displays those trading partners (organizations) that support the same document type as your organization, and thus have compatible document routing. You can then use Business Desk to associate the vendor ID with the catalog.

More than one catalog can be associated with a given vendor. You can also specify a vendor at the product level; however, if you do this your site developer must customize a page in your Web site (_additem.asp).

If you name a vendor "default," Commerce Server recognizes your own site as the vendor. For information about specifying the vendor ID for a catalog, see Creating a New Catalog.

Note

  • When a user orders an item from your Web site, the item must exist in the catalog of the destination organization. If the destination organization does not have the item in its catalog, BizTalk Server will not be able to send the purchase order from your site to the vendor. It will write an error message to the event log.

Your system administrator is responsible for setting up BizTalk Server and the trading partner agreements. For more information, contact your system administrator.

See Also

Sending a Catalog to a Trading Partner

Importing a Catalog

Creating a New Catalog


Commerce Server Configuration and Business Desk

Commerce Server Business Desk is hosted on a Web server running Commerce Server, the same way a Web site is hosted on a Web server. Your site developer and/or system administrator are responsible for configuring Business Desk to meet your business needs, and for ensuring you have access to the data you need to analyze and update your Web site.

The system administrator configures and maintains Business Desk using Commerce Server Manager. Commerce Server Manager is a Windows-based application, not a Web-based one; you cannot access it remotely.

The following table lists some of the tasks your system administrator performs to configure Commerce Server. If you have questions about these tasks or other site functionality, contact your system administrator.

Category System Administrator Tasks
Analysis
  • If needed, assigns specific SQL Server database roles to Business Desk users, allowing some users to read and save reports, while others can only read reports.

  • Import site data to the Data Warehouse so you can run reports.

  • Build new Segment models so you can perform segment analysis.
Campaigns
  • Determine when and how often advertising and discount campaign items are updated on your production site.

  • Provide the connection string and SQL query for you to generate lists directly from your SQL database.
Catalogs
  • Determine when and how often catalog updates are made to your production site.

  • Create a shared folder (\\server\CommerceCatalogs) for importing and exporting catalogs.

  • Convert external catalogs to Extensible Markup Language (XML) or comma-separated values (CSV) file format so you can import them.

  • Set the following Commerce Server properties:
    • The language (locale) for this site (1031 = German, 1033 = English, 1034 = Spanish, 1036 = French, 1041 = Japanese).

    • The locale for formatting the base currency.

    • Alternate currency options to enable money display for two currencies simultaneously.

    • The unit of measure for weights for calculating product shipping costs (for example, kilograms or pounds).

    • BizTalk Server integration options enabling you to send and receive catalogs from trading partners.
Orders
  • Define the payment types supported by your site: credit card, account billing, or both.
Users
  • Add profile definitions.

  • Add data sources that control where profile data is stored.

  • Set the following Commerce Server properties:
    • Site registration options that enable users to register at your site.

    • Site privacy options that collect profile information for guest users.

    • Address book options that enable your site to support an address book feature.

    • Login options that determine when users must login to the site: log in when they enter the site; optional on entering the site; require login at time of purchase; login optional at any time.

    • The number of times users are prompted to type their user name and password before a message instructing them to call customer service is displayed.

See Also

Updating Your Web Site with Business Desk

Business Desk Components

Using BizTalk Server

Business Desk Basics

What to do First


Business Desk Basics

Because Commerce Server Business Desk is a Web-based application, in some ways it looks and works differently than other Microsoft applications which are PC-based, such as Microsoft Word and Microsoft Excel. For example, you navigate through Business Desk by choosing from options (modules) in a menu on the left. This design is similar to that of many Web pages.

This section contains:

  • Navigating Business Desk

  • Using Toolbar Buttons

  • Securing Business Desk Modules

  • Customizing Business Desk

  • Importing and Exporting Data

  • Using Keyboard Shortcuts


Navigating Business Desk

Although each module in Commerce Server Business Desk has a unique function, all the modules have been designed with similar navigational features to help you find and sort information. Once you have learned how to perform the basic tasks in one Business Desk module, you can apply that knowledge to other modules. This section describes the layout of Business Desk screens, and how to navigate from category to module to screen.

The Navigation Pane

The Content Pane

Toolbar Buttons

The Navigation Pane

The left side of the Commerce Server Business Desk screen is called the navigation pane. You use this pane to select categories and open modules. When you click the name of a category, it expands and the module names appear in a list below the category. Click the category name again to collapse the module names back into the category.

The position of the arrowhead to the left of the category name indicates whether the category can be expanded or collapsed. A right-pointing arrowhead indicates that you can expand the list. An arrowhead pointed down indicates that the list is already expanded.

The following figure shows the navigation pane with the Orders category expanded to show the list of modules.

Business Desk navigation pane

Click the illustration to enlarge or reduce.

Note

When you view properties for a listed item, the navigation pane disappears from view. For example, in the previous figure, if you were to view the properties for the Code #1 – Basket, a new screen would be displayed and the navigation pane would no longer appear. You use the Back and Save and go back toolbar buttons to return to the main screen which contains the navigation pane.

The Content Pane

The right side of the Business Desk screen is called the content pane. You use the content pane to view site data and to edit information. When you click a module name in the navigation pane, the content pane is populated by a list that contains all the current information for the module.

For example, if you open the Orders category, and then click the Data Codes module name, the Data Codes – Order Status Codes screen appears in the content pane. In this screen, you can view, add, and delete the order status, country, and state data codes.

Toolbar Buttons

The toolbar appears across the top of the content pane and contains buttons that perform standard tasks. You click a toolbar button, for example, to add, copy, or delete an item. Each toolbar button shows a representational graphic for the action it executes. To see a description of that action, pause your mouse over a button before you click it. For a list of all the available toolbar buttons and a description of the functions that you can perform with them, see Using Toolbar Buttons.

Command buttons are labeled with the name of the command they execute. You click command buttons to perform specific tasks in the content pane. For example, you click the Select All button to select all the items in a results list.

See Also

Using Toolbar Buttons

Using Keyboard Shortcuts

Using Business Desk Online Help


Using Toolbar Buttons

Each toolbar button is used to execute a standard action from any screen in Commerce Server Business Desk. Not all toolbar buttons are available on every screen. The following table lists the toolbar buttons and describes the function of each.

Toolbar button | Description
Archive Archive | Saves the selected item in the Business Desk Archives.
Back Back | Closes the edit screen and returns you to the previous screen.
Cancel Cancel | Cancels the pending operation.
Copy Copy | Opens the selected item detail information and copies the item to create a new item with similar properties.
Delete Delete | Deletes the selected item or items.
Export Export | Exports a set of information.
Find Find | Opens the Find pane.
Find with menu Find with Menu | Opens a drop-down list from which you can select one of several types of items on which to perform a find.
Help Help | Opens the Business Desk Help for the current module. You can then view other Help topics.
Import Import | Imports a set of information.
Add New | Adds a new item.
Open Open | Opens the selected item.
Preview Report Preview | Displays the selected report in the format in which it will be printed.
Print Print | Prints the selected report. This button is available only in the Analysis modules.
Publish a catalog Publish | Publishes a catalog to a retail site. This button is available only in the Catalog Editor module.
Restore Restore | Restores a deleted campaign item. This button is available only in the Campaign Manager module.
Run report Run | Runs the selected report. This button is available only in the Analysis modules.
Save Save | Saves the added or changed item or property.
Save and create new Save Save and create new | Saves the added or changed item or property and opens a new page to create a new item.
Save and go back Save and go back | Saves the added or changed item or property and returns to the main module screen.
Send Send | Sends a catalog to a trading partner through Microsoft BizTalk Server. This button is available only in the Catalog Editor module and is enabled only if BizTalk Server is installed.
View View | Selects the type of items to view.

See Also

Navigating Business Desk

Using Keyboard Shortcuts

Using Business Desk Online Help


Securing Business Desk Modules

Commerce Server Business Desk provides role-based security: Business Desk users can view and manage only those modules for which they are authorized. For example, if a group of users does not use the Catalog Designer module, you can prevent that module from appearing in the navigation pane when those users access Business Desk. After the site developer limits who can access a module, a user without permissions to the module will not see it.

The ability to limit access to specific modules in Business Desk is not intended to prevent a malicious security violation. Rather, it prevents users from seeing Business Desk modules that are outside their areas of responsibility.

Contact your system administrator to implement security. To secure a Business Desk module, your system administrator must set Windows Access Control Lists (ACLs) on the module Active Server Pages (ASP) files. For more information, see "Security" in the Business Desk Architecture section of Commerce Server 2000 Help.

Notes

  • If you secure one of the following modules, all the modules are secured by default: Publish Profiles, Publish Campaigns, and Publish Transactions.

  • This feature does not limit access to specific data within Business Desk. To limit access to the data a user sees in Business Desk, contact your system administrator or site developer to implement security at the Commerce Server database level. For example, if you want to limit a Business Desk user to editing one specific catalog, your site developer can implement that security.

  • If a user connects to Business Desk from the Internet via an unauthenticated session, Internet Explorer prompts for the user name, password, and domain name in order to authenticate the user for the Business Desk application.

See Also

Business Desk Components

Customizing Business Desk


Customizing Business Desk

Site developers and system administrators can customize Commerce Server Business Desk to meet your business needs. For example, a site developer can add or remove features, integrate Business Desk with an existing application, or change the way Business Desk performs specific functions.

The following table describes several areas where you will coordinate customization with your system administrator or your site developer.

Business Desk component Customization and coordination
Analysis: Reports module
  • Your site developer can create new or customized reports for your business needs. You can also create custom reports based on the existing dynamic reports in the Reports module of Business Desk.

  • The system administrator is responsible for importing data into the Data Warehouse on a regular basis. After data is imported into the Data Warehouse, you can run reports against the data and analyze it.

  • The system administrator can customize which data from the Web log files is imported into the Data Warehouse and can set user and visit definitions that affect the results of the reports you run.
Analysis: Segment Viewer module
  • The system administrator uses the Predictor resource in Commerce Server Manager to create model configurations. The system administrator uses model configurations to build Prediction and Segment models from data in the Data Warehouse. You can view segment models in the Segment Viewer module in Business Desk. The system administrator uses the Prediction Model Viewer to view prediction models.
Users: Profile Designer module
  • The system administrator creates profile definitions using Commerce Server Manager, and adds data sources, data objects, and data members to expose the structure of the Commerce Server database to the profile definition. When you use Business Desk to add a profile property to a profile definition, you select the data member that maps the new profile property to the place in the Commerce Server database where the data collected by the profile property will be stored.
General System Settings
  • The system administrator configures system settings such as units of measure, currency options, payment options, and Web site registration and security options. You need to coordinate any changes to these options or settings with the system administrator.

See Also

Business Desk Components

Commerce Server Configuration and Business Desk

What to Do First

If You Need Additional Help


Importing and Exporting Data

You use Commerce Server Business Desk to import and export catalogs, mailing lists, and lists of users. The following table describes the data that can be imported or exported.

Module | Data imported or exported
Catalog Editor | Catalogs. You can import and export catalogs, in Extensible Markup Language (XML) or comma-separated values (CSV) format, to and from external sources. For information about importing and exporting catalogs, see Importing a Catalog and Exporting a Catalog. Catalog properties. You use Catalog Designer to specify which catalog properties are to be imported and stored in the Data Warehouse. After your system administrator imports the catalog properties to the Data Warehouse, you can run reports on them.
List Manager | User lists and mailing lists. You can import and export static or dynamic user lists and mailing lists from the List Manager module. For information about importing and exporting lists, see Importing and Exporting Lists.
Profile Designer | Profile properties. You use Profile Designer to specify which profile properties are to be imported and stored in the Data Warehouse. After your system administrator imports the profile properties to the Data Warehouse, you can run reports on them.
Reports | When you run a dynamic report, you can export the report to Microsoft Excel and save it as an Excel spreadsheet. You can export static reports to List Manager. After you export a static report to List Manager, you can import the list into Direct Mailer for use in a direct mail campaign if it contains e-mail addresses, or you can import the list into the Users module, if it contains user profile information, and update the profiles of the users in the list.

See Also

Importing a Catalog

Exporting a Catalog

Importing and Exporting Lists

If You Need Additional Help


Using Keyboard Shortcuts

In Commerce Server Business Desk you can use keyboard shortcuts to perform the same navigation and edit functions that you do using a mouse. You can use these shortcuts to perform all the functions used in Business Desk.

This section describes the keyboard shortcuts and also provides some tips about using your keyboard to navigate in Business Desk.

Tabs

Table of Keyboard Shortcuts

Tabs

When you begin to tab through the Business Desk Welcome screen, the tab focus is on the navigation pane. The current tab focus is indicated by a dotted line around the screen element.

When you tab out of the navigation pane, the tab focus goes to the toolbar and then to the content pane. When you tab onto a list of items, you must use the arrow keys to move within the list. Use the ENTER key or space bar to make your selection.

  • If you are selecting from a drop-down menu (menus that include a down arrow), use the arrow keys to indicate your selection and then press ENTER.

  • You can open drop-down menus by pressing the space bar.

  • If you need to use a button, press TAB until the button has the focus and then press ENTER.

  • If you want to tab back to an element, press SHIFT+TAB.

To open a Business Desk module

To access toolbar buttons using a keyboard

To open item properties using a keyboard

To open a Business Desk module

  1. In the navigation pane, tab to the category that contains the Business Desk module you want to work with, and then press ENTER.

  2. Tab to the name of the module you want to work with, and then press ENTER.

The module you selected opens.

To access toolbar buttons using a keyboard

  1. In the navigation pane, tab to the category that contains the items you want to add to or edit, and then press ENTER.

  2. Tab to the name of the module you want to work with, and then press ENTER.

  3. Tab to the toolbar button that you want to use, and then press ENTER.

You can now make changes or additions using the toolbar function you opened.

  4. Press ALT+S to save your additions or changes.

Notes

  • If you tab into a box with a drop-down list, you will need to press ENTER to select from the drop-down list. Use the UP ARROW and DOWN ARROW keys to select an option, and then press ENTER.

  • If you need to go back one box, press SHIFT + TAB.

Some screen elements are assigned the same hot key combinations. For example, the Orders module in the navigation pane and Open toolbar button share ALT+O. In this case, the first time you press a hot key combination you will activate the first screen element, the second time you activate the next element, and so on.

To open item properties using a keyboard

  1. In the navigation pane, tab to the category that contains the items you want to work with, and then press ENTER.

  2. Tab to the module you want to work with, and then press ENTER. The module you selected opens.

  3. Tab to the list of items in the content pane and then use the UP ARROW or DOWN ARROW keys to give the item focus.

  4. Press ENTER. The item is highlighted.

  5. Tab to Open on the toolbar and press ENTER.

  6. The properties for that item appear, enabling you to view them or make changes to them.

Table of Keyboard Shortcuts

Business Desk provides keyboard shortcuts for navigating without a mouse. The following table lists the keyboard shortcuts that are used frequently within Business Desk. You can also determine a keyboard shortcut for a toolbar button by hovering the mouse pointer over that button. This displays the tooltip for that toolbar button.

Action | Shortcut
Open | ALT+O
Find | ALT+F
New | ALT+N
Save | ALT+S
Save and Back | ALT+K
Save and Create New | ALT+N
Delete | ALT+D
Copy | ALT+C
View Properties | ALT+V
Open Help | ALT+?
Back | ALT+B
Run Report | ALT+R
Export | ALT+E
Import | ALT+I

See Also

Using Toolbar Buttons

Using Business Desk Online Help

Navigating Business Desk

If You Need Additional Help


What to do First

Before you can open your Web site for business, you or your site developer must use Commerce Server Business Desk to perform the following tasks:

  1. Create a Catalog. You can import an existing catalog, or create a catalog schema.
    • Import a Catalog. Contact your system administrator for the name and location of the catalog you want to import. You will need the full path name of the catalog on the main Commerce Server computer, for example, C:\Commerce Server\Catalogs\SportsCatalog.xml.

    • Create a Catalog Schema. If you do not have an existing catalog to import, you must create a catalog schema. It is recommended that you plan the organization of your catalog before creating your catalog schema.
  2. Price Products.

  3. Publish Your Catalog to Your Site.

  4. Customize Shipping Methods. You must specify how Commerce Server should calculate the shipping costs: by the weight of the product, by the quantity the users purchase, or by the amount of the purchase subtotal.

After performing these steps, you can open your Web site for business. In addition, it is recommended that you perform the following steps so you are familiar with how Business Desk is configured for your site.

In Campaigns, perform the following task:

  • Set up Your Reference Tables. The Reference Tables store industry codes, page groups, and content sizes. Commerce Server provides several popular industry codes and content sizes.

In Analysis, perform the following tasks:

  1. Review the existing reports to ensure they meet your needs; for a list of reports provided with Commerce Server, see Commerce Server Reports. If you need different reports, you can create custom reports, or contact your site developer. To create new reports, see Creating a New Dynamic Report.

  2. Contact your system administrator to determine when data will be imported into the Data Warehouse. Before you can run a report, the system administrator must import the data into the Data Warehouse.

  3. Contact your system administrator to determine when Segment models will be built. Before you can view Segment models, your system administrator must build them.

In Users, perform the following tasks:

  1. Review the existing profile definitions to ensure they meet your needs; for a list of profile definitions provided with Commerce Server, see Sample Profile Definitions. To add profile definitions, contact your system administrator. To add properties to profile definitions, see Adding Properties to a Profile Definition.

  2. Review the existing site terms to ensure they meet your needs. To add site terms, see Adding a Site Term.


Common Tasks

After your site is open, you may need to perform the following tasks frequently:

  • Resetting a User Password

  • Finding and Sorting Orders

  • Pricing Products

  • Discounting Product Prices

  • Targeting an Ad or Discount

  • Running Reports

  • Exporting a Static Report

  • Adding an Organization

  • Adding a Site Term


Example: Closing the Loop

You use Commerce Server Business Desk to analyze your business, and then use the results of that analysis to make your site more effective and relevant to your users. Users who find your site increasingly relevant, useful, and convenient will feel increased loyalty to your company and will return to your site more often. This "closed loop" functionality of collecting user data, analyzing the data, and then delivering information to users who meet your target criteria directly impacts your Web site business by converting browsers into buyers, and buyers into repeat users.

Commerce Server provides several ways for you to analyze site activity and then update your site. The following example procedures explain just one closed loop scenario: how to customize user profile data, analyze the user information, and then create a direct mail campaign to target those users that meet your target criteria.

Step 1: Add Properties to a Profile Definition

Step 2: Publish Profile Changes on Your Web Site

Step 3: Add a User with a New Property

Step 4: Run a Static Report

Step 5: Export a Static Report to a List

Step 6: Create a Direct Mail Campaign

Step 1: Add Properties to a Profile Definition

You use the Profile Designer module to specify which data you want to collect about your users. To specify which data you want to collect, you add properties to user profile definitions. For example, you can add a property such as "favorite color," use that property to identify users who like blue, and then target blue products to those users.

To add a new property to a user profile

  1. In Users, click Profile Designer.

  2. In the Profiles screen, select the User Object profile definition, and then click Open on the toolbar.

  3. In the Profile screen, in the Properties list, select General information, and then click Add.

  4. In the Add dialog box, select the Add a new property option, and then click OK.

  5. In the Attributes section, do the following:
    Use this | To do this
    Name | Type the name for the property, such as FavoriteColor.
    Display name | Type a display name for the property, such as Favorite Color.

  6. In the Advanced Attributes section, do the following:
    Use this | To do this
    Active | Verify Yes is selected.
    Map to Data In the Map to Data box, click the ellipse button […] to open the Data Source Picker dialog box.

    In the Data Source Picker dialog box, select ProfileService_SQLSource, select User Object, and then scroll down and select Custom Property 1.

    If you do not map the property to a data source, the property will not be available for editing in the User or Organizations modules.

  7. Click OK, and then click Apply.

  8. To save the property and return to the Profile Designer screen, click Save and go back on the toolbar.

The new property is added to the profile definition. You now publish the profile changes on your Web site.

Step 2: Publish Profile Changes on Your Web Site

After you add a property to a profile definition, you use the Publish Profiles module to publish your changes to your Web site.

To publish profile changes

  1. In Users, click Publish Profiles.

  2. In the Publish Profiles screen, select the site, and then click Publish profile changes to production and refresh the cache on the toolbar.

The profile changes are updated and are available on your Web site. You can now add a user with the new profile.

Step 3: Add a User with a New Property

You use the Users module to add user profile information for registered users. In this step, you enter the user profile information, including the Favorite Color property you added in Step 1.

To add a user with the new profile

  1. In Users, click Users.

  2. In the Registered User Management screen, click Add on the toolbar.

  3. In the New User screen, in the General information section, do the following:
    Use this | To do this
    Logon name | Type a logon name for the new user.
    User password | Type a password for the new user.
    Email | Type an e-mail address for the new user.
    Last name | Type a last name for the new user.
    First name | Type a first name for the new user.
    Favorite Color | Type blue.

  4. To save the new user and return to the Users screen, click Save and go back

The user is added to the Commerce Server database. You can now target the user based on the profile information for the user.

Step 4: Run a Static Report

After the data that contains information about user and server activity is processed into the Data Warehouse, your system administrator imports the information into Microsoft SQL Server Enterprise Manager. After the log files are imported, you use the Analysis modules to analyze your user data by running reports that show the characteristics and past behavior of your users. You can then update your site to target ad or products to those users. For example, you can run a Registered User Properties report, analyze the information in the report, and then select those users you want to target a direct mail campaign to.

To run a static report

  1. In Analysis, click Reports.

  2. In the list of available reports, select Registered User Properties, and then click Run on the toolbar.

  3. In the Run a report dialog box, in the Site Name section, do the following:
    Use this | To do this
    Operand | From the drop-down list, select an operand (All, Equals, Not equal to, Like, Not Like) to determine which site the report will run for.
    Parameter value | Type the name of the site that you want the report to run for.

  4. In the Run a report dialog box, in the Number of users section, do the following:
    Use this | To do this
    Select From the drop-down list, select a parameter for the number of users to include in the report:
    • All. All users in the Commerce Server database who meet the query criteria.

    • Top. The upper limit on the number of users in the Commerce Server database who meet the query criteria. You type the number of top users in the Parameter value box.

    • Distinct. A particular user in the Commerce Server database who meets the query criteria.
    Parameter value | Type the number of top users that you want the report to return.

  5. Click OK.

The static report runs and, when completed, is available for viewing in the Completed Reports module. The report can now be exported as a list into List Manager, and then used to target users in a direct mail campaign.

Step 5: Export a Static Report to a List

Data from static reports can be used in direct mail campaigns. A direct mail campaign can be targeted toward specific users by using mailing lists that reside in List Manager.

To export a static report

  1. In Analysis, click Reports.

  2. In the Reports list, select the static report containing the data you want to export, for example, Registered User Properties, and then click Export on the toolbar.

  3. In the Run a report dialog box, in the Site Name section, do the following:
    Use this | To do this
    Operand | From the drop-down list, select an operand (All, Equals, Not equal to, Like, Not Like) to determine which site the report will run for.
    Parameter value | Type the name of the site that you want the report to run for.

  4. In the Run a report dialog box, in the Number of users section, do the following:
    Use this | To do this
    Select From the drop-down list, select a parameter for the number of users to include in the report:
    • All. All users in the Commerce Server database who meet the query criteria.

    • Top. The upper limit on the number of users in the Commerce Server database who meet the query criteria. You type the number of top users in the Parameter value box.

    • Distinct. A particular user in the Commerce Server database who meets the query criteria.
    Parameter value | Type the number of top users that you want the report to return.

  5. Click OK.

  6. In the Export report as a list dialog box, do the following:
    Use this | To do this
    Static | Verify that Static is selected.
    List Name | Type a unique name for the list.

  7. Click OK.

Your static report is exported to List Manager as a list. You can now use the list to build a direct mail campaign

Step 6: Create a Direct Mail Campaign

Direct mail campaigns are a way to get users to view your ads. You use the Campaigns modules to create direct mail campaigns, which can be targeted toward specific users by using mailing lists that reside in List Manager. You can use these lists to run direct mail jobs in order to target your users more successfully.

The following procedure assumes you have already created a customer and a campaign.

  1. In Campaigns, click Campaign Manager.

  2. In the Campaign Manager screen, select the campaign for which you want to create a direct mail campaign, click Add on the toolbar, and then select New Direct Mail Campaign from the drop-down list.

  3. In the Direct Mail Properties screen, in the Direct Mail Item section, do the following:
    Use this | To do this
    Direct Mail Name | Type a name for the direct mail job.
    Message From e-mail Address | Type the address that the direct mail is being sent from.
    Reply to address Type the address to which the recipient is to reply if different from the default address.

    This box defaults to the address the direct mail is being sent from.
    Message subject | Type the subject text for this direct mail job.
    File Path or URL Containing Message Body | Type the path of the file or the URL that you are using to display the direct mail message.
    Attachment Type the file path and name of the attachment being sent with the message.

    If no attachment is being sent, leave this box unchecked.
    Mailing list | Select the mailing list that this direct mail campaign will use, for example, Registered User Properties, from the drop-down list.
    Personalization Select Yes or No from the drop-down list.
    • Yes - Enables personalization for this direct mail campaign.

    • No - Disables personalization for this direct mail campaign.
    Mail Format Select the format for this mail.

    The options are:

    • Text - Formats the mail in ASCII format.

    • MHTML - Formats the mail in multilingual HTML.

    • MIME - Formats the mail with Multipurpose Internet Mail Extensions.
    Comments (not included in message) | Type any required comments that are pertinent to this direct mail job.

  4. To save the direct mail campaign and return to the Campaign Manager screen, click Save and go back on the toolbar.

The direct mail campaign is added to Campaign Manager and the mailing will be sent to users from the specified mailing list, closing the loop.


Using Business Desk Online Help

To access help from Commerce Server Business Desk, click Help. Help is displayed for any screen and any task for which you need assistance.

Business Desk offers both dialog box level help and task help. Dialog box level help describes the required entries in specific text boxes. Task help steps you through a specific task. Documentation written specifically for system administrators and site developers is also provided within Commerce Server 2000.

Printing Topics

Contents Tab

Index Tab

Search Tab

Glossary Terms

Printing Topics

  • Right-click the topic you want to print, and then click Print.

  • To print a pop-up topic, right-click inside the pop-up window, and then click Print.

  • To print all topics within a book, on the Contents tab, select the book. On the Help toolbar, click Options, click Print, and then click Print the selected heading and all subtopics.

Note

  • Printing large illustrations could result in incomplete printing. If an illustration is very large, the right edge of the code or illustration might extend beyond the margin boundary and will not print.

Contents Tab

In the opening pane for Business Desk Help, click the Contents tab to view the table of contents for Business Desk Help. Click the name of any topic to view that topic or click the plus sign (+) to expand the topic. The topic appears on the right side of the Help window in the content pane.

To print the current topic or the current topic plus all the subtopics, click [image]. You can also click the Synchronization button to synchronize the table of contents with the content pane on the right. You will need to synchronize the table of contents with the content pane after you perform a search.

Index Tab

To view the online index for Business Desk, click the Index tab.

To search for a word in the Index

  1. In the Business Desk Documentation window, click the Index tab.

  2. In the Type in the keyword to find box, enter a keyword or phrase on which to search. The index automatically displays the closest word match contained in the index

  3. If you find a match, click Display and a Topics Found box appears listing the topics in which the word appears.

  4. To find the information you want, select the topic and then click Display. The topic appears in the content pane.

Search Tab

To search for specific keywords or phrases within Business Desk Help, click the Search tab.

To search for a keyword or phrase

  1. In the Business Desk Documentation window, click the Search tab.

  2. In the Search for box, enter a keyword or phrase on which to search, and then click Search. The results list appears in the content pane.

    You can use the Select type of search box to select a specific kind of search. By default, it searches for the exact phrase you type. You can select one of the following:

    Type of Search

            Description

    Exact Phrase

            Searches for the exact sequence of the words you type. For example, if you type Business Desk, the search returns only those topics that contain "Business Desk."

    Standard Search

            Searches for all forms of the words you type. For example, if you type Business Desk, the search engine returns all topics that have "business" and topics that have "desk."

  3. To display the topic you want to view, click the topic title.

The topic is displayed in the content pane.

Glossary Terms

When a Business Desk help topic appears in the content pane, you may see some words highlighted in green. You can click the highlighted word or words to display a definition for the term. You can also find an alphabetical listing of these terms at the end of the Business Desk table of contents under Glossary.


If You Need Additional Help

If you need additional help using or customizing Commerce Server Business Desk to meet your needs, contact either your system administrator or site developer. The following table lists the tasks performed by each person.

Contact To do this
System administrator
  • Create a shared folder for you to use when importing and exporting catalogs

  • Convert external catalogs to XML or CSV files so you can import them

  • Set up trading partners so you can send and exchange catalogs with them using BizTalk Server

  • Import data into the Data Warehouse so you can run reports

  • Build Segment models so you can view them using Segment Viewer

  • Add new profile definitions and data sources so you can collect additional profile data

  • Secure Business Desk modules

  • Schedule direct mail jobs

  • Troubleshoot Business Desk

  • Troubleshoot the Web site environment
Site developer
  • Integrate your Web site with existing systems

  • Customize Business Desk functionality

  • Add new modules to Business Desk

  • Add related-sell functionality to your site, such as cross-sell and up-sell items

  • Ad-enable a Web page so you can target page groups

  • Create custom reports

  • Extend the Data Warehouse


Business Desk Tutorial

Microsoft Commerce Server 2000 provides a comprehensive set of tools to help you build commerce applications for the Web. The following tutorials provides step-by-step instructions for using Commerce Server to manage your Web sites:

  • Business-to-Consumer Tutorial

  • Business-to-Business Tutorial

You will use the modules contained in Commerce Server Business Desk to manage different aspects of your Web site.


Business-to-Consumer Tutorial

The Business-to-Consumer (Retail) Business Desk tutorial provides easy to follow instructions for using Commerce Server features to import and create catalogs, manage user profiles, create ad campaigns, target site users, analyze site usage, and run reports.

The Retail tutorial contains the following labs for the Retail Solution Site. For the location of your Retail Solution Site, ask your system administrator. It is important to run each lab in the order listed below. Each lab is a prerequisite for subsequent labs:

  • Adding a Shipping Method and a Tax Rate

  • Creating a Catalog

  • Creating a Site Term

  • Adding a User with a New Profile

  • Importing a Catalog and Performing Free Text and Specification Searches

  • Creating an Ad Campaign

  • Creating a Target Expression

  • Creating a Discount Campaign

  • Importing a Log File

  • Running a Dynamic Report

  • Running a Static Report

  • Exporting a Static Report

  • Creating a Direct Mail Campaign


Adding a Shipping Method and a Tax Rate

The Commerce Server Business Desk Orders modules enable you to view order status information, add and modify shipping methods, and set up tax rates for different countries, states, and regions.

In this lab, you will add a shipping method, add and edit shipping rates by subtotal, and set up a tax rate for the state of Washington.

To add a shipping method

  1. Open Commerce Server Business Desk from either the Start menu or the Desktop.

  2. In Orders, click Shipping Methods.

  3. In the Shipping Methods screen, click Add on the toolbar, and then select Charge by Subtotal from the drop-down list.

  4. In the Charge by SubTotal - New screen, in the Shipping Method Properties section, do the following:
    Use this | To do this
    Name | Type Vigor Airlines.
    Description | Type We'll ship anything.
    Enabled | Verify the Shipping method enabled check box is checked.

  5. In the Rates section, click New, and then do the following:
    Use this | To do this
    Price, up to | Type 10.
    Shipping Rate | Type 5.

  6. Click Accept.

  7. To add another shipping rate, click New, and then do the following:
    Use this | To do this
    Price, up to | Type 20.
    Shipping Rate | Type 10.

  8. Click Accept.

  9. To add the over 20 shipping rate, do the following:
    Use this | To do this
    Price, up to | Double-click over 20.
    Shipping Rate | Type 15.

  10. Click Accept.

The new shipping rates are defined by subtotal.

To edit a shipping rate

  1. In the Charge by SubTotal - New screen, in the Rates section, do the following:
    Use this | To do this
    Price, up to | Select 20, and then click Edit.
    Shipping rate | Click after 10, and then change the shipping rate to 10.50.

  2. Click Accept.

  3. To save the new shipping rates and return to the Shipping Methods screen, click Save and go back on the toolbar.

The shipping rates are saved and will be applied to purchases on the Retail site by subtotal.

To add a tax rate

  1. In Orders, click Tax Rates.

  2. In the Tax screen, click New, and then do the following:
    Use this | To do this
    Country | Select United States of America from the drop-down list.
    State/Region | Select Washington from the drop-down list.
    Tax rate (%) | Type 10.

  3. Click Accept.

  4. To save the new tax rate and return to the Business Desk Welcome screen, click Save and go back on the toolbar.

The tax rate is saved and will be applied to purchases shipped to Washington state addresses.


Creating a Catalog

You can use the Catalog modules to add and update product data, and create catalogs of products. A catalog consists of two main parts: the catalog schema and the catalog data. To create a catalog, you first create the catalog schema, and then add the catalog data. A catalog schema specifies the structure of the catalog and catalog data is the content of the catalog.

Catalog data is organized into the following hierarchical groups:

  • Categories are containers for products or sub-categories. Each category is an individual instance of a category definition.

  • Products are the items for sale in a catalog. Each product is an individual instance of a product definition. A group of closely related products make up a product family.

  • Products are defined by a combination of property definitions. For example, if you have a product definition named Shirts that has the properties Color, Length, and Size, you create a product for each color, length, and size combination that you want to include in your catalog.

  • Product variants are specific items that are grouped with related variants that together form a product.

In this lab, you will use the Catalog Designer module to create property and product definitions, and to add new products to a catalog. Property definitions define the properties for describing the products in your catalog and product definitions define a particular type of product.

To create property definitions

  1. In Catalogs, click Catalog Designer.

  2. In the Catalog Designer: Category Definitions screen, click View on the toolbar, and then select Property Definitions from the drop-down list.

  3. In the Catalog Designer: Property Definitions screen, click Add on the toolbar, and then select Text from the drop-down list.

  4. In the Property Definition: New (Text) screen, do the following:
    Use this | To do this
    Name | Type MyTitle.
    Display name | Type My Title.
    Display in products list | Select Yes to display the property definition in the products list.

  5. To save the new property definition and create an additional one, click Save and create new on the toolbar.

  6. In the New Property Definition dialog box, select Text from the Type drop-down list, and then click Continue.

  7. In the Property Definition: New (Text) screen, do the following:
    Use this | To do this
    Name | Type MyAuthor.
    Display name | Type My Author.

  8. To save the new property definition and create an additional one, click Save and create new on the toolbar.

  9. In the New Property Definition dialog box, select Text from the Type drop-down list, and then click Continue.

  10. In the Property Definition: New (Text) screen, do the following:
    Use this | To do this
    Name | Type MyISBN.
    Display on site | Select the Yes check box.
    Free text searchable | Clear the Yes check box.
    Specification searchable | Clear the Yes check box.
    Minimum length | Type 10.
    Maximum length | Type 20.
    Export to Data Warehouse | Select the Yes check box.

  11. To save the new property definition and return to the Catalog Designer: Property Definitions screen, click Save and go back on the toolbar.

The new property definitions are saved. You can now add your product definitions.

To add a product definition

  1. In the Catalog Designer: Property Definitions screen, click View on the toolbar, and then select Product Definitions from the drop-down list.

  2. In the Catalog Designer: Product Definitions screen, click Add on the toolbar.

  3. In the Product Definition: New screen, in the Product Definition Properties section, in the Name box, type MyBook.

  4. In the Product Properties section, in the Available properties box, scroll down to view MyAuthor, MyISBN, and MyTitle. Hold down the [CTRL] key, and click MyAuthor, MyISBN, and MyTitle, and then release the [CTRL] key.

  5. Click Add.

The selected properties are moved to the Assigned properties box.

  6. To save the new product definitions and return to the Catalog Designer: Product Definitions screen, click Save and go back on the toolbar.

The MyBook product definition appears in the Name box.

  7. Double-click the MyBook product definition.

The Description, Name, Weight, MyAuthor, MyISBN, and MyTitle product properties appear under the MyBook product definition, in addition to the Description, Name, and Weight properties.

To add a new catalog

  1. In Catalogs, click Catalog Editor.

  2. In the Catalogs screen, click Add on the toolbar, and then select New Catalog from the drop-down list.

  3. In the Catalog: new screen, in the Catalog Properties section, do the following:
    Use this | To do this
    Name | Type MyBooks.
    Product unique ID | Select MyISBN from the drop-down list.
    Product variant unique ID | Select MyISBN from the drop-down list.

  4. To save the catalog properties, click Save on the toolbar.

The catalog properties are saved with the new catalog.

To add a new category based on the Department category definition

  1. In the Categories section, click New.

  2. In the New Category dialog box, select Department, and then click Continue.

  3. In the Category Properties section, do the following:
    Use this | To do this
    Name | Type Business Books.
    Description | Type Business titles off the shelf.

  4. To save the new category and return to the Catalog - MyBooks screen, click Save and go back on the toolbar.

    The Business Books category is created based on the Department category definition.

  5. To return to the Catalogs screen, click Back on the toolbar.

The MyBooks catalog appears in the Name box. You can now add a new product to the catalog.

To add a new product to the catalog

  1. In the Catalogs screen, select the MyBooks catalog, and then click Open on the toolbar.

  2. In the Products section, click New.

  3. In the New Product dialog box, select MyBook, and then click OK.

  4. In the Product Properties section, do the following:
    Use this | To do this
    MyISBN | Type 1-2345-6789-0.
    Description | Type Bill's latest thoughts.
    Name | Type Business @ the Speed of Thought.
    MyAuthor | Type Bill Gates.
    MyTitle | Type Business @ the Speed of Thought.
    Price | Type 19.99.

  5. In the Assigned Categories section, in the Available Categories box, select Business Books.

  6. Click Add.

The new book is assigned to the Business Books category.

  7. To save the new product in the catalog and return to the Catalog - MyBooks screen, click Save and go back on the toolbar.

The new product, the book Business @ the Speed of Thought, is saved in the catalog. You can now add another product.

To add another product to the catalog

  1. In the Products section, click New.

  2. In the New Product dialog box, select MyBook, and then click OK.

  3. In the Product Properties section, do the following:
    Use this | To do this
    MyISBN | Type 2-3452-8892-9.
    Description | Type Bill's first book.
    Name | Type The Road Ahead.
    MyAuthor | Type Bill Gates.
    MyTitle | Type The Road Ahead.
    Price | Type 29.99.

  4. In the Assigned Categories section, select Business Books in the Available Categories box.

  5. Click Add.

  6. In the Product Relationships section, click New, and then do the following:
    Use this | To do this
    Relationship | Type Other books by Bill Gates.
    Item | Click the ellipse button […] to open the Product Picker dialog box.

  7. In the Product Picker dialog box, do the following:
    Use this | To do this
    Categories | Select Business Books.
    Products in Category | Select the MyISBN number 1-2345-6789-0, (Business @ the Speed of Thought).

  8. Click OK, and then in the Product Relationships section, click Accept.

A relationship to the book Business @ the Speed of Thought is established.

  9. To save the new product in the catalog and return to the Catalog - MyBooks screen, click Save and go back on the toolbar.

  10. To return to the Catalogs screen, click Back on the toolbar.

The new product, the book The Road Ahead is saved in the catalog. The new product will display on the Retail site in the Business Books category.

Site Verification Steps

To verify your changes on the Retail site

  1. To open the Retail site, in Internet Explorer type http://<computername>/retail on the Address line.

  2. Click New user in the left pane under Login, and then do the following:
    Use this | To do this
    User name | Type Joe Visitor.
    Password | Type open_sesame.
    Confirm Password | Type open_sesame.

  3. Click Submit.

  4. Click the Business Books category, select Business @ the Speed of Thought, and then click Add to Basket.

  5. Click Basket in the screen header section, and then click Check-out.

    The text Address book is empty appears.

  6. Click Click here to add an address, and then do the following:
    Use this | To do this
    Address name | Type Joey.
    First name | Type Joe.
    Last name | Type Visitor.
    Address 1 | Type One Microsoft Way.
    City | Type Redmond.
    State | Select WA from the drop-down list.
    Zip Code | Type 98052.
    Country | Select United States of America from the drop-down list.
    Address type | Select Shipping address from the drop-down list.

  7. Click Submit.

  8. On the Ship-to address screen, click Continue.

  9. On the Shipping options screen, click Check-out.

  10. Verify that the tax rate is 10 percent of the order subtotal and that the shipping rate is $10.50, and then click Check-out.

  11. On the Credit Card Payment screen, do the following:
    Use this | To do this
    Name on Card | Verify Joe Visitor as the name on the card.
    Card number | Type 4111-1111-1111-1111.
    Type | Select VISA from the drop-down list.
    Expiration Month | Select July from the drop-down list.
    Expiration Year | Select 2003 from the drop-down list.

  12. To confirm your order, click Submit.

The Order confirmation screen appears with the order number link enabled.

To verify that the product profile matches the item you added

  1. In the left pane, under Customer Service, click Orders, and then click View Item Details.

  2. In the Order Details screen, verify the following Line Items:
    Box | Description
    Name | Business @ the Speed of Thought.
    Description | Bill's latest thoughts.
    Product ID | 1-2345-6789-0.
    Quantity | 1.
    Unit Price | 19.99.

  3. In the left pane, under Customer Service, click Profile.

    The profile matches the information you entered earlier for Joe Visitor. You can edit the user details, and then click Save to update the user profile.

  4. Close the browser window.


Creating a Site Term

You use the Site Terms Editor module to define values that are pertinent to your site. Site terms provide an easy way for you to standardize the values that are used throughout your site. You can use site terms to target products in your catalogs, content, and advertisements to site users.

In this lab, you will add the site terms, male and female. Once you have created your site terms, you will set up a user profile to include the site terms so you can later target an advertisement to those site users that match the user profile.

To create a site term

  1. In Users, click Site Terms Editor.

  2. In the Site Terms Editor screen, click Add.

  3. In the Add dialog box, select Add a new group, and then click OK.

  4. In the Attributes section, do the following:
    Use this | To do this
    Name | Type PersonalInfo.
    Display name | Type Personal Info.

  5. Click Apply.

  6. In the Site term structure list, select Personal Info, and then click Add.

  7. In the Add dialog box, select Add a new site term, and then click OK.

  8. In the Site Term Attributes section, do the following:
    Use this | To do this
    Name | Type Gender.
    Display name | Type Gender.

  9. In the Terms section, click New, and then do the following:
    Use this | To do this
    Term name | Type Male.
    Display name | Type Male.

  10. Click Accept.

  11. In the Terms section, click New, and then do the following:
    Use this | To do this
    Term name | Type Female.
    Display name | Type Female.

  12. Click Accept, and then click Apply.

  13. To save the site terms and return to the Business Desk Welcome screen, click Save and go back on the toolbar.

The site terms Male and Female are saved and can now be added to a user profile.

To add a site term to a user profile

  1. In Users, click Profile Designer.

  2. In the Profiles screen, in the Name box, select User Object, and then click Open on the toolbar.

  3. In the Profile: User Object screen, in the Properties list, select General information, and then click Add.

  4. In the Add dialog box, select Add a new property, and then click OK.

  5. In the Attributes section, do the following:
    Use this | To do this
    Name | Type Gender.
    Display name | Type Gender.
    Type | Select Site Term from the drop-down list.
    Type reference | Click the ellipse button […], select Personal Info, and then select Gender.

  6. Click OK.

  7. In the Advanced Attributes section, do the following:
    Use this | To do this
    Active | Verify the Yes check box is selected.
    Map to Data | Click the ellipse button […] to open the Data Source Picker dialog box.

  8. In the Data Source Picker dialog box, select ProfileService_SQLSource, select User Object, scroll down, and then select Custom Property1 (STRING).

  9. Click OK.

  10. In the Custom Attributes section, do the following:
    Use this | To do this
    Name | Select sUserAccess, and then click Edit.
    Value | Change the value to 1.

  11. Click Accept, and then click Apply.

  12. To save the site term with the user profile and return to the Profiles screen, click Save and go back on the toolbar.

After you add a property to a profile definition, you publish your changes to your Web site.

To publish the profile changes on your Web site

  1. In Users, click Publish Profiles.

  2. In the Publish Profiles screen, select the site whose changes you want to publish, and then click Publish on the toolbar.

The profile changes are updated and are available on the Web site.


Adding a User with a New Profile

You use the Users module to manage registered users — those Web site users who are recognized by your site because they have completed an online registration form, or in some way have established a user account on your site.

In this lab, you will be adding two new users with the new site terms, Male and Female that you created in the previous lab.

To create the male user

  1. In Users, click Users.

  2. In the Users screen, click Add on the toolbar.

  3. In the New User screen, in the General information section, do the following:
    Use this | To do this
    Logon Name | Type JackUser.
    User password | Type open_sesame.
    Email | Type JackUser@Microsoft.com.
    Last name | Type User.
    First name | Type Jack.
    Gender | Select Male from the drop-down list.

  4. To save the male user and create a new user, click Save and create new on the toolbar.

The male user is saved. You can now add another new user.

To create the female user

  1. In the General information section, do the following:
    Use this | To do this
    Logon name | Type JillUser.
    User password | Type open_sesame.
    Email | Type JillUser@Microsoft.com.
    Last name | Type User.
    First name | Type Jill.
    Gender | Select Female from the drop-down list.

  2. To save the female user and return to the Users screen, click Save and go back on the toolbar.

The male and female users are saved with the new male and female site terms.

Site Verification Steps

To verify your changes on the Retail site

  1. To open the Retail site, in Internet Explorer type http://<computername>/retail on the Address line.

  2. On the Retail screen, click Click here to enter the site as a guest visitor.

  3. Click Sign-in in the left pane under Login.

  4. In the Sign-in screen, do the following:
    Use this | To do this
    User Name | Type JackUser.
    Password | Type open_sesame.

  5. Click Submit.

  6. In the left pane, under Customer Service, click Profile.

  7. Verify that the newly created site term Gender is displayed under General information.

  8. Close the browser window.


Importing a Catalog and Performing Free Text and Specification Searches

You use the Catalog Editor module to work with categories and catalogs. You can create, modify, and delete categories and catalogs. You can also use the Catalog Editor module to import catalogs. You can import a catalog from either an Extensible Markup Language (XML) file or a comma-separated value (.csv) file.

In this lab, you will import an XML catalog file. Then you will visit the site and perform both a free text search and a specification search to display products, product families, and product families with variants that have searchable properties that match your search criteria. After you find a product that matches your search criteria, you will add it to your shopping basket.

To copy the XML catalog files to the Catalogs folder

  1. Copy the Hardwarefull.xml file in the \Tutorial folder at the root of the CDROM to the <drive:>\Inetpub\wwwroot\RetailBizDesk\Catalogs folder.

  2. Copy the Booksfull.xml file in the \Tutorial folder at the root of the CDROM to the <drive:>\Inetpub\wwwroot\RetailBizDesk\Catalogs folder.

To import the Hardwarefull.xml catalog file

  1. In Catalogs, click Catalog Editor.

  2. In the Catalog Editor screen, click Import on the toolbar, and then select Import XML from the drop-down list.

  3. In the Import XML Catalog dialog box, do the following:
    Use this | To do this
    File name | Type <drive>:\Inetpub\wwwroot\RetailBizDesk\Catalogs\hardwarefull.xml.
    Delete any existing catalog data | Verify that this check box is not selected.

  4. Click OK.

  5. In the Business Desk: Import XML Catalog dialog box, click OK.

The Hardware catalog is imported and available on the Retail site.

Note

  • The catalog does not yet appear in the Name box in the Catalog Editor.

To import the Booksfull.xml catalog file

  1. In the Catalog Editor screen, click Import on the toolbar, and then select Import XML from the drop-down list.

  2. In the Import XML Catalog dialog box, do the following:
    Use this | To do this
    File name | Type <drive:>\Inetpub\wwwroot\RetailBizDesk\Catalogs\Booksfull.xml.
    Delete any existing catalog data | Verify that this check box is not selected.

  3. Click OK.

  4. In the Business Desk: Import XML Catalog dialog box, click OK.

The Books catalog is imported and available on the Retail site.

Note

  • The catalog does not yet appear in the Name box in the Catalog Editor.

    Use the Catalog Editor module to refresh and publish a catalog on your Web site. You will have to refresh and publish your catalog whenever you make any change in order to ensure that changes are reflected on your Web site.

To refresh and publish the catalog

  1. In Catalogs, click Catalog Editor.

  2. In the Catalog Editor screen, click Publish a catalog on the toolbar.

The catalog is updated and published on the Web site.

To perform a free text search

  1. To open the Retail site, in Internet Explorer type http://<computername>/retail on the Address line.

  2. In the Product Search box, type book, and then click Search.

    The Search Results screen appears with the items matching your search criteria, including:

    • Products having a variant that has a searchable property that matches the search criteria.

    • A product family, containing The Road Ahead that matches the searchable criteria.

    • A product category that has searchable product property descriptions that match the search criteria.

To perform a specification search

  1. Click the Advanced search link.

    The Advanced Search screen appears containing the Hardware and Books catalogs.

  2. Under the Hardware catalog, click Mice.

    The message Number of matches found so far: 7 is displayed.

  3. To narrow your search criteria, in the Advanced Search screen, do the following:
    Use this | To do this
    Cordless | Select Yes.
    OS | Select Win 9x.
    ScrollWheel | Select Yes.

  4. Click Search.

    The message Number of matches returned: 1 is displayed.

Your search criteria has narrowed down the results to one match, the Microsoft® Cordless Wheel Mouse.

To display product variants

  1. Click Microsoft® Cordless Wheel Mouse.

    Scroll down to the list of variations. The product is displayed with two variations. You can choose to add either of the variations to your shopping basket.

  2. Select the second variant Color: White, SKU: C5700001w, List Price $44.95.

  3. Click Add to Basket, and then click Check-out.

  4. In the Ship-to address form, do the following:
    Use this | To do this
    First Name | Type Amy.
    Last Name | Type Jones.
    Address 1 | Type One Microsoft Way.
    City | Type Redmond.
    State | Select Washington from the drop-down list.
    Zip Code | Type 98052.

  5. Click Submit.

  6. On the Shipping options screen, click Check-out.

  7. On the Order summary screen, click Check-out.

  8. On the Credit card screen, do the following:
    Use this | To do this
    Expiration Month | Select March from the drop-down calendar.
    Expiration Year | Select 2003 from the drop-down calendar.

  9. Click Submit.

    The Order Confirmation screen is displayed with the order number.

  10. Close the browser window.


Creating an Ad Campaign

You use the Commerce Server Business Desk Campaigns modules to create and schedule marketing campaigns. You can create ad campaigns, direct mail campaigns, and discount campaigns. With the Campaigns modules you can manage different types of campaigns for several customers. You can also use the Reference Tables module in Campaigns to set up your industry codes. Industry codes enable you to identify the associated industry of an ad or discount, thus preventing two ads or discounts from customers within the same industry from appearing on the same Web page.

In this lab, you will add an industry code for Books. Then you'll add a new campaign customer, Lucerne Publishing, and then a new advertising campaign named Bill's Books.

To add an Industry Code to the Reference Tables

  1. In Campaigns, click Reference Tables.

  2. In the Reference Tables screen, in the Industry Codes section, click New.

  3. In the Industry Code box, type Books.

  4. Click Accept.

  5. To save the new industry code and return to the Business Desk Welcome screen, click Save and go back on the toolbar.

The new industry code is saved. You can now prevent two ads from promoting different books on the same Web page.

To add a campaign customer

  1. In Campaigns, click Campaign Manager.

  2. In the Campaign Manager screen, click Add on the toolbar, and then select New Customer from the drop-down list.

  3. In the Campaign Manager - New (customer) screen, in the Customer Properties section, do the following:
    Use this | To do this
    Name | Type Lucerne Publishing.
    Type | Select Advertiser from the drop-down list.
    Industry | Select Books from the drop-down list.

  4. To save the new customer and return to the Campaign Manager screen, click Save and go back on the toolbar.

The new customer is saved and appears in the Campaign Manager screen. You can now add a new campaign.

To add a campaign

  1. In the Campaign Manager screen, select Lucerne Publishing.

  2. In the Campaign Manager screen, click Add on the toolbar, and then select New Campaign from the drop-down list.

  3. In the Campaign Properties section, do the following:
    Use this | To do this
    Campaign Name | Type Bill's Books.
    Start date | Select yesterday's date from the drop-down calendar.
    End date | Select a date one month from today from the drop-down calendar.
    Status | Select Active from the drop-down list.

  4. In the Advertising/Campaign Goaling section, do the following:
    Use this | To do this
    Set goals by | Select Advertising Items from the drop-down list.
    Schedule by | Select Requests from the drop-down list.

  5. To save the campaign and return to the Campaign Manager screen, click Save and go back on the toolbar.

The Bill's Books campaign is saved and is goaled at the advertising item level. You can now create a new ad and target those users to whom you want to display the ad.


Creating a Target Expression

You use the Campaign Expressions module to define the user group that you want to target. You might want to target an advertisement, direct mail, or apply a discount campaign to this group.

In this lab, you will create an ad campaign targeting all male customers. You defined the gender property in the "Creating a Site Term" lab, so you can now use the gender profile property to target the ad.

Note

  • In this lab, in order to view the advertisement, an image is required in the Retail site folder.

To copy image files to your site

  • Copy the image file in the \Tutorial folder at the root of the CDROM to the <drive:>\Inetpub\wwwroot\Retail\Images folder.

To target an expression

  1. In Campaigns, click Campaign Expressions.

  2. In the Campaign Expressions: Target Expressions screen, click Add on the toolbar.

  3. In the Target Expression dialog box, do the following:
    Use this | To do this
    Name | Type MaleUsers, and then click New.
    Target based on the following conditions
    • First box - Select UserObject from the drop-down list, select General , and then select Gender.

    • Second box - Select Is Equal To from the drop-down list.

    • Third box - Click the ellipse button […], and then select the Male site term token, and then click OK.

  4. Click Apply.

  5. To save the expression, click Save.

The expression is saved and the ad will target male users.

To create a target group

  1. In Campaigns, click Target Group.

  2. In the Target Group screen, click Add on the toolbar.

  3. In the New Target Group: New screen, do the following:
    Use this | To do this
    Target group name | Type MaleGroup, and then click New.
    Expression | Select MaleUsers from the drop-down list.
    Action | Select Require from the drop-down list.

  4. Click Accept.

  5. To save the target group and return to the Target Group screen, click Save and go back on the toolbar.

The target group is created using the MaleUsers target expression.

To create a new ad

  1. In Campaigns, click Campaign Manager.

  2. In the Campaign Manager screen, click the arrow next to the Lucerne Publishing campaign, and then select Bill's Books.

  3. In the Campaign Manger screen, click Add on the toolbar, and then select New Ad from the drop-down list.

  4. In the Campaign Manager - Lucerne Publishing - Bill's Books - New (ad) screen, in the Add Properties section, do the following:
    Use this | To do this
    Ad name | Type TargetMales.
    Status | Select Active from the drop-down list.
    Type | Select Paid Ad from the drop-down list.
    Requests | Type 1000.
    Exposure limit | Select None from the drop-down list.
    Industry | Select Books from the drop-down list.

  5. In the Ad Target section, do the following:
    Use this | To do this
    Page groups | Verify the Show on all Page Groups check box is selected to display the ad on all Retail site Web pages.
    Target groups: Available | Select MaleGroup, and then click Add to move the group to the Assigned box.

  6. Scroll down, and in the Ad Display section, do the following:
    Use this | To do this
    Size | Select Full Banner from the drop-down list.
    Type | Select Image from the drop-down list.
    Image URL | Type http://<computername>/Retail/Images/MSPress.gif.
    Click URL | Type http://MSPress.Microsoft.com.

The ad is defined. You can now preview the ad before sending it to production.

To preview the ad

  1. In the Ad Display section, click Preview.

  2. In the Preview dialog box, select Yes to save the Campaign item.

    A copy of the ad appears in the display area below the Preview button.

  3. To return to the Campaign Manager screen, click Back on the toolbar.

To verify the status of the targeted ad

  1. In the Campaign Manager screen, click Find on the toolbar.

  2. In the Find screen, in the Status box, select All from the drop-down list.

  3. Click Find Now.

  4. In the Filtered View list, click the arrow next to Lucerne Publishing, and then click the arrow next to Bill's Books to verify that the targeted ad appears.

The status of the Targeted Ad is active.

To update the campaign on the Web site

  1. In Campaigns, click Publish Campaigns.

  2. In the Publish Campaigns screen, in the Production Items list, select advertising.

  3. To update the campaign, click Publish a catalog on the toolbar.

The ad campaign is updated and will target male users on the Retail site.

Site Verification Steps

To verify your changes on the Retail site

  1. To open the Retail site, in Internet Explorer type http://<computername>/Retail on the Address line.

  2. Click Sign-in under Login, and then do the following:
    Use this | To do this
    User name | Type JillUser.
    Password | Type open_sesame.

  3. Click Submit.

    The ad does not appear on the Retail site because you targeted the ad to male users.

  4. Close the browser window.

  5. To reopen the Retail site, in Internet Explorer type http://<computername>/Retail on the Address line.

  6. Click Sign-in under Login, and then do the following:
    Use this | To do this
    User name | Type JackUser.
    Password | Type open_sesame.

  7. Click Submit.

    The ad appears on the Retail site because you targeted the ad to male users.

  8. Close the browser window.


Creating a Discount Campaign

After you have created a campaign, you can use the Campaign Manager module to create a discount. You can specify the product to which the discount applies, state the amount of the discount, and specify the number of items a user must purchase before the discount is applied.

In this lab, you will create a site-wide discount campaign offering a 20 percent discount to all users.

To create a discount campaign item

  1. In Campaigns, click Campaign Manager.

  2. In the Campaign Manager screen, click the arrow next to Lucerne Publishing, select Bill's Books, click Add on the toolbar, and then select New Discount from the drop-down list.

  3. In the Campaign Manager - Lucerne Publishing - Bill's Books - New (discount) screen, in the Discount Properties section, do the following:
    Use this | To do this
    Discount name | Type 20% Site-Wide Discount.
    Status | Select Active from the drop-down list.
    Start date | Select today's date from the drop-down calendar.
    End date | Select a date two months from today from the drop-down calendar.

  4. In the Discount Definition section, and then do the following:
    Use this | To do this
    Buy: Anything | Select this check box to apply the discount to any product.
    Get
    • First box - Verify unlimited as the number of items awarded.

    • Second box - Select [any product] from the drop-down list.

    • Third box - Select Percent(%) from the drop-down list.

    • Fourth box - Type 20.

  5. In the Discount Display section, do the following:
    Use this | To do this
    Basket display | Type 20% discount in effect.
    Content size | Select Half Banner from the drop-down list.
    Content type | Select Image.
    Image URL | Type http://<computername>/retail/images/MSPress.gif.
    Click URL | Type http://MSPress.Microsoft.com.

  6. To save the discount and return to the Campaign Manager screen, click Save and go back on the toolbar.

A 20 percent discount will be applied to any product on the Retail site.

To send the discount campaign to production

  1. In Campaigns, click Publish Campaigns.

  2. In the Publish Campaigns screen, select discounts, and then Publish a catalog on the toolbar.

The discount campaign is sent to production.

Site Verification Steps

To verify your changes on the Retail site

  1. To open the Retail site, in Internet Explorer type http://<computername>/Retail on the Address line.

  2. Click Sign-in in the left pane under Login, and then do the following:
    Use this | To do this
    User name | Type JackUser.
    Password | Type open_sesame.

  3. Click Submit.

  4. Click the Business Books category, and then select Business @ the Speed of Thought.

The price of the book is $19.99.

  5. Click Add to Basket.

  6. Click Basket in the screen header section.

    The discount of $4.00 is applied to the final price, which is 20 percent less than the unit price.

  7. Close the browser window.


Importing a Log File

You can import log files that contain data about user and server activity for your site into the Data Warehouse, and you can run reports on the imported data. Before importing log files, you must choose the site from which you want to import the log files. You must also specify which log files you want to import.

After the event data in the Web logs is processed into the Data Warehouse, you can run a Data Transformation Service (DTS) task to load the descriptive data about the campaign items, such as the name of the discount, and then create a report.

In this lab, you will import a log file into the Data Warehouse and run the post-import process, which you will later use to import a Data Transformation Service (DTS) task. Importing a site log requires using Microsoft SQL Server Enterprise Manager.

Note

  • The system administrator would typically perform the procedures in this lab.

To synchronize the Data Warehouse with your application

  1. Click Start, point to Programs, point to Microsoft SQL Server, and then click Enterprise Manager.

  2. In the left pane, expand Microsoft SQL Servers>SQL Server Group>(ServerName)>Data Transformation Services, and select Local Packages.

  3. On the Action menu, click New Package.

    The DTS <New Package> window appears.

  4. On the Task menu, click Configuration synchronization (Commerce Server).

To import the Web Log Files

  1. On the Task menu, click Web server log import (Commerce Server).

  2. In the Import Web Server Logs dialog box, in the Site name box, select Retail from the drop-down list. Under Application select the retail, retailBizDesk application.

  3. In the Log file path box, type <drive:>\Winnt\System32\LogFiles\W3svc1, and then click OK.

To import the profile user data

  1. On the Task menu, click User profile data import (Commerce Server).

  2. In the User Import Properties dialog box, in the Site name box, select Retail from the drop-down list, and then click OK.

To populate the OLAP cubes with the import data

  1. On the Task menu, click Report Preparation (Commerce Server).

  2. In the Prepare Reports Properties dialog box, in the Site name box, verify Retail is selected, and then click OK.

To execute the four DTS tasks

  1. Select the Configuration Synchronization icon that appears in the DTS <New Package> window, hold down the [SHIFT] key, and then click the Report Preparation icon.

    All four Commerce Server DTS Task icons are selected.

  2. On the Workflow menu, click On Completion.

  3. On the Package menu, click Execute.

    You will see a progress dialog box indicating that the tasks are running.

  4. When the tasks have executed successfully, the Package Execution Results dialog box appears. Click OK.

  5. Close SQL Server Enterprise Manager without saving the package.

The data is imported into the Data Warehouse.


Running a Dynamic Report

Commerce Server 2000 provides you with approximately 50 default reports that you can use as soon as you connect to a data source. You can run both dynamic and static reports from the Reports module or you can schedule reports to be run automatically on a regular basis. Dynamic reports run in a matter of seconds and immediately appear in a separate window in the form of a pivot table.

In this lab, you will set up your Internet options to enable access to data sources across domains, and then you will run a dynamic report displaying an executive summary of daily site usage.

To access data sources across domains

  1. In Internet Explorer, click Tools, and then click Internet Options.

  2. On the Security tab, do the following:
    Use this | To do this
    Custom Level | Click to display the Security Settings options.
    Miscellaneous>Access data sources across domains | Select Enable.
    Navigate sub-frames across different domains | Select Enable.

  3. In the Internet Options dialog box, click OK.

  4. In the Confirmation dialog box, click Yes, and then in the Internet Options dialog box, click OK again.

  5. Close the browser window.

To run the daily usage summary report

  1. In Analysis, click Reports.

  2. In the Reports screen, click Find on the toolbar.

  3. In the Find screen, do the following:
    Use this | To do this
    Find by | Select Name from the drop-down list.
    Name | Type Usage Summary.

  4. Click Find Now.

  5. In the Find screen, select the Usage Summary by Day of Week report, and then click Run report on the toolbar to run the report.

The report appears in a new window as a pivot table.

To save the report

  1. In the pivot table window, click Save Report.

  2. In the Report Name box, type Daily Usage Summary, and then click OK.

  3. Close the browser window.


Running a Static Report

You run static reports from the Reports module. Static reports can take a few moments to run. While a static report is running, however, the Reports module is available to you for running other reports. You can check the status of your running report in the Completed Reports module, where you also view the report once it is completed.

In this lab, you will run a static report, and then view the report in the Completed Reports module.

To run a static report

  1. In Analysis, click Reports.

  2. In the Reports screen, click Find on the toolbar.

  3. In the Find screen, do the following:
    Use this | To do this
    Find by | Select Name from the drop-down list.
    Name | Type Registered User Properties, and then click Find Now.
    Name list | Select Registered User Properties.

  4. To run the report, click Run report on the toolbar.

  5. In the Run a report dialog box, click OK to accept the defaults.

The report is run and will now appear in the Completed Reports module.

To view the completed report

  1. In Analysis, click Completed Reports.

  2. In the Completed Reports screen, in the Name list box, select Registered User Properties.

  3. To open the report, click Open on the toolbar.

    The Registered User Properties report appears.

  4. Close the browser window.


Exporting a Static Report

You use the List Manager module to create and manage lists of site users. Once a list is exported to List Manager, you can create a mailing list that can be used by Direct Mailer to create and send pieces of mail to selected recipients on the list.

In this lab, you will export the Registered User Properties report to List Manager. However, you will not send any direct mail.

To export a static report to List Manager

  1. In Analysis, click Reports.

  2. In the Reports screen, click Find on the toolbar.

  3. In the Find screen, do the following:
    Use this | To do this
    Find by | Select Name from the drop-down list.
    Name | Type Registered User Properties, and the click Find Now.
    Name list | Select Registered User Properties.

  4. To export the report, click Export on the toolbar.

  5. In the Run a Report dialog box, click OK to accept the defaults.

  6. In the Export report as a list dialog box, do the following:
    Use this | To do this
    List Type | Select Static.
    List Name | Type UserProperties.

  7. Click OK.

In Campaigns, in the List Manager module, the UserProperties list appears in List Manager. You can now use the list to create a direct mail campaign.


Creating a Direct Mail Campaign

Direct mail campaigns are a way to get users to view your ads. A direct mail campaign can be targeted toward specific users by using mailing lists that reside in List Manager. You can use these lists to run direct mail jobs in order to target ads to your users more successfully.

In this lab, you will create a direct mail campaign using the UserProperties list that you exported to List Manager from the static report in the previous lab.

To create a Direct Mail campaign

  1. In Campaigns, click Campaign Manager.

  2. In the Campaign Manager screen, double-click Lucerne Publishing, and then select the Bill's Books campaign.

  3. Click [image] on the toolbar, and then select New Direct Mail Campaign from the drop-down list.

  4. In the Direct Mail Properties screen, in the Direct Mail Item section, do the following:
    Use this | To do this
    Direct mail name | Type TargetedMail.
    From address | Type WebMaster@BooksGalore.
    Message subject | Type Great news for our customers.
    Message Body | Type http://www.Microsoft.com.
    Mailing list | Select UserProperties from the drop-down list.
    Personalization | Clear the Yes check box.
    Mail Format | Select MHTML from the drop-down list.

  5. In the Mail Schedule section, do the following:
    Use this | To do this
    Start Date | Type today's date.
    Start Time Select the next full hour after the current hour.

    For example, if it is 11:45am, select 1200.
    Mailing Interval | Verify that One time only is displayed.

  6. In the Text section, in the Test list box, select UserProperties from the drop-down list.

  7. Click Send Test Mail.

  8. In the Message box, click OK.

  9. To save the direct mail campaign and return to the Campaign Manager screen, click [image] on the toolbar.

The direct mail campaign is added to the Campaign Manager.

Site Verification Steps

To verify the test mail was sent

  • Navigate to the DML_drop directory on your local computer. In Windows Explorer, go to <drive letter:>\Program Files\Microsoft Commerce Server\DML_drop.

The .eml file containing the direct mail message is displayed.

To view the test mail

  1. Double-click the .eml file.

  2. Verify the following:
    This | Contains this
    From: WebMaster@BooksGalore.com
    To: <your e-mail address>
    Subject: Great news for our customers
    Message body | Home page for Microsoft.com

Note

  • To verify that the scheduled mail was sent, repeat steps 1 through 3 at the starting time you specified.


Business-to-Business Tutorial

The Business-to-Business (Supplier) Business Desk tutorial provides easy to follow instructions for using Commerce Server features to import catalogs, add trading partners to your site, add users, and manage profiles.

The Supplier tutorial contains the following labs for the Supplier Solution Site. For the location of your Supplier Solution Site, ask your system administrator. It is important to run each lab in the order listed below. Each lab is a prerequisite for subsequent labs:

  • Adding a Shipping Method

  • Importing a Catalog

  • Creating a Catalog Set

  • Creating an Organization

  • Creating a User

  • Creating a Site Term

  • Adding a User with a New Profile


Adding a Shipping Method

The Commerce Server Business Desk Orders modules enable you to view order status information, add and modify shipping methods, and set up tax rates for different countries, states, and regions.

In this lab, you will add a shipping rate by subtotal.

To add a shipping rate

  1. Open Commerce Server Business Desk from either the Start menu or the Desktop.

  2. In Orders, click Shipping Methods.

  3. In the Shipping Methods screen, click Add on the toolbar, and then select Charge by Subtotal from the drop-down list.

  4. In the Charge by Subtotal - New screen, in the Shipping Method Properties section, do the following:
    Use this | To do this
    Name | Type Vigor Airlines.
    Description | Type We'll ship anything.
    Enabled | Verify the Shipping method enabled check box is checked.

  5. In the Rates section, click New, and then do the following:
    Use this | To do this
    Price, up to | Type 10.
    Shipping Rate | Type 5.

  6. Click Accept, and then click New to add another shipping rate.

  7. In the Rates section, do the following:
    Use this | To do this
    Price, up to | Type 20.
    Shipping Rate | Type 10.

  8. Click Accept.

  9. In the Rates section, do the following:
    Use this | To do this
    Price, up to | Double-click over 20.
    Shipping Rate | Type 15.

  10. Click Accept to add the Over 20 shipping rate.

  11. To save the shipping rates and return to the Shipping Methods screen, click Save and go back on the toolbar.

The shipping rates are saved and will be applied to purchases on the Web site.


Importing a Catalog

You use the Catalog Editor module to work with categories and catalogs. You can create, modify, and delete categories and catalogs. You can also use the Catalog Editor to import catalogs. You can import a catalog from an Extensible Markup Language (XML) file or a comma-separated value (CSV) file.

In this lab, you will import an XML catalog file.

To copy the XML catalog file to the Catalogs folder

  1. Copy the Hardwarefull.xml file in the \Tutorial folder at the root of the CDROM to the <drive:>\Inetpub\wwwroot\SupplierADBizDesk\Catalogs folder.

To import an XML catalog file

  1. In Catalogs, click Catalog Editor.

  2. In the Catalog Editor screen, click Import on the toolbar, and then select Import XML from the drop-down list.

  3. In the Import XML Catalog dialog box, do the following:
    Use this | To do this
    Filename | Type <drive:>\Inetpub\wwwroot\SupplierADBizDesk\Catalogs\Hardwarefull.xml.
    Delete any existing catalog data | Verify that this box is not checked.

  4. Click OK.

The Hardware catalog has been imported and is available on the SupplierAD site.

Note

  • The catalog does not yet appear in the Name box in the Catalog Editor.

    Use the Catalog Editor module to refresh and publish a catalog on your Web site. You will have to refresh and publish your catalog whenever you make any changes in order to ensure that the changes are reflected on your Web site.

To refresh and publish the catalog

  1. In Catalogs, click Catalog Editor.

  2. In the Catalog Editor screen, click Publish a catalog on the toolbar.

The catalog is updated and published on the Web site.


Creating a Catalog Set

Catalog sets are a subset of your product catalogs. You can use the Commerce Server Business Desk Catalog Sets module to create catalog sets, and then assign them to a specific user or group of users according to their user profile.

In this lab, you will create a catalog set named WWSpecial.

To create a catalog set

  1. In Catalogs, click Catalog Sets.

  2. In the Catalog Sets screen, click Add on the toolbar, and do the following:
    Use this | To do this
    Name | Type WWSpecial.
    Description | Type World Wide Importers Special Catalog Set.
    Available Catalogs | Select Hardware.

  3. To move the Hardware catalog to the Assigned catalogs box, click Add.

  4. To save the catalog set and return to the Catalog Sets screen, click Save and go back on the toolbar.

The WWSpecial catalog set is saved with the Hardware catalog.


Creating an Organization

You use the Organizations module to create or change organizations. You also use this module to add a trading partner to your site, and to specify information about the partner such as the name of the primary contact, address, phone, purchase order approval process, cost center, and discounts.

In this lab, you will add an organization called World Wide Importers.

To add an organization

  1. In Users, click Organizations.

  2. In the Organizations screen, click Add on the toolbar.

  3. In the New Organization screen, in the General information section, do the following:
    Use this | To do this
    Name | Type World Wide Importers.
    Trading Partner Number | Type 02.
    Organization catalog set | Select WWSpecial from the drop-down list.

  4. To save the new organization with the WWSpecial catalog set and return to the Organizations screen, click Save and go back on the toolbar.

The World Wide Importers organization is saved. The WWSpecial catalog set will appear on the SupplierAD site for the World Wide Importers Company.


Creating a User

You use the Users module to manage registered users — those Web site users who are recognized by your site because they have completed an online registration form, or in some way have established a user account on your site.

In this lab, you will be adding three new users for the World Wide Importers Company: an administrator, a delegated administrator, and a non-administrator user.

To create an administrator

  1. In Users, click Users.

  2. In the Users screen, click Add on the toolbar.

  3. In the New User screen, in the General information section, do the following:
    Use this | To do this
    Logon name | Type JoeUser.
    User password | Type open_sesame.
    E-mail | Type JoeUser@WWImporters.com.
    Last name | Type User.
    First name | Type Joe.

  4. In the Account Info section, do the following:
    Use this | To do this
    Organization ID | Click the ellipse button […] to open the Select Organization dialog box.

  5. In the Select Organization dialog box do the following:
    Use this | To do this
    Name (Find) Type World Wide Importers, and then click Find Now.

    World Wide Importers appears in the Name box.
    Name (List) | Select World Wide Importers.

  6. Click OK.

  7. In the Account Info section, in the Account status box, select Active Account from the drop-down list.

  8. In the Business Desk section, in the Partner service role flags box, select Administrator from the drop-down list.

  9. To save the new user and return to the Users screen, click Save and go back on the toolbar.

The new user is saved in the World Wide Importers organization.

To create a delegated administrator

  1. To open the SupplierAD site, in Internet Explorer type http://<computername>/SupplierAD on the Address line.

  2. On the SupplierAD site Sign-in screen, do the following:
    Use this | To do this
    User name | Type JoeUser.
    Password | Type open_sesame.

  3. Click Submit.

    Partner Service appears in the left pane.

  4. In the left pane, under Partner Service, click Users, and then above the user information, click New.

  5. In the Account Info section, from the Account status drop-down list, select Active.

  6. In the Business Desk section, from the Partner service role flags drop-down list, select Delegated Admin.

  7. In the General information section, do the following:
    Use this | To do this
    Logon name | Type BettyUser.
    Password | Type open_sesame.
    E-mail | Type BettyUser@WWImporters.com.
    Last name | Type User.
    First name | Type Betty.

  8. Click Save, and then click Close.

    Betty User is saved as a delegated administrator.

  9. Close the browser window.

To create a non-administrator user

  1. To open the SupplierAD site, in Internet Explorer type http://<computername>/SupplierAD on the Address line.

  2. On the SupplierAD site Sign-in screen, do the following:
    Use this | To do this
    User name | Type BettyUser.
    Password | Type open_sesame.

  3. Click Submit.

  4. In the left pane under Partner Service, click Users, and then click New.

  5. In the AccountInfo section, select Active from the Account Status drop-down list.

  6. In the Business Desk section, from the Partner service role flags drop-down list, select User.

  7. In the General information section, do the following:
    Use this | To do this
    Logon name | Type BarneyUser.
    Password | Type open_sesame.
    Email | Type BarneyUser@WWImporters.com.
    Last name | Type User.
    First name | Type Barney.

  8. Click Save, and then click Close.

    Barney User is saved as a non-administrator user.

  9. Close the browser window.

Site Verification Steps

To verify that BarneyUser is NOT a delegated administrator

  1. To open the SupplierAD site, in Internet Explorer type http://<computername>/SupplierAD on the Address line.

  2. On the SupplierAD site Sign-in screen, do the following:
    Use this | To do this
    User name | Type BarneyUser.
    Password | Type open_sesame.

  3. Click Submit.

    No Partner Services are listed.

  4. Click the Keyboards category.

    Note

    • Because there is only one catalog available, the site displays the catalog categories rather than the name of the catalog.
  5. Click Microsoft® Internet Keyboard Pro, scroll down, and then click Add to Basket.

  6. In the Quantity box, type 5, and then click Update.

    The total price includes a quantity of five keyboards on the basket page.

  7. Close the browser window.

To verify that the basket exists in Business Desk

  1. In Orders, click Basket Manager.

  2. In the Basket Manager screen, in the Find screen, from the Find By drop-down list, select All Baskets.

  3. Click Find Now.

The order by Barney User appears on the Find screen.


Creating a Site Term

You use the Site Terms module to define values that are pertinent to your site. Site terms provide an easy way for you to standardize the values that are used throughout your site. You can use site terms to target products in your catalogs, content, and advertisements to site users.

In this lab, you will add the site terms, Line and Staff. Once you have created your site terms, you will set up a user profile to include the site term so you can later target an advertisement to those site users that match the user profile.

To create a site term

  1. In Users, click Site Terms Editor.

  2. In the Site Terms screen, click Add.

  3. In the Add dialog box, click Add a new group, and then click OK.

  4. In the Attributes section, do the following:
    Use this | To do this
    Name | Type CompanyInfo.
    Display name | Type Company Information.

  5. Click Apply.

  6. In the Site term structure box, select Company Information, and then click Add.

  7. In the Add dialog box, select Add a new site-term, and then click OK.

  8. In the Site Term Attributes section, do the following:
    Use this | To do this
    Name | Type JobRole.
    Display name | Type Job Role.

  9. In the Terms section, click New, and then do the following:
    Use this | To do this
    Term name | Type Line.
    Display name | Type Line.

  10. Click Accept, and then click New to add a new site term.

  11. In the Terms section, do the following:
    Use this | To do this
    Term name | Type Staff.
    Display name | Type Staff.

  12. Click Accept, and then click Apply.

  13. To save the new site terms and return to the Site Terms screen, click Save and go back on the toolbar.

The new site terms are saved and can now be added to a user profile.

To add a site term to a user profile

  1. In Users, click Profile Designer.

  2. In the Profiles screen, in the Name list, select the User Object profile, and then click Open on the toolbar.

  3. In the Profile: User Object screen, from the Properties list, select General information.

  4. Click Add.

  5. In the Add dialog box, click Add a new group.

  6. Click OK.

  7. In the Profile: User Object screen, in the Attributes section, do the following:
    Use this | To do this
    Name | Type CompanyInfo.
    Display name | Type Job Role.

  8. Click Apply, and then click Add.

  9. In the Add dialog box, click Add a new property, and then click OK.

  10. In the Profile: User Object screen, in the Attributes section, do the following:
    Use this | To do this
    Name | Type JobRole.
    Display name | Type Job Role.
    Type | Select Site Term from the drop-down list.
    Type reference | Click the ellipse button […], select Company Information, and then select Job Role.

  11. Click OK.

  12. In the Advanced Attributes section, do the following:
    Use this | To do this
    Active | Verify that Yes is selected.
    Map to data | Click the ellipse button […] to open the Data Source Picker dialog box.

  13. In the Data Source Picker dialog box, select ProfileService_SQLSource, select UserObject, and then scroll down and select Custom Property 1 (STRING).

  14. Click OK, and then click Apply.

  15. To save the attributes with the user profile and return to the Profiles screen, click Save and go back on the toolbar.

The user profile is saved with the Job role site terms.

To update the user profile

  1. In Users, click Publish Profiles.

  2. In the Publish Profiles screen, select the SupplierAD application, and then click Publish on the toolbar.

The user profile is updated and you can now target site users that match the user profile.


Adding a User with a New Profile

You use the Users module to manage registered users — those Web site users who are recognized by your site because they have completed an online registration form, or in some way have established a user account on your site.

In this lab, you will be adding two new users with the new site terms, Line and Staff that you created in the previous lab.

To create the Line user

  1. In Users, click Users.

  2. In the Users screen, click Add on the toolbar.

  3. In the New User screen, in the General Information section, do the following:
    Use this | To do this
    Logon name | Type JackUser.
    User password | Type open_sesame.
    Email | Type JackUser@WWImporters.com.
    Last name | Type User.
    First name | Type Jack.
    Job role | Click Job role, and then select Line from the drop-down list.

  4. In the Account Info section, do the following:
    Use this | To do this
    Organization ID | Click the ellipse button […] to open the Select Organization dialog box. Select World Wide Importers, and then click OK.
    Account status | Select Active Account from the drop-down list.

  5. In the Business Desk section, in the Partner service role flags box, select Normal User from the drop-down list.

  6. To save the user and return to the Users screen, click Save and go back on the toolbar.

Jack User has been created as the Line user for the World Wide Importers organization.

To create the Staff user

  1. In Users, click Users.

  2. In the Users screen, click Add on the toolbar.

  3. In the New User screen, in the General Information section, do the following:
    Use this | To do this
    Logon name | Type JillUser.
    User password | Type open_sesame.
    E-mail | Type JillUser@WWImporters.com.
    Last name | Type User.
    First name | Type Jill.
    Job Role | Click Job Role, and then select Staff from the drop-down list.

  4. In the Account Info section, do the following:
    Use this | To do this
    Organization ID | Click the ellipse button […] to open the Select Organization dialog box. Select World Wide Importers, and then click OK.
    Account Status | Select Active Account from the drop-down list.

  5. In the Business Desk section, in the Partner service role flags box, select Normal User from the drop-down list.

  6. To save the user and return to the Users screen, click Save and go back on the toolbar.

Jill User has been created as the Staff user for the World Wide Importers organization.


Business Desk Analysis

You use the Analysis modules to analyze data about user activity on your site. You can analyze specific information about registered users, and also analyze user behavior during visits to your site, including how much time they spent on a particular page, or which links they clicked.

You can run reports to review the data and to view population segments. The information provided in these reports and segments can help you make informed decisions about pricing, marketing, advertising, and other aspects of your business.

Before you run analysis reports or view segments to analyze user activity on your Web site, your system administrator must install Microsoft Commerce Server 2000. Additionally, the system administrator must import Web log, transaction, campaign, user, and catalog data into the Data Warehouse, and run the Report Preparation process.

This section contains:

  • Workflow for Reports Management. Illustrates the workflow for running, changing, and managing reports.

  • Workflow for Segment Analysis. Illustrates the workflow for viewing and managing segments and Segment models in the Segment Viewer module.

  • About Analysis. Describes the components of a report, and provides an overview of the different types of reports. Describes the Segment Viewer module and how you can use it to analyze activity on your site.

  • Commerce Server Reports. Describes the reports provided with Commerce Server, the report properties, and how Commerce Server reports handle time.

  • Setting Up Business Analytics. Explains the steps required to run Commerce Server analytical functions.

  • Finding Reports. Explains how to find a report in the Reports list.

  • Running Reports. Explains how to run dynamic and static reports.

  • Viewing Dynamic Reports. Explains how to view completed dynamic reports.

  • Viewing Static Reports. Explains how to open and view static reports in the Completed Reports module.

  • Printing Reports. Explains how to print dynamic and static reports from the browser window.

  • Exporting a Dynamic Report. Explains how to export a dynamic report to Microsoft Excel.

  • Exporting a Static Report. Explains how to export a static report as a list to the List Manager module.

  • Creating a New Dynamic Report. Explains how to modify a dynamic report and save the modified report as a new dynamic report.

  • Deleting Reports. Explains how to delete custom dynamic report definitions and completed static reports.

  • Viewing Report Properties. Explains how to view report properties.

  • Analyzing Population Segments. Explains how to open a Segment model, view a segment or a segment group, compare two segments or segment groups, and export segment data to a list.


Workflow for Reports Management

The following figure illustrates a sample scenario for running, changing, and managing reports.

Workflow diagram for Reports Management
Reports
Run Report
View Dynamic Reports
Modify Report
Configure Parameters

Save changes to
Create a New Dynamic Report Definition

View Static Report
Completed Reports
Browser window
Run New Dynamic Report
Reports
Dynamic
Static

Sample Scenario for Running Dynamic Reports

  1. In the Reports module, run a dynamic report.

  2. In the browser window, view the dynamic report.

  3. In the browser window, modify the dynamic report.

  4. In the browser window, save the modified dynamic report as a new report definition.

  5. In the Reports module, run the new dynamic report.

Sample Scenario for Running Static Reports

  1. In the Reports module, run a static report.

  2. Configure the parameters of the report.

  3. In the Completed Reports module, open the static report and view it in a browser window.

  4. In the Reports module, export a static report as a list.

  5. Configure the parameters of the report.

  6. Configure the list.

  7. In the List Manager module, open the new list.
    Export static report as list workflow
    Reports
    Exporting a Static Report
    Configure parameters
    Configure list
    View new list
    List manager

Sample Scenario for Exporting Static Reports

  1. In the Reports module, export a static report as a list.

  2. Configure the parameters of the report.

  3. Configure the list.

  4. The new list is available in the List Manager module.


Workflow for Segment Analysis

The following figure illustrates a sample scenario for viewing and managing segments and Segment models in the Segment Viewer.

Segment Viewer workflow
Segment Viewer
Select Segment model
Analyze and compare segments
Rename segment and save
Create Summary Comparison Report
Export segment to List Manager

  1. In the Segment Viewer module, select a Segment model to view and analyze.

  2. Analyze the selected segment or segment group to determine its defining characteristics and the characteristics that contrast the selected segment or group with other segments or groups in the model. Analyze these characteristics by viewing the summary information for each and then comparing it with the information for other segments or segment groups.

  3. If necessary, rename the segment or segment group to reflect its summary and comparison characteristics.

  4. Create a summary report in Internet Explorer for the compared segments, and then print the report.

  5. Export a segment to the List Manager module to create a list of the users in the segment for further analysis and management.

See Also

About Analysis


About Analysis

You use Analysis to run reports on the user and site data stored in your Data Warehouse, and you use the results of those reports to perform business analytics on the performance of your Web site. For example, you can run reports that show you the characteristics and past behavior of your users, and then update your site to target advertisements or products to those users.

In addition to running analysis reports, you can use the Segment Viewer module to analyze segments of your user population. Segments represent groups of users with similar characteristics or behavior. You use the Segment Viewer module to analyze segments to identify these specific characteristics or behavior, such as usage trends. You can then use the results of your analysis to make marketing decisions based upon similarities among users.

Your system administrator must perform several tasks so you can run reports and analyze segments. For more information, see Setting Up Business Analytics.

This section contains:

  • Report Definitions

  • Dimensions and Measures

  • Dynamic and Static Reports

  • Custom Reports

  • Segment Analysis


Report Definitions

A report definition is the structure for a report, not the completed report. If you run a report a second time after new data is imported into the Data Warehouse, the second version of the report contains updated data. You run reports to see a "snapshot" of the data in the Data Warehouse

The Reports module contains two types of report definitions: one definition type for dynamic reports, and another definition type for static reports. For information about dynamic and static reports, see Dynamic and Static Reports.

The reports in the Reports module are divided into the following categories: advertising, product sales, Web usage, users, visits, diagnostics, and query strings. For information about the report definitions available in the Reports module, see Commerce Server Reports.

You can create custom dynamic report definitions. Your system administrator can create both custom dynamic and static report definitions. Both dynamic and static reports return specified views of the summarized data in the Data Warehouse after you run them. For information about custom reports, see Custom Reports.


Dimensions and Measures

The data returned in a report is determined by the dimensions and measures that the report definition contains. Measures are numeric values. Dimensions are business entities, such as color, size, product, or time. By combining dimensions and measures, Commerce Server report definitions provide quantitative and time-based information.

When you run a static report, you can change the parameters of the data returned. For example, you can request data for only the 25 users who made purchases, but you cannot change the dimensions and measures in the report.

When you run a dynamic report, a list of available dimensions and measures appears in the field chooser of the pivot control. You can change the dimensions and measures in a dynamic report by adding, removing, and changing the orientation of dimensions and measures, and by changing the level of detail that the completed report shows. If you change a completed dynamic report, you can save the report definition with the changes as a custom dynamic report definition.

See Also

Dynamic and Static Reports

Custom Reports

Commerce Server Reports


Dynamic and Static Reports

Commerce Server provides two types of reports:

  • Dynamic reports. Are created at runtime. Each time a dynamic report is run, it gathers the most recent data in the Data Warehouse. Only the report definition, which remains the same over time, is stored.

  • Static reports. Are run immediately upon request, and then stored with the data in the Completed Reports module. Static SQL reports are run asynchronously, allowing you to continue using Commerce Server Business Desk to perform other tasks while static reports are running. Static multidimensional expression (MDX) reports are run synchronously, therefore, you will not be able to perform other tasks using Business Desk until the reports are complete.

Note

  • You can check whether a static report is based on MDX or SQL by looking at the properties of the report. For information about viewing report properties, see Viewing Report Properties.

Features of Dynamic and Static Reports

Dynamic Reports

PivotTables

PivotTable Field List

Collapsed Dimensions

PivotCharts

Static Reports

Features of Dynamic and Static Reports

The following table lists the differences between static and dynamic reports.

Feature | Dynamic report | Static report
Control size of report results | You control the size of report results by not displaying detailed data. | You control the size of report results by limiting the number of rows to report on.
Change the contents of the report | You use the PivotTable features to add and remove dimensions and measures from the report results. | The system administrator modifies static reports programmatically. For instructions for modifying static reports, see "Creating Custom Reports" in Commerce Server 2000 Help.
Export report results directly to List Manager | You cannot export the results of a dynamic report to List Manager. | You can export a static report as either a dynamic or static list to List Manager.
Export report results to Microsoft Excel | You can export the results of a dynamic report to Microsoft Excel. | You cannot export a static report to Microsoft Excel.
Create new report definitions | You can make changes to a dynamic report and save the changes as a new dynamic report definition. | The system administrator can modify static reports programmatically. For instructions for modifying static reports, see "Creating Custom Reports" in Commerce Server 2000 Help.
Delete report definitions | You can delete custom dynamic report definitions. You cannot delete default dynamic report definitions. | You can delete custom static report definitions. You cannot delete default static report definitions.
Save completed reports | You cannot save completed dynamic reports with data in Business Desk. | Completed static reports are stored with their data in Completed Reports until you delete them.
View report results as a chart | You can view completed dynamic reports as PivotCharts. | You cannot view completed static reports as charts.

Dynamic Reports

When a dynamic report is completed it appears, by default, as a PivotTable report or a PivotChart report in a new Internet Explorer browser window. You can hide and reveal the PivotTable and PivotChart in every dynamic report. PivotTables include filters, rows, and columns that contain your report details. PivotCharts are graphical representations of the data in the report. Within the PivotTable, you can look at details of your data and move dimensions and measures to get a different perspective on your data.

Note

  • To access Microsoft PivotTable List Help, you must have Microsoft Office installed on the same computer on which you are running Business Desk.

PivotTables

You can make changes to a dynamic report PivotTable. You can add or remove dimensions as rows or columns, and add or remove measures. You can expand or contract the level of detail shown, and you can add or change filter dimensions. After you make changes, you can save the changed report as a new dynamic report definition, available in the Reports module. For more information about creating a new dynamic report definition, see Creating a New Dynamic Report.

The following figure uses the Ad Reach and Frequency per Campaign Item report to show the screen elements of a PivotTable.

Click the illustration to enlarge or reduce.

PivotTable Field List

You use the PivotTable Field List to add dimensions and measures to a PivotTable. The PivotTable Field List appears when the report appears in the browser window. If the Field List does not appear automatically, click the PivotTable Field List button. The Field List shows the dimensions and measures that can be included in a report. Dimensions and measures shown in bold type are included in the default view of a report; those not shown in bold are available for use in the report. You can use the drag-and-drop feature to add dimensions and measures to a report.

The following figure shows the screen elements of a PivotTable Field List.

Pivot Table Field List

Click the illustration to enlarge or reduce.

Collapsed Dimensions

You expand and collapse dimensions to change the level of information shown in detail in a report. Collapsed dimensions appear in the PivotTable with a plus sign (+) to the left of the dimension name. When a dimension is collapsed, the total shown in the report is a rolled-up total for the dimension as a whole. You can click the plus sign next to a dimension name to reveal the individual dimension members. Collapsed dimensions are sorted at the level at which they are collapsed.

If you collapse the dimensions of a dynamic report that contains measures that have unique counts, the totals shown in the report will not be accurate. For example, the Ad Reach and Frequency per Day report shows the total reach (number of unique users) and frequency (number of unique visits) for each ad campaign by day. If you collapse an ad campaign, the total of the number of unique users by day will not be an accurate total for the ad campaign because a user may have visited the Web site on multiple days. Other Commerce Server reports that contain unique counts include Ad Reach and Frequency per Campaign, Ad Reach and Frequency per Campaign Item, Distinct Users and Visits by Week, and Distinct Users by Day.

PivotCharts

You can view dynamic report PivotCharts. The Show Chart button displays your dynamic report as one of the 15 types of charts available in Commerce Server. Each Commerce Server dynamic report is assigned a default chart format that best represents the data in that report. You can choose different chart formats to meet your needs.

The following figure shows the screen elements of a PivotChart in the Ad Placement report.

Pivot Chart Example

Click the illustration to enlarge or reduce.

Note

  • Only the first measure is shown in PivotCharts. If you want to see a chart showing a different measure, you will need to move that measure to the first position (far left) in the PivotTable the chart is based on.

The following table lists each chart format with a description of the type of data the chart displays. For information about viewing your dynamic report as a PivotChart, see Viewing Dynamic Reports.

Chart format | Data displayed
Bar: Clustered | Shows comparisons between items.
Column: Clustered | Shows data changes over a period of time or compares items.
Line | Shows trends in data.
Line: with Markers | Shows trends in data at equal intervals, with markers to designate the intervals.
Line: Smooth | Shows trends in data at equal intervals, smoothed to show the estimated data between intervals.
Line: Smooth, with Markers | Shows trends in data at equal intervals, with markers to designate the intervals, smoothed to show the estimated data between intervals.
Pie | Shows the proportional size of items that make up a single data series to the sum of the items.
Pie: Exploded | Shows the proportional size of items that make up a single data series to the sum of the items, with emphasis on a specific item.
Area | Shows the magnitude of change over time, and the relationship of parts of data to the whole.
Doughnut | Shows the relationship between items and the data series they make up, showing different data series in each ring of the chart.
Doughnut: Exploded | Shows the relationship between items and the data series they make up, showing different data series in each ring of the chart, with emphasis on a specific item.
Radar: with Lines | Shows a comparison of aggregate values of several data series, displayed as points radiating out from a center point.
Radar: with Lines and Markers | Shows a comparison of aggregate values of several data series, displayed as connected points radiating out from the center point, with markers identifying the values.
Radar: with Smooth Lines | Shows a comparison of aggregate values of several data series, displayed as connected points radiating out from the center point, smoothed to show the estimated data between intervals.
Radar: with Smooth Lines and Markers | Shows a comparison of aggregate values of several data series, displayed as connected points radiating out from the center point, with markers identifying the values, smoothed to show the estimated data between intervals.

Static Reports

Completed static reports are stored in the Completed Reports module. Static reports are able to report on very large result sets, although static reports that are run on very large data sets can take a significant amount of time to run. While the report is running, the status of the report is shown as "Pending" in the Completed Reports module. When you open a completed static report, it opens as an HTML document in a new Microsoft Internet Explorer browser window.

The following figure shows the screen elements of a static report.

Click the illustration to enlarge or reduce.

You can export static report results as static or dynamic lists to the List Manager module in Campaigns. The static list in List Manager contains the same data that was in the static report when you ran it; however a static report is limited to 1,000 rows in the resulting HTML report. You can export an unlimited number of rows as a list.

A dynamic list contains a pointer to the static report. For example, if you export the New Registered Users report, you use the Run a report dialog box to configure the parameters of the report. If you select "last month" for the date of the report, the data exported as a list will be for the previous month.

If you exported the report as a dynamic list, the report definition and parameters are stored. Each time the dynamic list is run, it shows data for the month preceding the current month, for example, data for June is returned if you run the list in July. A dynamic list retrieves the latest data from the Data Warehouse when you run the list in List Manager. However, if you exported the report as a static list, as opposed to a dynamic list, in June and selected "last month," the data in the list will always be for May, regardless of when you open the list.

Export a static report to List Manager

Static List:
Static Report Definition gathers data from the Data Warehouse

Commerce Server Data Warehouse

Export
Static Report

Data gathered from Data Warehouse when list is opened

Dynamic List

Dynamic list definition added to List Manager

Static list added to List Manager

List Manager

You use the static report properties in the Running a Report dialog box to customize the results of a static report. You can change or enter new values for any parameter the report is based on. For example, you can limit the Registered User Properties report to showing the properties for only the twenty-five most recently registered users. If you run a report that has a date parameter, you can select an absolute date, a date range, or a relative date, such as last year. If you run a report that has an expression parameter, you can select from a full set of operands to create the expression you want.

After you run a static report, you cannot modify the report results in the browser window. However, you can use the functions of Internet Explorer to print the report or to save it as a file, just as you would with any HTML file. For information about the features of Internet Explorer, see Internet Explorer Help.

See Also

Commerce Server Reports

Running Reports

Exporting a Dynamic Report

Creating a New Dynamic Report

Viewing Dynamic Reports

Exporting a Static Report

Viewing Static Reports


Custom Reports

You can modify a dynamic report definition and save it as a custom report definition, which is added to the Reports module. You use custom dynamic report definitions to create a new view of the data in a dynamic report. For example, you can run the Usage Trend report to see the total requests, users, and visits per year for your site.

If you want to see more details about usage trends, you can create a new dynamic report definition from the Usage Trend report to show you usage trends by the type of user who is visiting your site, or to show you usage trends over different time periods (per day, per month, or per quarter) instead of per year. When you save the Usage Trend report with your changes, the new report definition is added to the Reports module. Refresh the Reports list in the Reports module to show the new dynamic report definition. For more information about creating a new dynamic report definition, see Creating a New Dynamic Report.

You create a custom dynamic report definition by changing the PivotTable of an existing report, and saving the result as a new report definition. You can change the PivotTable of an existing report by adding and removing filters, sorting the displayed data, adding measures, moving fields, changing the data that is detailed and summarized, and by pivoting (or manipulating) the columns and rows. For example, you can expand the year dimensions of the Usage Trends report and see usage trends by day. You can expand the year dimensions, remove the year, quarter, and day dimensions and see usage data by month only.

For more information about working with PivotTables, Your system administrator can create custom static and dynamic report definitions and add them directly to the database used by reports. For information for site developers creating custom reports, see Creating Custom Reports. For information about planning for creating custom reports, see Planning for the Business Analytics System.

See Also

Commerce Server Reports

Running Reports

Creating a New Dynamic Report


Segment Analysis

You use the Segment Viewer module to perform segmentation (or clustering) analysis. In segmentation analysis, users are grouped into segments according to their behavior on the site and properties such as age and gender. Users in the same segment have similar behavior or properties. Records grouped together in a segment tend to be more similar to each other than to records in other segments. The result of the segmentation process is a Segment model. The Segment model describes the shared characteristics of the users belonging to a segment or a group of segments. Segments and segment groups are created in Commerce Server Manager from data in your Data Warehouse.

You use the Segment Viewer module to examine a single segment or to compare one segment to another. You also use the Segment Viewer module to create a summary report of all your segments.

Segments and Segment Groups

Segment Models

Segment Viewer

Segment Reports

Segments and Segment Groups

Segments are clusters of users that exhibit similar behavior on the site or have similar properties such as age and gender. A segment consists of a summary of the database records that belong to it. The summary is derived from properties in the Data Warehouse used to cluster the database records. Segment groups are collections of similar segments or other segment groups. Similar segments and segment groups are then merged to form higher-level segment groups. This process continues until a single, high-level segment group is formed representing the entire population.

The Segment Viewer presents the segments in hierarchical order, with the top-level segment group summarizing the entire population and the lower-level segment groups and segments summarizing smaller and smaller subsets of the population. You use the information gathered in the Segment Viewer as the basis for personalization and targeting through other Commerce Server Business Desk modules.

The segment groups form a hierarchy from which you can analyze trends and discover correlations within the data at different levels of the Segment hierarchy. By grouping users according to their similarities, new correlations may become apparent to you. These newly recognized correlations can form the basis for targeting and personalization rules.

Segment Models

A Segment model describes the characteristics of the users belonging to each of the segments and segment groups. You use Segment models to discover and analyze the attribute values that characterize the users visiting your site. For example, after building a Segment model, you may discover a segment characterizing users who purchased a popular fantasy book for children: female, over 40, income above $55,000 per year, and an education level of college graduate or greater. After you have discovered these common characteristics, you can then offer similar products to users matching those criteria. For example, these users may also be likely to buy an animal book for children.

At your request, your system administrator can build Segment models using data derived from the Commerce Server Data Warehouse. Your system administrator should notify you after the new Segment model is complete, so you can view updated Segment model information in the Segment Viewer module in Commerce Server Business Desk.

Segment Viewer

You view segment groups and single segments using the Segment Viewer, a data analysis tool designed for the business manager. Using the Segment Viewer module, you can identify usage trends and make marketing decisions based upon similarities among users.

You use the Segment Viewer module to view relevant information about various segments and to compare and contrast their properties. You can save members of single segments to a list in the List Manager module if you want to perform further analysis and classification on the segments.

When you first open the Segment Viewer module, a list of available Segment models appears. After you select a Segment model and click the Open Model button on the toolbar, the Segment Viewer screen appears. Three work areas appear on this screen:

  • A hierarchical view of the segments and segment groups in the Segment model you opened.

  • A summary of the relevant properties for the selected segment or segment group.

  • A comparison of the selected segment to another segment or segment group.

The first time you view a Segment model using the Segment Viewer, the segments and segment groups in the segment list have generic names, such as Segment1, Segment2, and so on. The percentage of the total population represented in a segment or segment group appears in parentheses after the name. The segment summary appears in the screen to the right of the segment list.

Segment Viewer work area

Click the illustration to enlarge or reduce.

The summary of your segment or segment group contains a table with the following columns:

  • Property/value pairs. Correspond to each other and best summarize the records in the selected segment or segment group. For example, if the majority of records in a given segment correspond to people whose occupation is "Student," then "Occupation" appears in the Property column and "Student" appears in the Value column.

  • Score. Displays a red bar, the length of which indicates how well the matching property/value pair summarizes the records in the selected segment or segment group.

Segment Reports

You can use the Segment Viewer to generate a report that is a summary of all the segment groups and segments you have created. You use this report to compare all segments. Each segment and segment group has links to its detailed information; clicking on these links allows you to move easily between segments. The report appears in a separate browser window.

See Also

Commerce Server Reports

Viewing a Segment Model

Viewing a Segment Report

Exporting Segment Data to List Manager


Commerce Server Reports

Commerce Server provides you with a set of 39 report definitions. You can change dynamic reports to create new reports and add your newly created dynamic reports to the Reports module. For more information about creating a new dynamic report definition, see Creating a New Dynamic Report. In addition, your site developer or system administrator can create custom reports as needed.

Note

  • Your system administrator must perform several tasks before you can run reports. For more information, see Setting Up Business Analytics.

This section contains:

  • Advertising Reports

  • Product Sales Reports

  • Web Usage Reports

  • User Reports

  • Visit Reports

  • Diagnostic Reports

  • Query String Reports

  • Report Properties

  • Time Handling in Reports


Advertising Reports

You use the Reports module to run reports to analyze advertising data.

Ad Placement

Ad Reach and Frequency per Day

Ad Reach and Frequency per Campaign Item

Ad Reach and Frequency per Campaign

Campaign Item Summary

Campaign Event Summary

Ad Placement (Dynamic)

Use the Ad Placement report to review how effectively ads have been placed on your site. This report displays a summary of campaign activity by location on your site. This report collects data only for closed visits.

The following table lists the measures and dimensions that this report contains.

Measures | Dimensions
Count Events | Campaign Events Page Group Site

Return to Advertising Reports

Ad Reach and Frequency per Day (Dynamic)

Use the Ad Reach and Frequency per Day report to review the behavior of users in relation to campaign items on your site. This report displays the activity of unique users per day for each campaign item. This report provides data only for closed visits.

The following table lists the measures and dimensions that this report contains.

Measures | Dimensions
Events Frequency Reach | Campaign Date Distinct Users Event Site

Return to Advertising Reports

Ad Reach and Frequency per Campaign Item (Dynamic)

Use the Ad Reach and Frequency per Campaign Item report to review the behavior of users in relation to campaign items over time. This report displays the activity of unique users per day for each campaign item over time. This report provides data only for closed visits.

The following table lists the measures and dimensions that this report contains.

Measures | Dimensions
Events Frequency Reach | Campaign CampaignItem Date DistinctUsers Event Site

Return to Advertising Reports

Ad Reach and Frequency per Campaign (Dynamic)

Use the Ad Reach and Frequency per Campaign report to review the behavior of users in relation to campaigns. This report displays the activity of unique users per day for each campaign over time. This report provides data only for closed visits.

The following table lists the measures and dimensions that this report contains.

Measures | Dimensions
Events Frequency Reach | Campaign DistinctUsers Event Site

Return to Advertising Reports

Campaign Item Summary (Dynamic)

Use the Campaign Item Summary report to review the effectiveness of campaigns on your site. This report displays a summary of activity by campaign item on your site. This report provides data only for closed visits.

This report displays a summary of campaign activity on your site. The following table lists the measures and dimensions that this report contains.

Measures | Dimensions
% Click Thru Ad Requests Remaining Clicks ReachRequests Yield | Advertiser Campaign Campaign Item Reach Site

Return to Advertising Reports

Campaign Event Summary (Dynamic)

Use the Campaign Event Summary report to review the effectiveness of campaigns on your site. This report displays a summary of campaign event activity on your site. This report collects data only for closed visits.

The following table lists the measures and dimensions that this report contains.

Measures | Dimensions
Count Events | Advertiser Event Site

Return to Advertising Reports

See Also

About Analysis

Commerce Server Reports

Setting Up Business Analytics

Finding Reports

Running Reports

Viewing Dynamic Reports

Viewing Static Reports

Printing Reports


Product Sales Reports

You use the Reports module to run reports to analyze product sales data.

Buyer Browse to Purchase

Customer Sales

Customer Spend Summary

Order Events

Product Sales

Shopping Basket Events

Buyer Browse to Purchase (Dynamic)

Use the Buyer Browse to Purchase report to review user visit and purchasing patterns. This report displays the number of first time and repeat buyers, and the average number of visits for each purchase per buyer.

The following table lists the measures and dimensions that this report contains.

Measures | Dimensions
Count Sales Visit Count Visitor Count Visits Per Buy | Buyer Type Site

Return to Product Sales Reports

Customer Sales (Static)

Use the Customer Sales report to see customer details, total sales, and total orders. This report can be exported to the List Manager, and the information it provides can be used to target customers with online campaigns, such as direct mail promotions.

The following table lists the measures and dimensions that this report contains.

Measures | Dimensions
Orders Sales | E-mail First Name Last Name User ID

Return to Product Sales Reports

Customer Spend Summary (Dynamic)

Use the Customer Spend Summary report to review sales volume and revenue by customer. This report displays sales data by logon name for registered users and by guest user ID for guest users.

The following table lists the measures and dimensions that this report contains.

Measures | Dimensions
Quantity Revenue | Customer Date Products Site

Return to Product Sales Reports

Order Events (Dynamic)

Use the Order Events report to review order submittal events, such as a user clicking the Checkout button to indicate that the order is complete. This report shows the number of submit order events performed by registered and guest users each hour.

Note

  • The Week of Year dimension is used to calculate the date dimensions in this report. For years that begin on a Saturday, the Week of Year dimension returns week 53 for the last week.

The following table lists the measures and dimensions that this report contains.

Measures | Dimensions
Count Events | Date Events Hour of Day Site User Type

Return to Product Sales Reports

Product Sales (Dynamic)

Use the Product Sales report to review product sales volume and revenue by date. This report shows the total quantity and revenue for each product sold.

The following table lists the measures and dimensions that this report contains.

Measures | Dimensions
Quantity Revenue | Date ProductsSite

Return to Product Sales Reports

Shopping Basket Events (Dynamic)

Use the Shopping Basket Events report to review user behavior in regard to shopping basket activity. This report displays products and the number of times they have been added to and removed from shopping baskets.

The following table lists the measures and dimensions that this report contains.

Measures | Dimensions
Count | Date Events ProductsSite

Return to Product Sales Reports

See Also

About Analysis

Commerce Server Reports

Setting Up Business Analytics

Finding Reports

Running Reports

Viewing Dynamic Reports

Viewing Static Reports

Printing Reports


Web Usage Reports

You use the Reports module to run reports to analyze site usage, referring URLs, and requests for data.

Directories

Entry Path Analysis

Top Referring Domains by Request

Top Requested Pages

Usage Summary by Day of Week

Usage Summary by Hour of Day

Usage Summary by Week of Year

Usage Trends

Visits by Browser, Version, and OS

Directories (Dynamic)

Use the Directories report to determine which of the 5,000 Uniform Resource Identifier (URI) directory levels are the most visited. This report displays activity for the first six levels of URI directories.

Note

  • If you want to see URIs that provide information other than the 5,000 most active URIs, for example, the least active URIs, ask your system administrator to edit the CSDW_MakeAggRequestsByUri stored procedure in the site database.

The following table lists the measures and dimensions that this report contains.

Measures | Dimensions
Hits Count | Date Directory Level Is Request Site

Return to Web Usage Reports

Entry Path Analysis (Static)

Use the Entry Path Analysis report to determine the top entry paths most frequently used to get to your site. This report displays the top six levels of path directories.

Note

  • The Entry Path Analysis report performs intensive analysis of how users traversed your site. This is a very process-intensive task and may take a long time to complete.

The following table lists the measures and dimensions that this report contains.

Measures | Dimensions
Count | URI 1 URI 2 URI 3 URI 4 URI 5 URI 6

Return to Web Usage Reports

Top Referring Domains by Request (Static)

Use the Top Referring Domains by Request report to review the sites from which your users access your site. This report displays a list of the most active referring domains by number of requests.

The following table lists the measures and dimensions that this report contains.

Measures | Dimensions
Domain | % Requests Requests

Return to Web Usage Reports

Top Requested Pages (Static)

Use the Top Requested Pages report to review the pages most requested. This report displays a list of the 5,000 most active pages, including query strings, by number of requests.

Note

  • If you want to see more than the 5,000 most active pages, for example, the least active pages, ask your system administrator to edit the CSDW_MakeAggRequestsByUri stored procedure, located under Stored Procedures in the Data Warehouse.

The following table lists the measures and dimensions that this report contains.

Measures | Dimensions
Domain | % Requests Requests

Return to Web Usage Reports

Usage Summary by Day of Week (Dynamic)

Use the Usage Summary by Day of Week report to view a PivotChart showing the average number of page requests per day of week.

The following table lists the measures and dimensions that this report contains.

Measures | Dimensions
Avg Requests Per Day of Week Avg Visits Per Day of Week | Date Day of Week Site

Return to Web Usage Reports

Usage Summary by Hour of Day (Dynamic)

Use the Usage Summary by Hour of Day report to view a PivotChart showing the average number of page requests per hour of day.

The following table lists the measures and dimensions that this report contains.

Measures | Dimensions
Avg Requests Per Hour of Day Avg Visits Per Hour of Day | Date Hour of Day Site

Return to Web Usage Reports

Usage Summary by Week of Year (Dynamic)

Use the Usage Summary by Week of Year report to view a PivotChart showing the average number of page requests per week.

Note

  • For years that begin on a Saturday, the Week of Year dimension returns week 53 for the last week.

The following table lists the measures and dimensions that this report contains.

Measures | Dimensions
Avg Requests Per Week of Year Avg Visits Per Week of Year | Date Site Week of Year

Return to Web Usage Reports

Usage Trends (Dynamic)

Use the Usage Trends report to review a summary of daily page requests, users, and visits.

The following table lists the measures and dimensions that this report contains.

Measures | Dimensions
Requests Users Visits | Date Site User Type

Return to Web Usage Reports

Visits by Browser, Version, and OS (Dynamic)

Use the Visits by Browser, Version, and Operating System (OS) report to determine which browsers are used most frequently to visit your site. For example, if your users have older browsers, you can avoid incorporating features, such as frames or multimedia, in your site design. This report displays the browsers, versions, and operating systems users are running to access your site.

The following table lists the measures and dimensions that this report contains.

Measures | Dimensions
Visits | Browser Date OS Name Site Version Visit Count

Return to Web Usage Reports

See Also

About Analysis

Commerce Server Reports

Setting Up Business Analytics

Finding Reports

Running Reports

Viewing Dynamic Reports

Viewing Static Reports

Printing Reports


User Reports

You use the Reports module to run reports to analyze user data.

Distinct Users and Visits by Week

Distinct Users by Day

New Registered Users

Registered User Properties

Registered Users by Date Registered

User Days to Register

User Registration Rate

User Trends

Distinct Users and Visits by Week (Dynamic)

Use the Distinct Users and Visits by Week report to determine whether a few people are visiting your site many times or many people are visiting your site one time. This report displays the number of unique users visiting your site and how many times your site has been visited in a particular week. This report correlates the number of unique users with the number of visits made by each one.

If you collapse the date dimension, you will see the number of unique weekly users for the time period (year). This report does not provide the number of unique user visits per year, because it counts only unique weekly visitors. For example, if a user visits on a Wednesday in a given week and visits again on Friday in the following week in a given year, that user is counted as a unique user for each of the two weeks. The unique users count for that year is two, even though both visits were by the same user.

The following table lists the measures and dimensions that this report contains.

Measures | Dimensions
Users Visits | Site Unique Users User Type Visits Week Num Year

Return to User Reports

Distinct Users by Day (Dynamic)

Use the Distinct Users by Day report to determine how many unique users visit your site in a particular day. If you collapse the date dimension, you will see the number of unique daily users for the time period (week or year). This report does not provide the number of unique user visits per week or year, because it counts only unique daily visitors. For example, if a user visits on two days in a given week, that user is counted as a unique user for each day, and the unique users count for that week is two, even though both visits were by the same user.

The following table lists the measures and dimensions that this report contains.

Measures | Dimensions
Users | Date Site Users User Type

Return to User Reports

New Registered Users (Static)

Use the New Registered Users report to identify new registered users. This data can be used to create special promotional campaigns. Export this report to the List Manager to target new registered users with online campaigns, such as direct mail promotions.

For more information about exporting static reports, see Exporting a Static Report.

The following table lists the measures and dimensions that this report contains.

Measures | Dimensions
There are no measures in this report. | Date Registered Date Created E-mail First Name Last Name User ID

Return to User Reports

Registered User Properties (Static)

Use the Registered User Properties report to review information provided by registered users. This data can be used to create special promotional campaigns. Export this report to the List Manager to target registered users with online campaigns, such as direct mail promotions.

The following table lists the measures and dimensions that this report contains.

Measures | Dimensions
There are no measures in this report. | Date Created Date Registered E-mail First Name Last Name User ID

Return to User Reports

Registered Users by Date Registered (Dynamic)

Use the Registered Users by Date Registered report to review the registration behavior of your users. This report displays user registration history for your site for a particular time period (year, quarter, month, or day).

The following table lists the measures and dimensions that this report contains.

Measures | Dimensions
Registered Users | Date Registered Users Site ID

Return to User Reports

User Days to Register (Dynamic)

Use the User Days to Register report to track the average number of days it takes guest users to register on your site.

The following table lists the measures and dimensions that this report contains.

Measures | Dimensions
Average Elapsed Days to Register | Average Elapsed Days Date Created Site

Return to User Reports

User Registration Rate (Dynamic)

Use the Registration Rate report to determine how successful you have been in getting guest users to register at your site. The report displays the time elapsed from the date users first access the site as guests until the date they register.

The following table lists the measures and dimensions that this report contains.

Measures | Dimensions
Registered Users | Elapsed Days Registered Users Site

Return to User Reports

User Trends (Dynamic)

Use the User Trends report to determine how successful you have been in attracting repeat users. This report displays the types of users (new and repeat) who visit your site by date.

The following table lists the measures and dimensions that this report contains.

Measures | Dimensions
New Users Repeat User % Repeat Users Total Users | Date Site Week of Year

Return to User Reports

See Also

About Analysis

Commerce Server Reports

Setting Up Business Analytics

Finding Reports

Running Reports

Viewing Dynamic Reports

Viewing Static Reports

Printing Reports


Visit Reports

You use the Reports module to run reports to analyze visit data.

Entry Pages

Exit Pages

General Activity Statistics

User Visit Trends

Entry Pages (Dynamic)

Use the Entry Pages report to determine the 5,000 pages on your site that users are likely to visit first. This report displays the 5,000 most frequently used URIs used to enter your site and the number of times each URI has been used.

Note

  • If you want to see URIs that provide information other than the 5,000 most frequently used URIs, for example, the least used URIs, ask your system administrator to edit the CSDW_MakeAggRequestsByUri stored procedure in the site database.

The following table lists the measures and dimensions that this report contains.

Measures | Dimensions
Visit Count | Date Site URI

Return to Visit Reports

Exit Pages (Dynamic)

Use the Exit Pages report to determine from which pages users are most like to leave your site. This report displays the 5,000 most frequently used URIs used to exit your site and the number of times each of them has been used.

Note

  • If you want to see more than the 5,000 most frequently used URIs, for example, the least active pages, ask your system administrator to edit the CSDW_MakeAggRequestsByUri stored procedure in the site database.

The following table lists the measures and dimensions that this report contains.

Measures | Dimensions
Visit Count | Date Site URI

Return to Visit Reports

General Activity Statistics (Dynamic)

Use the General Activity Statistics report to quickly review the activity on your site. This report displays the average requests per visit, the average visit duration, and the number of requests and visits, over time.

The following table lists the measures and dimensions that this report contains.

Measures | Dimensions
Average Duration per Visit Average Requests per Visit Requests Visits | Date Site

Return to Visit Reports

User Visit Trends (Dynamic)

Use the User Visit Trends report to review the number of visits to your site over time. This report displays the total number of visits, and visits by registered and unregistered users.

The following table lists the measures and dimensions that this report contains.

Measures | Dimensions
Visits | Date Site User Type

Return to Visit Reports

See Also

About Analysis

Commerce Server Reports

Setting Up Business Analytics

Finding Reports

Running Reports

Viewing Dynamic Reports

Viewing Static Reports

Printing Reports


Diagnostic Reports

You use the Reports module to run reports to analyze diagnostic data.

Bandwidth Summary

Bandwidth Trends

Hits by HTTP Status

Hits by Win32 Status

Bandwidth Summary (Dynamic)

Use the Bandwidth Summary report to view a PivotChart of the weekly bandwidth consumption for your site.

The following table lists the measures and dimensions that this report contains.

Measures | Dimensions
Bandwidth (MB) | Date Site

Return to Diagnostic Reports

Bandwidth Trends (Dynamic)

Use the Bandwidth Trends report to review the daily bandwidth consumption for your site.

The following table lists the measures and dimensions that this report contains.

Measures | Dimensions
Bandwidth (MB) | Date Day of Week Site

Return to Diagnostic Reports

Hits by HTTP Status (Dynamic)

Use the Hits by HTTP Status report to review and diagnose problems users may be encountering with the 5,000 most active pages on your site. This report displays HTTP error messages associated with the 5,000 most active pages of your Web site.

Note

  • If you want to see more than the 5,000 most active pages, for example, the least active pages, ask your system administrator to edit the CSDW_MakeAggRequestsByUri stored procedure in the site database.

The following table lists the measures and dimensions that this report contains.

Measures | Dimensions
Count | Date HTTP Status Site URI

Return to Diagnostic Reports

Hits by Win32 Status (Dynamic)

Use the Hits by Win32 Status report to review and diagnose problems users may be encountering with the 5,000 most active pages on your site. This report displays Win32 error messages associated with the 5,000 most active pages of your Web site.

Note

  • If you want to see more than the 5,000 most active pages, for example, the least active pages, ask your system administrator to edit the CSDW_MakeAggRequestsByUri stored procedure in the site database.

The following table lists the measures and dimensions that this report contains.

Measures | Dimensions
Count | Date Site Win32 Status

Return to Diagnostic Reports

See Also

About Analysis

Commerce Server Reports

Setting Up Business Analytics

Finding Reports

Running Reports

Viewing Dynamic Reports

Viewing Static Reports

Printing Reports


Query String Reports

You use the Reports module to run reports to analyze query string data.

Query Strings (multi-value)

Query Strings (single value)

Query Strings (multi-value) (Static)

You use the Query Strings (multi-value) report to determine the information that users are looking for on your site. This report displays the number of requests to query strings that you have configured for the system to analyze. For example, the system administrator can configure a multi-valued query string to track the stocks that users are most interested in.

The following table lists the measures and dimensions that this report contains.

Measures | Dimensions
Requests | Name Value

Return to Query String Reports

Query Strings (single value) (Static)

You use the Query Strings (single value) report to determine the information that users are looking for on your site. This report displays the number of requests to query strings that you have configured for the system to analyze. For example, the system administrator can configure a single-valued query string to track the number of times users enter a particular search string on your site. You could then use this report to analyze the most popular search strings on your site.

The following table lists the measures and dimensions that this report contains.

Measures | Dimensions
Requests | Name Value

Return to Diagnostic Reports

See Also

About Analysis

Commerce Server Reports

Setting Up Business Analytics

Finding Reports

Running Reports

Viewing Dynamic Reports

Viewing Static Reports

Printing Reports


Report Properties

You use Report Properties to find out details about a report before you run it. Viewing a report query, available in the properties of the report, is helpful for determining if a particular report definition will return the data you want. This is especially important if you are running a static report for a large data set, for example, running the Registered User Properties report for 10,000,000 users. Static reports running on large data sets can require significant time to process.

The report properties include useful information about the report, such as the name, description, type, date created, and the query that the report is based on. You cannot change report properties. For information about viewing report properties, see Viewing Report Properties.

The following table describes the properties that you can view in the Reports module.

Property | Description
Name | Name of the report.
Description | Description of the report.
Report type | Type of report.
Date created | Date the report was created.
Created by | Name of the person who created the report.
Date modified | Date of the last modification to the report.
Modified by | Name of the person who made the last modification.
Query | Structured Query Language (SQL) or multidimensional expressions (MDX) query to be run for the report. Query is not available for dynamic Online Analytical Processing (OLAP) reports.
Export as mailing list? | Indicates whether data from this report can be exported to List Manager as a mailing list.
Export as user list? | Indicates whether data from this report can be exported to List Manager as a user list.

See Also

About Analysis

Commerce Server Reports

Creating a New Dynamic Report


Time Handling in Reports

All Commerce Server reports present user behavior data by time. Reports on weekly activity will always use the default start day of the week (usually Sunday) for the language version of SQL Server used.


Setting Up Business Analytics

You use Analysis modules to run reports and to view Segment models to analyze user activity on your Web site. There are several tasks that must be performed to make user activity data available for analysis. The following figure shows the processes required to make data available to the Commerce Server 2000 analytical processes.

Segment Viewer
View segment models
Create segment models
Setting up business analytics
Install
Commerce Server
Install
Business Desk
Reports
Run reports
Run Report
preparation task
Import data into
Data Warehouse
Configure
Data Warehouse

To set up business analytics

  1. Your system administrator installs Commerce Server. For instructions for installing Commerce Server, see http://support.microsoft.com/support/commerceserver/2000/install/default.asp.

  2. You install the Commerce Server Business Desk client on the computers you will be using to perform business analytics tasks.

  3. Your system administrator configures the Data Warehouse. For more information about configuring the Data Warehouse, see "Configuring the Data Warehouse Resource Properties" in Commerce Server 2000 Help. Your system administrator may also assign specific SQL Server database roles to users, allowing some users to read and save reports while others can only read reports. For more information about creating these roles, see "Setting Up Data Warehouse Permissions" in Commerce Server 2000 Help.

  4. Your system administrator imports user activity data in the form of Web log, transaction, user, campaign, and catalog data, into the Data Warehouse. For information about importing data into the Data Warehouse, see "Importing Data into the Data Warehouse" in Commerce Server 2000 Help.

  5. Your system administrator runs the Report Preparation process to load the OLAP cubes with the data in the Data Warehouse. The OLAP cubes are installed when a site is unpacked. The OLAP cubes organize and store the data for improved retrieval by the analysis processes. For information about running the Report Preparation process, see "Preparing to Create Reports" in Commerce Server 2000 Help.

Your system administrator builds segment models with the data in the Data Warehouse. For information about building segment models, see "Building a New Analysis Model" in Commerce Server 2000 Help.

  6. You analyze user activity on your Web site by running analysis reports and viewing segment models. For information about running reports, see Running Reports. For information about viewing segment models, see Viewing a Segment Model.

See Also

Finding Reports

Running Reports

Viewing a Segment Model


Finding Reports

You use the Reports module to find dynamic and static reports.

You can search the Reports list for a particular report or a group of reports. You use the Find pane to get a list of all available reports or to narrow your search using the properties of the report. The resulting list contains all the reports that meet your search criteria. The list contains four columns—Name, Category, Created By, and Type—each of which corresponds to the four report properties that have those names. You can sort the resulting list by name, category, created by, and type report properties.

When you search for reports by name, category, or created by, the Reports module returns all entries that match or begin with the search string.

To view a list of all the available reports

To find a report based on its properties

To sort the Reports list

To view a list of all the available reports

  1. In Analysis, click Reports, and then click Find on the toolbar.

  2. In the Find By drop-down list, select All Reports, and then click Find Now.

A list of all the available reports appears in the Reports screen.

To find a report based on its properties

  1. In Analysis, click Reports, and then click Find on the toolbar.

  2. In the Find By drop-down list, do the following:
    Use this | To do this
    Name | Select to search for a report by its name.
    Category | Select to search for a report by the category that includes it.
    Created By | Select to search for a report by the report author.
    Type | Select to search for a report by its type, either dynamic or static.
    Any Information | Select to search for a report by any combination of search criteria—Name, Category, Created By, and Type.
    All Reports | Select to include all available reports.

  3. In the property value box that appears next, type or select from the list the specific value for the property or properties that you selected (Name, Category, Created By, and Type).

If you selected the Any Information option, text boxes appear for four properties: Name, Category, Created By, and Type.

  4. In the appropriate property value boxes, type or select specific values for one or more of the properties.

  5. Click Find Now.

A list of all the reports that match your search criteria appears in the Reports screen.

To sort the Reports list

  • In Analysis, click Reports, and then do the following:
    Use this | To do this
    Name | Click to sort by report name. By default, the Reports list is sorted in alphabetical order.
    Category | Click to sort by report category.
    Created By | Click to sort by who created the report.
    Type | Click to sort by report type.

See Also

About Analysis

Commerce Server Reports

Running Reports

Viewing Report Properties


Running Reports

You use the Reports module to run both dynamic reports and static reports. Your system administrator must perform several tasks before you can run reports. For example, on a regular basis the system administrator must import data into the Data Warehouse and run the report preparation process, ensuring the most current data is in the Data Warehouse. (If needed, your system administrator also assigns you the appropriate permissions to save and view a report.) For more information, see Setting Up Business Analytics.

Note

  • When you first open the Reports module, the default view assumes a search for All Reports. You can narrow the list of reports by using more specific search criteria.

To run a dynamic report

To run a static report

To run a dynamic report

  • In Analysis, click Reports. In the list of available reports, select the dynamic report you want to run, and then click Run on the toolbar.

The completed dynamic report appears as a PivotTable in a new browser window.

Notes

  • If your PivotTable is not visible, click Show PivotTable.

  • Commerce Server 2000 supports up to 250,000 members per dimension in dynamic reports. If the data set for the report has more than 250,000 members in a dimension, the report will appear in the browser window without data.

To run a static report

  1. In Analysis, click Reports. In the list of available reports, select the static report you want to run, and then click Run on the toolbar.

  2. In the Run a report dialog box, in the Site Name section, do the following:
    Use this | To do this
    Operand | From the drop-down list, select an operand (All, Equals, Not equal to, Like, Not Like) to determine which site the report will run for.
    Parameter value | This box contains the current site name by default. If you want to run the report for a different site, type the name of the site that you want the report to run for. If the name that you type does not match a Commerce Server site name, the report either will fail or not contain data.

  3. In the Run a report dialog box, adjust the parameters to meet your needs. All report parameters are report specific.

    Note

    • You can view the report query, site name, field name, and parameter tags for the number of users and site name by clicking the Advanced button in the Run a report dialog box.
  4. Click OK.

The static report runs and, when completed, is available for viewing in the Completed Reports module.

Caution

  • If you have many static reports running concurrently, it may slow processing time, or possibly cause your Business Desk to not respond.

See Also

About Analysis

Commerce Server Reports

Finding Reports


Viewing Dynamic Reports

You view a completed dynamic report as a PivotTable or PivotChart in a browser window.

To view a dynamic report as a PivotChart

To view a dynamic report as a PivotTable

To view a dynamic report as a PivotChart

  1. In Analysis, click Reports, and then select the dynamic report you want to run.

  2. In the Reports screen, click Run on the toolbar to run the dynamic report.

    The completed report is displayed in a new browser window as a PivotTable or a PivotChart.

    Note

    • The first time you run a dynamic report from Commerce Server Business Desk, you will be asked if you have a registered copy of Microsoft Office installed on the computer you are running Business Desk on. If you do not have a registered copy of Microsoft Office installed on that computer, you will not be able to export dynamic reports to Microsoft Excel, modify the report, or access Microsoft PivotTable List Help. You will be able to see the standard view of the data in the report.
  3. In the <completed report> browser window, do the following:
    Use this | To do this
    Show chart | Click to show the PivotChart. Click again to hide the PivotChart.
    Show legend | Click to show a legend for your PivotChart. Click again to hide the legend.
    Flip series | Click to change the way that data is presented in the PivotChart. Pressing the Flip Series button has the same effect as swapping the row and column dimensions in the PivotTable.
    Chart type drop-down list | Select a new chart type for your PivotChart from the drop-down list.

To view a dynamic report as a PivotTable

  1. In Analysis, click Reports, and then select the dynamic report you want to run.

  2. In the Reports screen, click Run on the toolbar to run the dynamic report.

    The completed report is displayed in a new browser window as a PivotTable or PivotChart.

  3. In the <completed report> browser window, do the following:
    Use this | To do this
    Show pivot | Click to show the PivotTable. Click again to hide the PivotTable.
    Show description | Click to show the report description.


Viewing Static Reports

After you run a static report, you will find the completed static report in the Reports list of the Completed Reports module.

To check the status of a static report

To search for completed static reports

To sort the completed Reports list

To open a static report

To open multiple static reports

To close a static report

To check the status of a static report

  • In Analysis, click Completed Reports.

The status of the report appears in the Status column of the Reports list. The status is one of the following:

  • Completed. The report has completed. You can now open the report to view it.

  • Pending. The report is running.

  • Failed. The report did not complete successfully. If a report fails, delete the report from the Completed Reports list and run the report again.

Note

  • The Status column in the Completed Reports module sorts on the Status ID in the order of Completed, Pending, and Failed.

To search for completed static reports

  1. In Analysis, click Completed Reports, and then click Find on the toolbar.

  2. In the Find By drop-down list, do the following:
    Use this | To do this
    Name | Select to search for a report by its name.
    Run By | Select to search for a report by the name of the person who ran the report.
    Date Run | Select to search for a report by a range of dates during which it was run.
    Status | Select to search for a report by the status of the report—Completed, Pending, or Failed.
    Any Information | Select to search for a report by any combination of search criteria—Name, Category, Created By, and Type.
    All Reports | Select to search for all available reports.

  3. In the property value box that appears next, type or select from the list the specific value for the criteria that you have selected (for example, Name, Date Run, Run By, and Status), and then click Find Now.

The resulting Reports list contains all the static reports that meet your search criteria. You can sort the Reports list by clicking any column heading.

To sort the completed Reports list

  • In Analysis, click Completed Reports, and then do the following:
    Use this | To do this
    Name | Click to sort by the name of the report.
    Date Run | Click to sort by the date the report was run. By default, the reports are sorted by Date Run in descending order.
    Time Run | Click to sort by the time of day the report was run.
    Run By | Click to sort by the name of the person who ran the report.
    Status | Click to sort by the report status—Completed, Pending, or Failed.

Notes

  • The Status column in the Completed Reports module sorts in the order of Failed, Pending, and Completed.

  • The Time Run column sorts by the date the report was run. You cannot sort by Time Run independently of Date Run.

To open a static report

  1. In Analysis, click Completed Reports.

  2. In the Reports list, select the report you want to open, and then click Open on the toolbar.

    Note

    • You can only open reports with a status of Completed.

The static report appears in a new browser window as an HTML document.

To open multiple static reports

  1. In Analysis, click Completed Reports.

  2. In the completed Reports list, select the reports you want to open, and then click Open on the toolbar.

The static reports appear in new browser windows as HTML documents.

Notes

  • If you click the Select All button to select all the reports in the list, you cannot open them. If you want to open all the reports in your list, you must select each report individually.

  • Opening multiple static reports may exceed the memory limitations of the Web browser, and cause the Completed Reports module to not respond.

To close a static report

  • Close the browser window that contains the report.

See Also

Printing Reports

Exporting a Dynamic Report

Exporting a Static Report


Printing Reports

Commerce Server 2000 reports are designed to be viewed in the browser window. You can print dynamic and static reports from the Web browser. You will encounter size limitations if you are printing and displaying large reports.

When you print a dynamic report PivotTable, the Web browser prints only the parts of the PivotTable that are visible in the browser window, without scrolling. If you expand nodes of the PivotTable and the resulting table exceeds the browser memory limitation, the PivotTable will not print. To print a large PivotTable in its entirety, export the PivotTable to Microsoft Excel. For information about exporting a PivotTable to Microsoft Excel, see Exporting a Dynamic Report. For information about printing from Excel, see Excel Help.

When you run a static report, the completed report is limited to displaying 1,000 lines in the browser window. You can export a large static report to the List Manager to see all the lines of the report. For information about exporting reports to List Manager, see Exporting a Static Report.

To print a report

  1. In the browser window, in the File menu, click Print.

  2. In the Print dialog box, click Print.

The report prints.

See Also

Exporting a Dynamic Report

Exporting a Static Report


Exporting a Dynamic Report

You use the PivotTable controls to export a completed dynamic report to Microsoft Excel. You use Microsoft Excel to save, modify, and print completed dynamic reports. You must have Microsoft Excel installed on the computer you are viewing the report on.

To export a completed dynamic report to Microsoft Excel

  1. In Analysis, click Reports. In the list of available reports, select the dynamic report you want to run, and then click Run on the toolbar.

    The completed dynamic report appears as a PivotTable in a new browser window.

    Note

    • If the PivotTable is not visible, click Show PivotTable.
  2. To open your report in Microsoft Excel, in the PivotTable screen, click Export to Excel on the PivotTable toolbar.

The report now appears as an Excel spreadsheet.

See Also

About Analysis

Commerce Server Reports

Running Reports

Exporting a Static Report

Exporting a Report to List Manager


Exporting a Static Report

You use the Reports module to export data from your static report to the List Manager module. Data from static reports that have the Direct Mail property can be used in direct mail campaigns. You can access and update data from static user reports, for example, Registered User Properties, in the Users module.

To export data to a list

  1. In Analysis, click Reports.

  2. In the Reports list, select the static report containing the data you want to export, and then click Export on the toolbar.

  3. In the Run a report dialog box, adjust the report parameters to meet your needs. All report parameters are report specific.

    Notes

    • If the name that you type in the Site Name: Parameter Value box does not match a Commerce Server site name, the export will not contain data.

    • To view the report query, site name, field name, and parameter tags for the number of users and site name, click Advanced in the Run a report dialog box.
  4. Click OK.

  5. In the Export report as a list dialog box, do the following:
    Use this | To do this
    Static | Select to export a static list.
    Dynamic | Select to export a dynamic list.
    List Name | Type a unique name for the list.
    Report Name | View the name of the report the list is created from.

  6. Click OK.

Your static report is exported to the List Manager module as a list.

Open the List Manager module to verify that your data was exported as a list. For information about exporting lists to List Manager, see Exporting a Report to List Manager.

See Also

About Analysis

Commerce Server Reports

Running Reports

Exporting a Dynamic Report

Exporting a Report to List Manager


Creating a New Dynamic Report

You use the Reports module to change the PivotTable of a report, and save the changed report as a new report definition. The newly saved report is then available in the Reports list. For information about creating custom reports for use by site developers, see Creating Custom Reports.

Note

  • You cannot save PivotCharts.

To add fields to a PivotTable

To see your new report in the Reports list

To refresh the Reports list

To add fields to a PivotTable

  1. In Analysis, click Reports, and then select the dynamic report you want to run.

  2. In the Reports screen, click Run on the toolbar to run the dynamic report.

    The completed report is displayed in a new browser window as a PivotTable. The PivotTable Field List appears above the PivotTable.

    Note

    • If the PivotTable Field List does not appear automatically when you open the table, click the Field List button on the PivotTable toolbar.
  3. Drag fields from the PivotTable Field List and drop them into the PivotTable.

    In a PivotTable, the items under Totals in the field list are measures; the items at the same level as Totals are dimensions. Measures can be added to the data area (that is, the center cells) of the PivotTable. Dimensions can be used as rows, columns, or filters.

    As an alternative to using a drag-and-drop operation to move the fields from the PivotTable Field List, you can use the Add to button at the bottom of the PivotTable Field List. For information about using the field list, click the Help button on the PivotTable toolbar.

  4. In the completed report window, click Save just above the PivotTable. The Save a report — Web Page dialog box appears.

  5. In the Save a report—Web Page dialog box, do the following:
    Use this | To do this
    Report Name | Type the name of your new report.
    Report Description | Type a description of your new report.
    Report Long Description | Type a longer description of your report. This description will be visible in the browser window above the PivotTable controls when you click Show description above the PivotTable controls.

  6. Click OK. Your new report is saved.

  7. To return to the Reports screen, close the report window.

For more information about working with PivotTables, see PivotTable Help, available when you click the Help button on the PivotTable toolbar.

Important

  • When you save a new report, you are saving the report definition, not the data. The next time you run the report, it will have the same rows, columns, and filters, and the current data will be queried from Microsoft SQL Server 2000 Analysis Services (OLAP) as specified in the report definition.

To see your new report in the Reports list

  1. In Analysis, click Reports.

  2. In the Reports screen, click Find on the toolbar, check that the present search criteria will find your report, and then click Find Now.

To refresh the Reports list

  1. In Analysis, click Reports, and then click Find on the toolbar.

  2. In the Find By box, select All Reports, and then click Find Now.

A new Reports list appears showing all reports.

See Also

About Analysis

Commerce Server Reports


Deleting Reports

You use the Reports module to delete custom report definitions. You use the Completed Reports module to delete completed static reports. You cannot delete dynamic or static report definitions included with Commerce Server. These are system reports. System reports show "System" in the Created By column of the Reports list in the Reports module.

Deleting Custom Report Definitions

Deleting Completed Static Reports

Deleting Custom Report Definitions

You use the Reports module to delete custom report definitions. You cannot delete system reports. System reports show "System" in the Created By column.

Caution

  • When you delete a custom report in the Reports module, you delete the report definition, and you will not be able to run the report again.

To delete a custom report

  1. In Analysis, click Reports, and then select the custom reports you want to delete.

  2. Click Delete the toolbar.

  3. In the Delete Reports? dialog box, click Yes.

The selected custom reports are deleted. The Reports list no longer shows the deleted reports.

Deleting Completed Static Reports

You use the Completed Reports module to delete completed static reports. When you delete a static report in the Completed Reports module, you delete only the completed report. The report definition remains in the Reports module.

Notes

  • You can delete a failed report in the same way you delete a completed report.

  • Deleting a running (Pending) report from the Reports list does not terminate the report. The report will continue to run.

To delete a completed static report

  1. In Analysis, click Completed Reports.

  2. In the Reports list, select the reports you want to delete, and then click Delete on the toolbar.

The selected static reports are deleted. The Report list no longer shows the deleted reports.

See Also

About Analysis

Commerce Server Reports


Viewing Report Properties

You use the Reports module to view the Name, Description, Report type, Date created, Created by, Date modified, Modified by, Query, Export as mailing list, and Export as user list properties for both static and dynamic reports. You view the query property to help you determine if the report will return the information you want.

You cannot change report properties. If you cannot find a report definition with a query that returns the data you are looking for, you can modify a dynamic report definition and save it as a new dynamic report definition or ask your system administrator to create a new dynamic or static report definition that meets your needs. For more information about modifying a dynamic report definition to create a new dynamic report definition, see Creating a New Dynamic Report.

To view the properties of a report

  • In Analysis, click Reports. In the Reports list, select the report that contains the properties you want to view, and then click Open on the toolbar.

A list of the report properties appears.

See Also

About Analysis

Commerce Server Reports

Finding Reports


Analyzing Population Segments

Segments represent groups of users who share characteristics or behavior. Segments are derived from properties stored in the Data Warehouse. You use the Segment Viewer module to analyze segments and segment groups to identify specific characteristics or behavior, such as usage trends. You can then use the results of your analysis to make marketing decisions based upon similarities among users.

A Segment model is the collection of segments created when the Segment model was constructed and describes the characteristics of the users belonging to each of the segments and segment groups. A Segment model describes the characteristics of the users belonging to each of the segments and segment groups. You use Segment models to discover and analyze the attribute values that characterize the users visiting your site.

For example, after building a Segment model, you may discover a segment characterizing users who purchased a popular fantasy book for children: female, over 40, income above $55,000 per year, and an education level of college graduate or greater. After you have discovered these common characteristics, you can then offer similar products to users matching those criteria. For example, these users may also be likely to buy an animal book for children.

You view Segment models in the Segment Viewer module of Commerce Server Business Desk. The segments and segment groups you view are named generically by Commerce Server; after you analyze their contents, you should rename them to something more descriptive. After you have renamed your segments, you can compare them to each other and then generate a report showing those comparisons. You can also export your segment data to the List Manager module in Business Desk to create mailing lists, to add properties to user profiles for targeting, and so on.

This section contains:

  • Viewing a Segment Model

  • Comparing Two Segments or Segment Groups

  • Renaming a Segment or Segment Group

  • Viewing a Segment Report

  • Exporting Segment Data to List Manager

See Also

Segment Analysis

Commerce Server Reports


Viewing a Segment Model

The first time you view a Segment model, the segments and segment groups in the Segment hierarchy have generic names, such as Segment1, Segment2, and so on. The percentage of the total population represented in a segment or segment group appears in parentheses after the name. The segment summary appears on the screen to the right of the segment list.

Segment Viewer work area

Click the illustration to enlarge or reduce.

The summary of your segment or segment group contains a table with the following columns:

  • Property/value pairs. Correspond to each other and best summarize the records in the selected segment or segment group. For example, if the majority of records in a given segment correspond to people whose occupation is "Student," then "Occupation" appears in the Property column and "Student" appears in the Value column.

  • Score. Displays a red bar, the length of which is a relative indicator of how well the matching property/value pair summarizes the records in the selected segment or segment group.

To view a Segment model

  • Click Segment Viewer, select the Segment model you want to view, and then click Open Model on the toolbar.

The Segment Viewer screen appears with the top-level segment group, which is labeled Population (100%), visible. To view lower-level segments and segment groups, click the arrow next to the top-level segment group.

Note

  • You can view only one Segment model at a time.

Your system administrator creates Segment models in Commerce Server Manager. For information about creating Segment models, see "Running the Predictor Resource" in Commerce Server 2000 Help.

See Also

Workflow for Segment Analysis

Segment Viewer

Commerce Server Reports


Comparing Two Segments or Segment Groups

You can compare one segment or segment group to another using the Segment Viewer module. As an example, you may find that one segment corresponds to users who frequent your site and another segment corresponds to infrequent users. You may want to compare users to determine what characteristics distinguish the frequent users from the infrequent users.

To make segment comparisons, select a segment and then select the segment you want to compare it to. The comparison appears in a table with the following columns:

  • Property/value pairs. The property/value pairs that appear are those that best distinguish between the users in the selected segment or segment group and the users in the comparison segment or segment group.

  • Selected Segment. This column contains a yellow bar the length of which indicates the degree to which a record, with the corresponding property/value pair, belongs in the selected segment or segment group rather than in the comparison segment or segment group.

  • Comparison Segment. The column contains a blue bar the length of which indicates the degree to which a record, with the corresponding property/value pair, belongs in the comparison segment or segment group rather than in the selected segment or segment group.

To compare two segments or segment groups

  1. Click Segment Viewer, select the Segment model that contains the segments you want to compare, and then click Open Model on the toolbar.

  2. In the Segment hierarchy, select the segment or segment group to compare.

    A summary of the selected segment or segment group appears under Summary of <Segment Name> on the Segment Viewer screen.

  3. In the Compare Segment <Segment Name> to box, select from the drop-down list the segment or segment group to which you want to compare the segment you selected in the previous step.

A comparison summary appears in the lower section of the Segment Viewer screen. The properties appear in order of their relative membership strength in the selected segment or comparison segment.


Renaming a Segment or Segment Group

The first time you open a Segment model, the segments and segment groups have assigned names that are generic, such as Segment1, Segment2, and so on. These generic names are listed in the Segment hierarchy. The entire population for all segments is listed in the Segment hierarchy as Population (100%).

After you have examined a segment or segment group and determined which of its characteristics are significant, by using the summary information for the segment and comparing it to other segments, you can give it a more descriptive name. When you choose a new name for a segment or segment group, you must choose a name that is unique to the Segment model.

To rename a segment or segment group

  1. Click Segment Viewer, select the Segment model that contains the segment or segment group you want to rename, and then click Open Model on the toolbar.

  2. In the Segment hierarchy, expand the top-level segment group until you see the segment or segment group you want to rename, select it, and then click Rename.

  3. In the Rename Segment dialog box, type a new name for the segment or segment group, and then click OK.

    The new name replaces the old name in the Segment hierarchy.

  4. To rename additional segments or segment groups, repeat Step 3.

  5. When you have renamed all the segments and segment groups you want, and are ready to save your changes to the Segment model, click Save on the toolbar.

The new names are saved.

Note

  • If you change several names for a large segment group, it may take several minutes to save your changes.

See Also

Commerce Server Reports


Viewing a Segment Report

You use the Segment Viewer to generate a report that is a summary of all the segments and segment groups you have created. The report appears in a separate Internet Explorer window. You use this report to compare all segments. Each segment and segment group has links to its detailed information; clicking on these links allows you to move easily between segments.

To view a segment report

  1. Click Segment Viewer, select the Segment model that contains the report you want to view, and then click Open Model on the toolbar.

  2. In the Segment hierarchy list, select the segment that you want to build a report from, and then click Launch Report on the toolbar.

The report appears in an Internet Explorer window.


Exporting Segment Data to List Manager

After you create your segments, you can create a list of the users in those segments for further analysis and management. You export your segment data to List Manager in Commerce Server Business Desk.

To export segment data to List Manager

  1. Click Segment Viewer, select the Segment model that contains the data you want to export, and then click Open Model on the toolbar.

  2. In the Segment hierarchy, select the segment that contains the data you want to export, and then click Export Segment to List on the toolbar.

  3. In the Export Segment to List dialog box, do the following:
    Use this | To do this
    Enter list name | Type a name for the list.
    Minimum probability | Type the threshold probability of membership that a user must exceed to be included in a list.

  4. Click OK.

After you have exported your data, go to the List Manager module in Business Desk to view it. If you are exporting a relatively small amount of data, the exported data should appear in List Manager almost immediately. If you are exporting a large amount of data, it may take a few minutes for the data to appear. For more information about exporting reports, see Exporting a Report to List Manager.

Note

  • In order to export user information to a list, you must select a segment and not a segment group. If you select a segment group, the Export Segment to List on the toolbar is disabled.


Business Desk Campaigns

You use the Campaigns modules to create and manage marketing campaigns. The Campaigns modules provide an easy to use interface to help you create and manage your campaign schedules. The campaign schedule is used to determine the type of content that will be shown to the user and when the content will be delivered. You can create an ad campaign, a direct mail campaign, or a discount campaign, and then specify when the content will be delivered to the targeted group of users.

You can run campaign reports to help you make informed decisions about pricing, marketing, advertising, and other aspects of your business. Analyzing your campaigns gives you the ability to promote the campaigns that are the most successful.

This section contains:

  • Workflow for Campaign Management. Illustrates the workflow for creating, targeting, and managing campaigns.

  • About Campaigns. Describes ads, discounts, and direct mail, and how to use campaign goaling. Describes how to create targeting expressions.

  • Setting Up Your Reference Tables. Explains how to set up content sizes, industry codes, and page groups to match your business model.

  • Creating a Campaign. Explains how to add customer information, add and schedule a campaign, create and preview a campaign item, and then send it to production.

  • Publishing Campaign Changes on Your Web Site. Explains how to update your site with new information that you have added using Business Desk.

  • Changing Between Campaign Goaling and Advertising Item Goaling. Explains how changing campaign goaling affects the weights of your ads.

  • Adding an Ad Campaign Item. Explains how to add an ad campaign item, specify the size of the ad, and target the ad to Web pages and groups of users.

  • Adding a Discount Campaign Item. Explains how to create and manage a discount campaign.

  • Targeting an Ad or Discount. Explains the purpose and use of target expressions, catalog expressions, and how to create a target group.

  • Adding a Direct Mail Campaign Item. Explains how to create and use lists of site users.

  • Managing Lists of User Records. Explains how to use List Manager to create and manage mailing lists and lists of users.

  • Analyzing a Campaign. Explains how to run a campaign report and export it to List Manager.

  • Deleting and Restoring Campaigns. Explains how to delete and restore campaigns.

  • Searching Campaigns. Explains how to search the campaigns on your site using filter criteria.


Workflow for Campaign Management

The following figure illustrates a sample scenario for creating, managing, analyzing, and targeting campaigns.

Workflow for creating, managing, analyzing, and targeting campaigns
Reference Tables
Analyzing a Campaign
Campaign Manager
Setting Up Your Reference Tables
Creating a Campaign
Importing a Mailing List
Creating a Direct Mail Campaign
Analysis
Campaign Manager
Campaign Expressions Target Group
Targeting an Ad or Discount
List Manager

  1. In the Reference Tables module, you specify your content sizes, and add industry codes and page groups. Only perform this step if you need to add or change the tables provided by your site developer.

  2. In the Campaign Manager module, create a new customer (such as Arbor Shoes), and create a campaign (such as Fall Season Sale), and then add a discount campaign item (such as Member Discount).

  3. In the Campaigns Expressions module, create a target expression to specify the users you want to deliver the discount to.

  4. In the Campaign Manager module, run a report to analyze the effectiveness of your ad campaign.

  5. In the List Manager module, import the campaign report into List Manager.

  6. In the Campaign Manager module, use the list to run a direct mail job to target your users more successfully.

See Also

About Campaigns


About Campaigns

You use the Campaigns modules to create and schedule marketing campaigns and deliver targeted content for Web sites. Commerce Server provides several different delivery mechanisms for your online campaigns. For example, you can create campaigns for advertisements, discounts, and direct mail. You can also analyze your campaigns giving you the ability to make decisions about pricing, targeting content, and other aspects of your business. After you analyze your user data, you can update your site to better target your users.

The Campaigns modules are designed so you can work with your customers to maximize the effect of ads, discounts, and direct mail. With Campaigns, you can:

  • Target ads or discounts to users of a specific profile. You set up a user profile using the Profile Designer module, and then integrate it into a campaign. For each individual ad page, you can specify whether the profile for the user browsing that page should be considered for targeted content, or ignored.

  • Run campaigns for customers who compete within the same industry. The competing ads are never shown on the same page.

  • Charge your customers based on the number of ad requests they want their ads to receive.

This section contains:

  • Campaign Structure

  • Campaign Goaling

  • Reference Tables

  • Ads

  • Discounts

  • Direct Mail

  • User Lists and Mailing Lists

  • Targeting and Personalization

  • Campaign Effectiveness


Campaign Structure

A campaign is a marketing program that represents one or more contracts or orders from a customer. For example, you might have a campaign to introduce new products, retain existing users, or increase market share. Each campaign may include multiple campaign items: ads, discounts, or direct mail messages.

You use the Campaign Manager module to create and manage customers, and then campaigns, and then campaign items.

The following figure shows the hierarchical structure of the Campaign Manager tree.

Click the illustration to enlarge or reduce.

Customer information, such as billing address, is used for all campaigns created for that customer. You can view all your customers in alphabetical order in the Campaign Manager module.

All campaign items within one campaign have a common customer and date ranges. For example, in the travel section of a Newspaper site, an advertiser might request the delivery of 10,000 requests within a week to users from the Northwest. The advertiser might decide to run three different ads to fill those 10,000 requests and then see which one of the three ads creates the highest click rate. Each ad is a campaign item.


Campaign Goaling

Campaign goaling is the process of specifying the number of ads to deliver (the goal) in a certain amount of time. You can goal by clicks on an ad or by requests for an ad. You can goal campaigns at the campaign level or at the ad level.

  • Campaign level goaling applies the goals to all of the campaign items (ads) in the campaign by using a weighted distribution of the total number of requests.

    For example, say you perform goaling at the campaign level for a customer. The customer gives you two ads, and orders 25,000 ad requests. At the campaign level, one ad is set up to display 60 percent of the ad requests, and the other ad is set to display 40 percent of the ad requests. If the customer changes the number of ad requests, for example, to 40,000, you do not have to manually change the number of times the ads are to display; they are still 60 percent and 40 percent.

  • Ad level goaling applies the goals at the campaign item level. The total requests for the campaign will be equal to the total number of ordered requests for each campaign item. For example, a customer might order 50,000 requests to be delivered in one month. The ad item must be delivered 50,000 times.

You can switch between campaign level goaling and ad level goaling. For example, a customer orders two ad campaign items to run in even proportion for a quantity ordered of 1000 ad requests. You perform the following steps:

  1. You add the campaign items to a campaign, and assign each item a weight of 1. The quantity ordered for each item is 500 ad requests.

  2. Later, the same customer requires 500 more requests for Ad 1. You open the campaign and change the goaling to Advertising, select Ad 1, and then add 500 items to the quantity.

    The quantity ordered for Ad 1 is 1000. The quantity ordered for Ad 2 is 500. The total quantity ordered is not visible in the Campaign Manager module for ad goaled campaigns.

  3. Finally, the customer wants to redistribute the order so that Ad 1 is run at a rate of 3 to 1 with Ad 2. You change the goaling to Campaign level goaling. The quantity ordered reappears containing the sum of the quantity ordered for all ads or 1500. Now the weights for each of the ads are the same as the quantity ordered.

    At this point you can edit the weights of each ad so that the weights are 3 and 1 and Commerce Server will calculate the new quantities, or figure out that the new paid weights would be 1125 and 375.

In a different situation, for example, after step two the customer wants the campaign run at a rate of 2 to1 and the third ad to also have weight of 1. If you add an ad to a campaign that has been converted from an ad level goaling to Campaign level goaling, and leave the weight of 1 without changing the paid weights of the other ads, the ad delivery will be skewed. You should reopen the Campaign Manager and assign new weights to all of the ads, and then verify the actual calculations.

See Also

Changing Between Campaign Goaling and Advertising Item Goaling

Scheduling a Campaign


Reference Tables

You use the Reference Tables module in Business Desk to set the sizes of content that is displayed on your site, to manage the names of Page Groups, and to establish industry codes that you can use to prevent two ads from the same industry showing up on the same page at the same time. The properties in the Reference Table module ensure the consistency of advertising content across your site.

  • Content Sizes are the sizes you want for your content (ads and discounts). Commerce Server 2000 provides several default content sizes. These content sizes are taken from a list of commonly used sizes approved by the Internet Advertising Bureau (IAB). Content sizes are validated through the Content Size section in the Reference Tables module.

    The content sizes in the reference tables are available when you select the size you want for your campaign item content. You can view, edit, and delete any of the predefined sizes, or you can create a new content size to fit your needs.

  • Industry codes are codes for different industries, for example, automotive, aviation, and beverage. You use industry codes to identify the associated industry of an advertisement, thus preventing two ads from competing companies in the same industry from appearing on the same page. Industry codes do not apply to discounts.

    You can update your industry codes, for example, to include more than one beverage code, such as one for coffee and one for milk, so that ads for different types of beverages can appear on the same page. For example, it may be acceptable for an ad for coffee to compete with an ad for milk on the same page. You can set the level at which the industry conflict is monitored by controlling the number of entries in this table.

    Commerce Server provides several popular industry codes for your use. The industry codes used in ads are validated through the Industry Codes section in the Reference Tables module. The industry codes in the reference tables are available when you select the industry code for a campaign item. You can view a list of all current industry codes, add new industry codes, edit industry codes, and delete industry codes from the Industry Code section in the Reference Tables module.

  • Page groups are a set of related Web pages that is tagged with a particular page group name and used for targeting ads. For example, if you are running a newspaper site, you might create a page group for Sports, one for the Top Story, and another for Local News. You can then target ads to display only on pages in certain page groups.

    When you bill customers for displaying ads on your site, you can base the advertising rates by page group. For example, you can charge a premium for ads displayed on your home page, but less for ads displayed on other pages.

Note

  • Before a page group can be used, contact your site developer to ad-enable the page for you.

See Also

Setting Up Your Reference Tables


Ads

Commerce Server supports two types of ads: paid ads and house ads.

  • Paid ads are pieces of content to be delivered by Commerce Server based on a specific formula for delivery referred to as Need of Delivery (NOD).

  • House ads are pieces of content that are served when paid ads are ahead of the Need of Delivery schedule specified for them. For example, a customer orders 1000 paid ads to be delivered over four months, but in the first two months the ad has been served 850 times. To balance the Need of Delivery schedule, house ads would be served.

    House ads are critical to ensure the smooth delivery of your paid ads. House ads are also displayed when there are no paid ads eligible for the request. For example, a house ad would be served because all paid ads missed a required target.

    House ads may also be used to sell leftover inventory at discounted prices. They may also be used if the ads on the site do not have specific delivery goals, but you want to have the ads run at specified weights.

Components of an Ad

In Commerce Server, ads are treated as having four parts:

  • Ad Properties include the name of the ad, the type (paid ad or house ad), the weight or number of requests or clicks scheduled to be delivered (paid ad versus house ad), the exposure limit, and the industry associated with the ad.

  • Ad Schedule is the start date/time and end date/time. You can select the days of the week on which the ad will be displayed, and what times of each day.

  • Ad Target identifies the pages on which the discount will be displayed, and the groups it will be targeted to.

  • Ad Display identifies the size of the ad, the type (for example, image, text, or HTML), and if needed, the image and/or URL that the user can click to go to another page (or Web site). You can display ads as images, text, HTML, non-clickable images, Buy Now ads, Windows Media Services, or vignette. (A vignette ad is composed of text that is displayed adjacent to the image where the ad is displayed.)

Targeting Ads

Using Commerce Server, you can determine when an ad is displayed, where, and to whom. When you create an ad, you specify the following:

  • Exposure limit. The number of times the ad can be shown to a user within a session.

  • Weight. A means of determining how frequently an ad is displayed, relative to all of the campaign items for a given customer. In a campaign, weight only applies to ads that are goaled at the campaign-level. If the ads are goaled at the item level, weight is not used for paid ads.

    For house ads the weight is relative to all other house ads for all customers and all campaigns. For paid ads, the weight is relative to other paid ads in the same campaign. The weight of an individual campaign item is relative to the weight of all the other campaign items.

    For example, assume you have four ads to sell paint, and you assign the weight as follows:

    Ad | Weight | Percentage of times served
    Blue paint | 1 | 10
    Green paint | 2 | 20
    Red paint | 3 | 30
    Yellow paint | 4 | 40
    Total Weight | 10 | 100

    The total weight of all the ads is 100 (10+20+30+40 = 100). The Blue paint ad has a weight of 1 so it will be displayed once out of every ten ad requests.

    For paid ads, the weight is the ratio of a single ad to the sum of all the campaign items for that campaign. For house ads, the weight is the sum of the weights of all other house ads in the campaign.

    For ads that are goaled at the campaign item-level, weight is not used to determine the delivery of the ad. Instead, you directly specify the number of requests or clicks that should be served.

  • Page Groups. A set of related Web pages is tagged with a particular page group name and used for targeting ads. For example, if you are running a newspaper site, you might create a page group for Sports, one for the Top Story, and another for Local News. You can then target ads to display only on pages in certain page groups.

    You create page groups using the Reference Tables module.

  • Target Groups. A collection of targets to which content will be displayed. For example, you can target ads to users who have specific profile properties. For more information about targets and target groups, see Targeting and Personalization.

Processing Ad Campaign Items

The Content Selection Framework (CSF) processes the variables that you specify for an ad: campaign goaling, exposure limit, schedule, weight, page groups, and target groups. Each time a user visits your site, it determines whether the ad is to be displayed.

The Content Selection Framework for advertising uses a formula called Need of Delivery (NOD) to initially score the advertisements based on how far behind schedule they are. This formula takes into account the total quantity of content to be delivered and the length of time over which the quantity must be delivered. Need of Delivery is calculated for each ad request by the Content Selection Framework after it has processed the ad request. Need of Delivery is applied to paid ads only; it is not applied to house ads.

If you have several ads and want to know on what basis they are being displayed, contact your site developer. Commerce Server includes a tool named TraceScores that your site developer can use to trace the selection process. Use TraceScores to see exactly how the internal content decision process works.

If you plan to run many campaigns simultaneously, using the same target group and the same priority, the Content Selection Framework selects the ad to be displayed based on the ad type. If the ads are both house ads, an ad is selected at random using the weights as relative probabilities. If the ads are paid ads, an ad is selected for display based on the Need Of Delivery Calculation (which takes into account the start date, end date, number of events scheduled, and number of events served to date). One of the score modifications is History Penalty, which applies a decreasing penalty to ads recently seen by a user. When the History Penalty is enabled, ads are "rotated" over time.

See Also

Adding an Ad Campaign Item


Discounts

You can apply discounts to any item in your catalog. You can apply a discount against an entire order (an order-level discount), or you can apply it against specific items in the order (an item-level discount).

  • Order-level discounts apply to all products in a shopping basket. For example, free shipping is a type of order-level discount: you can give users free shipping for all products in their basket. Free shipping is the only order-level discount delivered with Commerce Server. If you want to offer another type of order-level discount, for example, a 10 percent discount for preferred users, a site developer must make custom changes to your site.

  • Item-level discounts apply to specific products in the basket.

If you apply a discount to an entire order, the discount is applied to each item individually. Only one discount can be applied to an order line item with a quantity of one. Two discounts cannot be applied to the same item with a quantity of one.

You can use Commerce Server to create and apply the following discount types:

  • Click-required discounts are only applied if the user clicks the discount URL, which may be an image of the product that says, for example, "10 percent off." Site developers can extend this type of discount for other uses, such as offering coupons, which the customer must have in order to enjoy the discount.

  • Leverage discounts are based on the purchase of other products. For example, when users add a telephone to their basket, you can offer them a hands-free headset at checkout that they can then accept by adding it to their basket. Or, you can offer users another accessory at a discounted price.

  • Percentage-off discounts reduce the price of products by a percentage, rather than by dollar amount. For example, you can discount products by 10 percent, and then change the price of the products as needed. When you change the price of the products, the discount amount is updated automatically.

  • Dollar-off discounts reduce the price of products by a fixed amount. For example, you can offer a $5.00 discount on certain products. Even though you may change the price of the products, the discount amount ($5.00) always stays the same.

  • "Happy Hour" discounts reduce the price of products during certain dates. To schedule discounts to apply during certain hours, you can build expressions that evaluate the Current Time property. For example, if Current Time > 5:00 pm and Current Time < 9:00 pm, discount the product by 10 percent.

You can apply these discounts to individual products, all the products in a category, or you can create an expression to discount products that meet specific criteria, for example, to offer a 10 percent discount on all items from a certain manufacturer.

For example, you can create discounts to apply in the following situations:

  • Price of product is greater than $20.00. This is a discount condition expression. Discount condition expressions are based on a product property.

  • User buys 2. This is part of a required discount condition criteria.

  • User clicks a discount ad on the Sports page. This is the click-required part of a discount.

  • User is registered. This is a discount eligibility expression. Discount eligibility expressions are based on user profiles and context profiles.

You cannot apply multiple discounts to one product simultaneously. A customer can enjoy only one discount per product, or a condition can be applied toward only one discount. After a product as been used as a condition or an award for one discount, it cannot be used as a condition or award for another discount.

Components of a Discount

A discount campaign item has the following components: discount properties, discount definition, discount target, and discount display. You use the Campaign Manager module to define these components when you create the discount.

  • Discount properties are the name of the discount, priority, start date and end date.

  • Discount definition is a specification of what you are discounting, how much, and for whom. A discount definition has the following parts:
    • Target expression identifies what is discounted. For example, the target expression Book_price > 20 applies the discount to all books meeting that criteria.

    • Requirement identifies the user and/or context in which the discount is advertised. For example, if the user is a registered female who purchased $50.00 of merchandise during her last visit, you can offer a discount. Or, if the user shops your site during a certain day, or views a specific page, the user may meet the context requirements and receive a 10 percent discount.

    • Award identifies what the users receive, for example, a 10 percent discount or free shipping. An award condition must be true for the discount to apply. The award condition is evaluated for each item in the order form. An award condition can be an expression specifying that the discount applies to a particular item, or it can specify that it applies to all items.
  • Discount Target identifies the pages on which the discount will be advertised, and to which target groups.

  • Discount Display identifies how many times you will display the discount to a user, the image and/or URL that the user clicks to get the discount, and the discount information that will be displayed in the basket when the user checks out.

Discount Priority

You give every discount a priority that determines when it should be applied relative to other discounts that may also apply to a product. (Unlike ads, discounts do not use weights to determine when they are delivered.) For example, you create three discounts and assign each a priority as shown in the following table.

Discount | Priority
10 percent discount for telephones | 10
30 percent discount for premier users who buy telephones, radios, or computers | 20
Free shipping | 30

If a premier user shops your site and purchases a telephone, among other items, only the 10 percent discount would be applied to the telephone. Neither the 30 percent discount nor the free shipping discount would apply to the telephone purchase because those discounts are a lower priority.

If two discounts have the same priority, the type of database you are using may influence which discount is applied. The results will be undetermined for discounts with the same priority.

Discounts Based on Quantity or Value Purchased

You can apply discounts based on the quantity that users purchase, or on the value of the purchase. For example, you can create a discount that applies when a user buys three cases of juice (quantity), or a discount that applies when a user buys $20.00 worth of juice (value).

You can apply one discount per quantity or value. For example, the beverage department of your online store has a special offer for summer: buy one case of juice; get the second case for half price. However, your online store has another special offering 10 percent discount on each product in the beverage category. Assume you prioritize these discounts as shown in the following table.

Discount | Priority
Buy one case of juice, get the second case at a 50 percent discount. | 10
10 percent discount on each product in the beverage category. | 20

If a user buys four cases of juice, the discounts are applied as follows:

  • Case 1: No discount

  • Case 2: 50 percent discount

  • Case 3: 10 percent discount

  • Case 4: 50 percent discount, only if no limit was placed on the "Buy one get second half price" discount. The 50 percent discount would apply again instead of the 10 percent discount because you gave it a higher priority.

Discount Limits

You can limit the number of discounts that can be applied to a basket. If the discount limit has a value of zero (0), discounts are unlimited: the discount can apply multiple times, assuming the condition for the discount is met multiple times in the basket. The discount limit is a basket limit and does not apply across baskets. For example, if a user checks out, returns to the site, and buys the same discounted items then the user will receive the same discount again.

Processing Discount Campaign Items

Discount campaigns are processed by the discounts Content Selection pipeline and the OrderDiscount pipeline component. You use the discounts CSF pipeline to advertise the most appropriate discount to a user. The OrderDiscount component in the Basket pipeline is used to apply discounts to the shopping basket.

  • Discounts Content Selection pipeline checks the start date and end date of the discounts, and then adjusts the scores in the list of possible discounts. It ensures that the discounts that are most relevant to the current user receive the highest priority.

  • The OrderDiscount pipeline component first applies the requirements to the available discounts. Depending on the discount involved, it uses the user profile and context profile information to evaluate target expressions. In addition, if a discount requires a click, it checks the list of campaign item IDs for every item clicked. Next, the Order pipeline processes each item, testing the conditions and awards. Discounts are applied from highest to lowest priority. If two discounts have the same priority, properties other than the priority determine the order in which the discounts are applied.

See Also

Adding a Discount Campaign Item

Targeting an Ad or Discount


Direct Mail

You create a direct mail campaign item to distribute e-mail message ads to a targeted group of users. The objective is to achieve a high response rate from the mailings. You can send personalized e-mail messages from a Web page, or non-personalized messages from a flat text file. You can create direct mail messages that include attachments, such as pictures, discounts, or URLs. The Direct Mail service is designed to send bulk personalized e-mail messages to millions of users.

To set up a direct mail campaign you use the Campaign Manager module in Business Desk. Direct mail campaign items are processed by the Direct Mailer service, a powerful engine that can send a large number of e-mails very quickly.

To create a direct mail campaign item, you perform the following steps:

  • Create the message. To create personalized e-mail messages your site developer must first create ASP pages with the personalized text, and then add them to the Web server. The site developer must give you the URL for the location of the ASP pages. To create a non-personalized message, you can type the text in the flat text file, for example, using Notepad.

  • Generate a list of recipients. You can generate a list of recipients for the direct mail campaign using the powerful analysis tools in Commerce Server. For example, using the Reports module in Business Desk, you can run a report against the data in the Data Warehouse to obtain a list of specific users. You can then export the resulting list to the List Manager. Or, you can use the Predictor resource to generate a list of users in a population segment, and then export that list of users to the List Manager. After a list has been exported to the List Manager, it is available to the Direct Mailer.

    You cannot use target groups to send direct mail directly to user e-mail addresses.

  • Create and schedule the direct mail campaign. Use the Campaign Manager module to specify the name of the campaign, the name of the list of recipients, the start time and date of the campaign item, and the URL (for personalized messages) or static file where Direct Mailer will receive the message body.

For more information about adding direct mail campaign items, see Adding a Direct Mail Campaign Item.

Opt Out Lists

Direct Mailer supports an opt-out feature. For direct mail jobs running as part of a campaign item, individual recipients can request to opt out of a direct mail campaign item. You can filter a mailing list against an opt-out list using an opt-out ASP page that is shipped as part of the Commerce Server Solution Sites.

The developer that authors the ASP page for the Direct Mailer jobs from the Web server can provide links to an opt-out.asp page, which the recipient can use to either opt out from the site or from the direct mail campaign item by clicking the appropriate link. When a Direct Mailer job running as part of a campaign item is executed, Direct Mailer checks for the presence of the site level opt-out list and the campaign item level opt-out list. If either list exists, they are subtracted from the original mailing list and the resulting list acts as the new mailing list.

Processing Direct Mail Campaign Items

Direct Mailer performs the following tasks:

  • Manages direct mail jobs.

  • Constructs personalized and non-personalized message bodies.

  • Formats e-mail message headers.

  • Sets the code-page value (language) and converts message bodies to the correct message type: MIME Encapsulation of Aggregate HTML Documents (MHTML), Multipurpose Internet Mail Extensions (MIME), or text.

  • Sends e-mail messages to recipients.

The Direct Mailer pipeline is used to process lists of recipients. You can add new components to the pipeline, integrate the components with line-of-business systems, or replace them with components supplied by third parties.

See Also

Adding a Direct Mail Campaign Item


User Lists and Mailing Lists

You use the List Manager module in Commerce Server Business Desk to import and export user lists and mailing lists in Business Desk.

  • Adding Lists to List Manager. You can export a Commerce Server Analysis report as a list to List Manager. You can import a list that you created using another application, such as SQL Server (to create a SQL table), Notepad (to create an ASCII text file), Microsoft Excel (to create a spreadsheet), or Microsoft Outlook (to export a .pst file which contains a list of addresses) into List Manager.

    For example, if you have a list of addresses in a Microsoft Excel spreadsheet, you can use List Manager to import it into Business Desk, and then use the list in a direct mail campaign. If you identify a list of users in an Analysis report, you can export the report results as a list to List Manager, and then use the list in a direct mail campaign.

    For information about importing a list into List Manager, see Importing and Exporting Lists. For information about exporting a Commerce Server Analysis report to List Manager, see Exporting a Static Report.

  • Using Lists from List Manager. You can import a user list from the List Manager module to the Users module, and then update the user profiles in the list. For example, you run the Commerce Server Customer Sales report to identify users who buy the most products, and then export the report as a list to the List Manager. You import the user list from List Manager into the Users module, and then update the user profiles in the list by assigning a special value a profile property in the user profiles. You use that value to target specific ads or discount campaigns to the users whose profiles you have modified. For information about importing a list into the Users module, see Importing a List of User Profiles. For information about modifying multiple user profiles, see Editing Multiple Users.

    You can also export the list to another application. For example, you can export a list generated from an Analysis report to a Microsoft Excel spreadsheet. For information about exporting a list to a file, see Importing and Exporting Lists.

Mailing Lists

Mailing lists contain rows of e-mail addresses for a direct mail campaign. Each row in the list represents a single recipient and contains the following elements in a comma-delimited format.

Element | Description
E-mail address | Name or name@domain.
GUID | Globally unique identifier. The user ID that will be used to provide content in a personalized mail message.
Message format | Controls the message format type that the Collaboration Data Object (CDO) translates the results into. For example, text, MIME Encapsulation of Aggregate HTML Documents (MHTML) or Multipurpose Internet Mail Extensions (MIME).
Language | The code-page value for the mail message.
URL | Provides the ability to pass individual URLs per user to CDO.

You can create a list using any text editor, such as Notepad. You can add a mailing list to Business Desk by using the List Manager module to import ASCII text files, files from Microsoft Excel or Microsoft Outlook, or tables from SQL Server databases. To create a mailing list by using information in a .pst file from Microsoft Outlook, see the topic "Export items to a file or to a personal folder file" in Microsoft Outlook Online Help.

For information about importing mailing lists for a direct mail campaign, see Importing a Mailing List.

User Lists

User lists contain rows of user IDs and optionally, other user profile properties. You can export user lists from the List Manager module to the Profile Designer module, and then perform bulk updates on the properties for the specific users.

For example, you can import a list from the Segment Viewer module and set a property in the user profile for each user to indicate their membership in a particular segment. You can then use this information to target ads and discounts to that specified user segment.

Generic Lists

Unlike user lists and mailing lists, generic lists do not have content requirements. To use generic lists, a site developer must customize your application.

Generic lists can contain anything, and they can include headers, as in the following example:

ProductID | ProductName | Unit
1 | Socks | 100
2 | Shirts | 20

You may want to use generic lists to set product properties. You run the Commerce Server Product Sales report to identify the most popular products (in terms of sales) on your Web site. You then use the List Manager module to import the result of this report as a list of products, and use the Catalog Editor module to set a property on these products that identifies them as strong sellers. You can then use this property to create target expressions, or to increase the price of these products by five percent.

Another way you can use generic lists is to mail coupons to your frequent online customers for use in your brick-and-mortar store. You can do this by running a report to analyze user purchases, exporting the results of the report as a list which includes the mailing addresses, and then using List Manager to export this list for use in a labeling application.

Dynamic Lists and Static Lists

User lists, mailing lists, and generic lists can be either dynamic or static.

  • Dynamic lists are created at run time; for example, when the list is being exported from List Manager for use in a direct mail campaign. Each time the list is requested, List Manager gathers the most recent data in the Data Warehouse. Only the information needed to create the list is stored in the database used by the List Manager. Use dynamic lists for direct mail campaigns that you will run frequently, or for lists of recipients that are updated frequently.

  • Static lists are created immediately upon request, and then stored in the database used by the List Manager. Use static lists for direct mail campaigns that you run infrequently, or for lists of recipients that do not change often.

See Also

Importing and Exporting Lists

Importing a List of User Profiles

Managing Lists of User Records

Creating a Mailing List


Targeting and Personalization

Targeting and personalization is the process of delivering personalized content to one or more users, or to any other business entity that has a profile. For example, if you are running a sports Web site, you may want to deliver tennis-related information only to tennis players, or to users who are interested in tennis. You may want to deliver announcements about upcoming tennis tournaments, or advertisements and promotions for tennis products.

You can use Commerce Server 2000 to perform two types of targeting:

  • Expression-based targeting. Also known as explicit targeting. This is used when you know the profile properties of the users to whom you are delivering content, or you know the context, and you know what content is to be delivered. You use the Campaigns modules in Commerce Server Business Desk to specify this information and deliver the content to the user.

  • Prediction. Also known as implicit targeting. This is used when you do not know all the necessary profile properties to target the user, or you do not have specific content to deliver. You use the Commerce Server Predictor resource to extrapolate this information from existing user data so that you can deliver content of interest to each user.

Both expression-based targeting and prediction improve your ability to deliver content that may be of interest to the users who receive it. Users are more likely to return to your site when they can expect to receive a personalized experience.

Using Targeting Methods in Web Site Management

Expression-based Targeting

The Expression Builder

Processing Expressions

Using Targeting Methods in Web Site Management

You can target content to any business-related item that has a profile. For example, you can target content to anonymous users, registered users, companies, or contexts. For conceptual information about profiles, see Profiles.

You use Business Desk to target content to business-related items. For example, you can do the following:

  • Create a direct mail campaign that delivers personalized messages to users.

  • Deliver content such as advertisements to users based on certain user profile properties. For example, you might display advertisements for bicycles to users who have their Favorite Sport property set to "Biking."

  • Identify groups of Web pages, and then target content to be displayed only on those pages, or only when users with specific properties access those pages.

  • Display content on a page based on the properties of other content on the page. For example, if your Web site provides news, you can assign profiles to the content specifying whether Weather_Type property is "Hot" or "Cold." If Weather_Type = Hot, you can display an advertisement for air conditioners.

  • Apply discounts to certain products in your catalog, based on characteristics of the product itself, or based on the user profile.

  • Choose when to display a discount and when the discount is to be applied to the order. For example, you can apply the discount when users put the item in their basket or when they check out.

Expression-based Targeting

Expression-based targeting is the process of creating expressions that define the users or context you want to target and the content you want to deliver. An expression is a condition that is evaluated against profiles to determine whether to deliver content, or perform another action. For example, an expression might be user.totalvisit > 100. If this expression evaluates to "True," then a specific piece of content is displayed to the user.

You use the Campaigns modules in Business Desk to create expressions, and then combine the expressions with the action you want to perform after the expression is evaluated. You can create two types of expressions:

  • Target expressions. Identify where, when, and to whom content should be displayed. For example, you can target content to users who have specific profile properties. You can also target content to specific sections of a Web site, called page groups. For example, you can create a target expression that will display certain ads only on sports pages.

  • Catalog expressions. Specify the products in a catalog that a discount can be applied to. For example, a catalog expression might be Product.price = 20.00. If this expression is "True," for a particular product, then a discount of 10 percent is applied to the price of that product when users add it to their shopping baskets.

After you have created target expressions, you can combine them to form a target group. A target group is a collection of expressions and actions. For example, you might create one expression to show a specific piece of content to users who have visited the site 10 times, and another expression to show content to users who have purchased a soccer shirt. You can combine the two expressions in a target group with AND or OR statements. For example:

If the user has visited the site 10 times AND the user has purchased a soccer shirt,

Display an advertisement for a soccer product.

In a target group you combine expressions by specifying the action to be taken when each expression evaluates to "True." Each action has two multipliers: a multiplier to apply if the expression is true, and a multiplier to apply if the expression is false. When the multiplier is applied, the expression is given a score, which affects whether the content is eligible for delivery. You can specify the following actions:

  • Target. If the expression evaluates to "True," the score is increased, as is the probability the content will be shown. If the expression evaluates to "False," the score is not changed. In both scenarios, the content is eligible for delivery.

  • Require. If the expression evaluates to "True," the content is eligible for delivery; if it is "False," the content is not eligible for delivery.

  • Exclude. If the expression evaluates to "True," the content is not eligible for delivery; if it is "False," the content is eligible for delivery.

  • Sponsor. If the expression evaluates to "True," the content is eligible for delivery and no other content is eligible unless it too has an expression with action = Sponsor. (Sponsor has only one multiplier.) For example, if Microsoft sponsors an advertisement on a home page, only Microsoft advertisements are displayed; however, if there are more advertisements from other companies sponsoring the home page, those advertisements would also be eligible for display.

A site developer can change the values of the multipliers provided with Commerce Server. You may want to do this to give expressions with one action type a higher priority than expressions with a different action type.

The Expression Builder

The Commerce Server feature that enables business managers to create, edit, and view expressions is called the Expression Builder. The Expression Builder provides the user interface for building expressions. It accesses the appropriate properties for building an expression, and it names and stores the expression in the Commerce Server databases.

The Expression Builder is designed so that site developers can easily embed its functionality and user interface in other Business Desk modules. In addition, it can be invoked by any Web application that uses and manipulates expressions, enabling you to integrate it with other processes. For example, if you have an existing content management process, you can incorporate Expression Builder functionality, and then target content to users.

To create applications that use the Expression Builder, you do the following:

  • Define profiles. You specify which profiles the expression should use, and the Expression Builder loads those profile definitions for constructing the expression. You can also specify a profile properties filter to limit the properties in the profile that will be available to an Expression Builder user.

  • Save expressions. You can specify the expression/profile store to use, and the Expression Builder loads and saves expressions in that database.

  • Display messages to users. You can customize the messages that are displayed in the Expression Builder user interface (UI). For example, the default title message is "Create an expression," but for your implementation, you might change it to "Create an Ad-Targeting Expression."

The Expression Builder uses Dynamic Hypertext Markup Language (DHTML for its UI, so the style sheets of the application will apply to the Expression Builder UI, giving your application a consistent look and feel.

Processing Expressions

Commerce Server performs several steps to specify the piece of content that is to be shown to a user. The following components are used in the process:

  • ExpressionEval. This Component Object Model (COM) object takes the expression and user data as input, and then processes the expression to determine whether it evaluates to "True" or "False."

  • Content Selection Framework (CSF). This platform-level framework includes a set of components and pipelines (the Content Selection Pipeline and the Event Processing Pipeline) that determines the action to be performed as a result of the expression.

The following figure illustrates how target expressions, catalog expressions, user data and context data are input into the Expression Evaluator, which results in True, False, or undefined results. The result is input to CSF, which then determines the action to perform.

A figure illustrating how Expression Evaluator and CSF process expressions
Target expression
Catalog expression
User data

Context data
Expression Evaluator
True, False, or undefined result
Content Selection Framework
Determines the action on this result

See Also

Profiles

Creating a Target Expression

Creating a Target Group


Campaign Effectiveness

The following table lists the reports included with Commerce Server that you use to analyze the effectiveness of a campaign item.

Report | Description
Campaign Item Summary | Review a summary of campaign activity on your site. This report displays information such as the number and percentage of clicks and the number of ad requests remaining.
Ad Reach and Frequency per Day | Analyze the behavior of daily unique users who interact with your campaign. Use this report to understand the interaction of daily unique users with your campaigns.
Ad Reach and Frequency per Campaign Item | Analyze the interaction of unique users with your campaign items. This report displays the behavior of unique users who interact with your campaign items for all time.
Ad Reach and Frequency per Campaign | Analyze the interaction of unique users with your campaigns. This report displays the behavior of unique users who interact with your campaign for all time.
Campaign Event Summary | Analyze the effectiveness of campaigns on your site. This report displays a summary of campaign activity on your site.
Ad Placement | Analyze where in your site ads are most effective. This report displays a summary of the activity of campaigns by location on your site.

See Also

Commerce Server Reports

Running Reports


Setting Up Your Reference Tables

By setting up your reference tables, you can accurately reflect your business model. The reference tables maintain valid advertising industry codes, page groups, and content sizes. If a page group used by a campaign item is not validated against the page groups in the reference table, the campaign item will not be put into production.

You can use the Reference Tables module to add industry codes, page groups, and content sizes in addition to those provided by Commerce Server 2000. You can also delete industry codes, page groups, and content sizes that you do not use.

Specifying Content Sizes

Adding Industry Codes

Adding Page Groups

Specifying Content Sizes

You can specify the size you want for your campaign item content. Commerce Server 2000 provides several default content sizes. These content sizes are taken from a list of commonly used sizes approved by the Standards and Practices Committee of the Internet Advertising Bureau (IAB). Content sizes are validated through the Content Size section in the Reference Tables module.

The content sizes in the reference tables are available when you select the size you want for your campaign item content. You can view, edit, and delete any of the predefined sizes, or you can create a new content size to fit your needs.

To specify a content size

  1. In Campaigns, click Reference Tables.

  2. In the Reference Tables screen, in the Content Sizes section, click New, and then do the following:
    Use this | To do this
    Tag Type the Tag name.

    A Tag is a parameter value to be passed into a content request on a page that specifies how the document, or a portion of the document should be formatted.
    Name | Type a name for the new content size.
    Width | Type the content size width (in pixels).
    Height | Type the content size height (in pixels).

  3. Click Accept.

    The new content size is added to the content size list. Content size items appear in the list in alphabetical order by the Tag attribute.

  4. To save the new content size and return to the Campaign Manager screen, click Save and go back on the toolbar.

The new content size is saved and is now available when you select content sizes for campaign items.

Adding Industry Codes

Industry codes provide a definition type for industries, for example, automotive, aviation, and beverage. You use industry codes to identify the associated industry of an ad, thus preventing two ads from competing companies in the same industry from appearing on the same page. You can also update industry codes; for example you can add beverage codes for coffee and soft drinks, so that ads for these different types of beverages can appear on the same page.

Commerce Server provides several popular industry codes for your use. The industry codes used in ads are validated through the Industry Codes section in the Reference Tables module. The industry codes in the reference tables are available when you select the industry code for an ad campaign item. You can view a list of all current industry codes, add new industry codes, edit industry codes, and delete industry codes from the Industry Code section in the Reference Tables module.

To create an industry code

  1. In Campaigns, click Reference Tables.

  2. In the Reference Tables screen, in the Industry Codes section, click New, and then do the following:
    Use this | To do this
    Industry Code | Type a name for the new industry code.

  3. Click Accept.

    The new industry code is added to the industry code list in alphabetical order.

  4. To save the new industry code and return to the Campaign Manager screen, click Save and go back on the toolbar.

The new industry code is saved and is available when you select industry codes for campaign items.

Adding Page Groups

You use page groups to specify the pages on which your ads appear on your Web site. Using page groups, you can place targeted ads on all pages of your commerce site, or only on one particular page. For example, a News site might have a Sports page group to which you would target sports-related ads. Additionally, you can charge advertisers different rates based on the page group on which they advertise. Page groups are validated using the Page Groups section in the Reference Tables module.

The page groups in the reference tables are available when you select the page you want a campaign item to appear on. Once the page group used by the campaign item is validated against the Page Group property, the campaign item can be put into production. You can view a list of all current page groups, add new page groups, edit page groups, and delete page groups from the Page Group section in the Reference Tables module.

Note

  • Before you can target an ad to a page group, your site developer must ad-enable the page. To ad-enable a page, see the Ad Sitelet sample in the Commerce Server 2000 Software Development Kit.

To add a page group

  1. In Campaigns, click Reference Tables.

  2. In the Reference Tables screen, in the Page Groups section, click New, and then do the following:
    Use this | To do this
    Page Group | Type a name for the new page group.
    Description | Type a description for the page group.

  3. Click Accept.

    The new page group is added to the Page Group list in alphabetical order.

  4. To save the new page group and return to the Campaign Manager screen, click Save and go back on the toolbar.

The new page group is saved and is available when you select page groups for your campaign items.

See Also

Reference Tables

Targeting an Ad to a Page Group


Creating a Campaign

You use the Campaigns modules to create a campaign item and send it to production. To create a campaign item, you first add the customer to Campaign Manager module. In Campaign Manager, you then create a campaign for your customer, for example, a brand awareness campaign. You schedule the campaign by campaign goaling. You can schedule the campaign using campaign level goaling or advertising item level goaling. After you have created a campaign, you can create one or more campaign items, and then specify your ad display. After you have defined the ad display, you can preview the ad before sending it to production.

The following figure illustrates a sample scenario for creating a campaign, adding a campaign item, and then sending the campaign item to production:

Workflow for creating a campaign item and sending it to production
Campaign Manager

Creating a Campaign Item

Adding Customer Information
Adding a Campaign
Previewing a Campaign Item

Publishing Campaign Changes on Your Web Site

Scheduling a Campaign
Publish Campaigns

  1. In the Campaign Manager module, add a new customer (such as Arbor Shoes).

  2. In the Campaign Manager module, add a new campaign (such as Fall Season sale).

  3. Schedule the campaign (for example, by campaign level goaling).

  4. Create an ad campaign item, (such as summer sandals).

  5. Preview the ad campaign item before you send it to production.

  6. In the Publish Campaigns module, update your site with the new advertisement.

This section contains:

  • Adding Customer Information

  • Adding a Campaign

  • Scheduling a Campaign

  • Creating a Campaign Item

  • Previewing a Campaign Item


Adding Customer Information

To create a campaign, you must first add information about the customer who owns the campaign. Each customer may have multiple campaigns representing a different marketing program. For example, a customer might have a fall season sale, a new product campaign, and a spring discount sale. Each campaign may have multiple campaign items such as ads, discounts or promotions, and direct mailings.

You can use the Campaign Manager module to add customers, modify customer properties, and delete customers.

To create a new customer

  1. In Campaigns, click Campaign Manager.

  2. In the Campaign Manager screen, click Add on the toolbar, and then select New Customer from the drop-down list.

  3. In the Campaign Manager - New (customer) screen, in the Customer Properties section, do the following:
    Use this | To do this
    Name | Type the name of the customer.
    Address | Type the address for the customer, including street address, city, state, zip code or postal code, and country.
    Type | Select the type of relationship you have with the company from the drop-down list.
    URL | Type the URL associated with the customer.
    Industry code Select the industry code for the customer.

    Industry codes are created using the Reference Tables module. For information, see Setting Up Your Reference Tables.

    Comments | Type any necessary comments about the customer.

  4. In the Contact Information section, do the following:
    Use this | To do this
    Contact | Type the contact information for the customer.
    Email | Type the e-mail address for the contact.
    Phone | Type the phone number for the contact.
    Fax | Type the fax number for the contact.

  5. To save the customer information and return to the Campaign Manager screen, click Save and go back on the toolbar.

The customer information is saved. You can now add a campaign for the customer.

See Also

Workflow for Campaign Management

About Campaigns

Adding a Campaign

Setting Up Your Reference Tables


Adding a Campaign

After you add customer information, you can add a campaign for the customer. Each customer can have multiple campaigns. For example, a customer might have both a brand awareness campaign and a customer loyalty campaign. You can use the Campaign Manager module to add the campaign, view campaign properties, copy the campaign to create a new campaign, edit the campaign properties, schedule the campaign by advertising item or campaign level goaling, locate a campaign, and delete and restore a campaign.

To add a new campaign

  1. In Campaigns, click Campaign Manager.

  2. In the Campaign Manager screen, select the customer for whom you want to create a new campaign, click Add on the toolbar, and then select New Campaign from the drop-down list.

  3. In the Campaign Manager <Customer> New (campaign) screen, in the Campaign Properties section, do the following:
    Use this | To do this
    Campaign name | Type the name of the new campaign.
    Start date | Select the campaign start date from the drop-down calendar.
    End date Select the campaign end date from the drop-down calendar.

    Campaign dates are used as default dates for campaign item dates. However, campaign item dates override campaign dates. A campaign item date may be set to extend past the dates for the campaign.
    Status | Select the campaign status from the drop-down list. The status can be either Active or Inactive.
    Comments | Type any necessary comments about the campaign.

The campaign properties are created. To schedule the campaign by advertising item or campaign level goaling, see Scheduling a Campaign.

See Also

Workflow for Campaign Management

About Campaigns

Adding Customer Information


Scheduling a Campaign

You schedule a campaign using campaign goaling. You can schedule at the campaign level or the advertising item level. When you create a new campaign goaled at the campaign level, you order the total number of requests for the entire campaign. For example, you perform goaling at the campaign level and your customer orders 25,000 ad requests. At the campaign item level, one ad is set up to display 60 percent of the ad requests, and the other ad is to display 40 percent of the ad requests. If the customer changes the number of ad requests, for example, to 40,000, you don’t have to manually change the number of times the ads are to display; they are still displayed at 60 percent and 40 percent. When you schedule at the ad level, you set the request goals for each individual ad. For more information about campaign goaling, see Campaign Goaling.

In a campaign, weight applies to ads that are goaled at the campaign level. For house, ads the weight is relative to all other house ads for all customers and all campaigns. For paid ads, the weight is relative to other paid ads in the same campaign.

You can schedule the campaign by either clicks or requests. When you schedule a campaign by clicks, the goals of the campaign are met when the user actually clicks on the ad. When you schedule the campaign by requests, the goals of the campaign are met when the ad is displayed on the specified page group.

To schedule the campaign

  1. In Campaigns, click Campaign Manager.

  2. In Campaign Manager, double-click the customer for whom you want to schedule a campaign, select the campaign, and then click Open on the toolbar.

  3. In the Campaign Manager <Customer Name> <Campaign Name> (campaign) screen, in the Advertising/Campaign Goaling section, do the following:
    Use this To do this
    Set goals by Select the goaling level from the drop-down list. You can goal the campaign at the Campaign level or the Advertising Items level.

    If you select Campaign level goaling, you can modify the Quantity ordered in the field below the Set goals by box. After ad campaign items have been added to the Campaign in the Campaign Manager, you can edit the dynamic table at the bottom of the Advertising/Campaign Goaling section. You select the advertising item in the table, and then click Edit to modify the weight of each ad. The quantities for each of the ads areredistributed based on the weights you enter.

    If you select Advertising Items level goaling, the quantity ordered field disappears. Quantities for campaigns goaled at the Advertising item level are entered in the ad campaign item. After ad campaign items have been added to the campaign in the Campaign Manager, you can edit the dynamic table at the bottom of the Advertising/Campaign Goaling section. You select the advertising item in the table, and then click Edit to modify the quantities of each ad.

    Notes

    • You can change the type of goaling from campaign level goaling to advertising item level goaling, and from advertising item level goaling to campaign level goaling.

    • This box is not required for discounts and direct mail campaign items.
    Quantity ordered Type the number of requests ordered for this campaign.

    This box is available only if you chose Campaign in the Set goals by box.
    Scheduled by Select Request or Click from the drop-down list.

    Request indicates that the goals of the campaign will be met when the ad is displayed on the specified page group(s).

    Click indicates that the goals of the campaign will be met when the user actually clicks on the ad.

  4. To save the schedule and return to the Campaign Manager screen, click Save and go back on the toolbar.

The campaign schedule is saved with the campaign. You can now create an ad campaign item for the campaign.

See Also

Workflow for Campaign Management

About Campaigns

Campaign Goaling

Adding a Campaign


Creating a Campaign Item

There are three types of campaign items: ads, discounts, and direct mail. To schedule the delivery of content, you need to create a campaign item. In addition to these three campaign items, your site developer can add related-sell functionality to your site, such as intelligent cross-sell and up-sell items.

Notes

  • For information about adding intelligent cross-sell functionality to your site, see Running the Predictor Resource and Prediction Objects.

  • For information about adding other related-sell functionality to your site, see the Commerce Server Software Development Kit.

For information about creating a campaign item, see the following:

  • Adding an Ad Campaign Item

  • Adding a Discount Campaign Item

  • Adding a Direct Mail Campaign Item


Previewing a Campaign Item

After the ad display is defined, you can preview the ad before you publish it on your Web site. You can also preview the Web page that appears when the user clicks on the ad if the ad is clickable.

To preview the ad

To display the Web page for the ad

To preview the ad

  1. In Campaigns, click Campaign Manager.

  2. In the Campaign Manager screen, select the ad campaign containing the ad you want to preview, and then click Open on the toolbar.

  3. In the Campaign Manager <Customer> <Campaign> <Campaign item> (ad ID: <number>) screen, in the Ad Display section, verify the information is entered in the required fields, and then click Preview.

  4. In the Preview dialog box, click Yes to save the ad campaign item.

A copy of your ad appears in the display area below the Preview button.

For information about setting up the ad type in the Ad Display section, see Setting Up an Ad Type.

To display the Web page for the ad

  1. In Campaigns, click Campaign Manager.

  2. In the Campaign Manager screen, select the ad campaign item that you want to preview, and then click Open on the toolbar.

  3. In the Campaign Manager <Customer> <Campaign> <Campaign item> (ad ID: <number>) screen, in the Ad Display section, verify the information is entered in the required fields, and then click the ad in the display area below the Preview button.

The Web page associated with the ad appears in a new Internet Explorer window. For information about publishing the ad on your Web site, see Publishing Campaign Changes on Your Web Site.

See Also

Adding an Ad Campaign Item

Sizing an Ad

Setting Up an Ad Type

Publishing Campaign Changes on Your Web Site


Publishing Campaign Changes on Your Web Site

You use the Publish Campaigns module to update your site immediately with new information that you have added to your Web site. However, even if you do not perform this step to publish your ad campaign changes, by default, within five minutes your Web site will reflect any changes you made regarding the ad campaign. Changes to discount campaign items are not updated on the Web site unless you publish them using the Publish Campaigns module.

In most e-commerce businesses, changes are first made to a test site, and then at a scheduled times the changes are published to the production site. Contact your system administrator for information about when and how changes are made to your production site.

The Publish Campaigns module contains a search mechanism that enables you to find the ads or discounts you want to view, publish, or delete.

Note

  • Before you update an ad campaign on a new site, you must first visit the Web site if a user has never visited it. Each server in the Web farm must be updated before a campaign item can be sent to production.

To search for a production item

To publish a campaign item

To search for a production item

  1. In Campaigns, click Publish Campaigns.

  2. In the Publish Campaigns screen, click Find on the toolbar.

  3. In the Find pane, in the Look For box, select the type of campaign item you are searching for from the drop-down list, and then click Find Now.

The campaign items matching the search criteria appear in the Production Items box.

To publish a campaign item

  1. In Campaigns, click Publish Campaigns.

  2. In the Publish Campaigns screen, select the production item you want to publish, and then click Publish on the toolbar.

The campaign item is sent to production. The site is updated to include the new ad campaign.

See Also

Adding an Ad Campaign Item

Previewing a Campaign Item


Changing Between Campaign Goaling and Advertising Item Goaling

Campaigns are scheduled using campaign goaling. You can schedule at the campaign level or advertising item level. In a campaign, weight applies to ads that are goaled at the campaign level. For house ads the weight is relative to all other house ads for all customers and all campaigns. For paid ads, the weight is relative to other paid ads in the same campaign. After you schedule a campaign, you can change between campaign goaling and advertising item goaling, which determines how the weights for the ads will be calculated.

The following describes three scenarios for goaling paid ads. In the first scenario, the customer orders two ads goaled at the campaign level. In the second scenario, the customer wants to add requests for the first of the two ads, and so switches to advertising item goaling. In the third scenario, the customer wants the first ad displayed at a three-to-one rate over the second, and so switches back to campaign-level goaling.

  • Scenario 1: A customer orders two paid ads for their fall season sale to be run in even proportion for a total quantity ordered of 1000 requests. The quantity ordered for each ad is 500. The campaign is goaled at the campaign level.
    Campaign goaling - equal weight

    Click the illustration to enlarge or reduce.

  • Scenario 2: The customer now wants 500 additional requests for the first ad. The campaign is changed to advertising item level goaling, and 500 additional requests are added to the quantity ordered for the first ad for a total of 1000 requests. The second ad remains at 500 requests.
    Advertising Item Goaling

    Click the illustration to enlarge or reduce.

  • Scenario 3: The customer decides to redistribute the order so that the first ad is run at a weight of 3 to 1 against the second ad. The campaign is changed back to campaign level goaling with a total quantity ordered of 1500. After the ad campaign item weights are changed to 3 and 1 (for the first and second ads, respectively), the new paid weights for the campaign are 1125 for the first ad and 375 for the second.
    Campaign goaling - 3:1 weight

    Click the illustration to enlarge or reduce.

Caution

  • In the second scenario, if the customer decides to redistribute the order, and then also adds a third ad with a weight of 1, all of the ads must be reweighted. Because the ad has been changed from an ad-goaled campaign to a campaign-goaled campaign, the paid weight of all the ads must be changed or the delivery of the ads will be skewed.


Adding an Ad Campaign Item

You create ad campaign items to schedule delivery of your ads. An ad campaign item typically has a delivery goal, date ranges and target attributes. After you create the ad campaign, you can schedule the ad, specify the Web pages where the ad is to appear, and target the ad at a specified group of users. You can also specify your ad display. For example, may want an ad that contains text and an image or you may want an ad that is text only. After you specifiy the appearance of the ad, you can preview the actual ad display.

This section contains:

  • Creating an Ad Campaign Item

  • Scheduling an Ad Campaign Item

  • Targeting an Ad to a Page Group

  • Targeting an Ad to a Group of Users

  • Specifying the Ad Display

  • Copying an Ad Campaign Item


Creating an Ad Campaign Item

You use the Campaign Manager module to create an ad campaign item for a specific campaign. You select the type of ad, which can be either a paid ad or a house ad depending on the Need of Delivery (NOD) schedule. You can also set a limit on how many times you want to show a user a piece of content within a user session. To prevent two ads from competing companies in the same industry from appearing on the same page, you can select an industry code for the ad.

To create an ad campaign item

To set up the ad display

To create an ad campaign item

  1. In Campaigns, click Campaign Manager.

  2. In the Campaign Manager screen, select the campaign for which you want to create a new ad campaign, click Add on the toolbar, and then select New Ad from the drop-down list to create the new ad.

  3. In the Campaign Manager <Customer> <Campaign> New (ad) screen, in the Ad Properties screen, do the following:
    Use this | To do this
    Ad name Type the name for the ad.

    To help distinguish between house ads and paid ads, use a distinct naming convention for the two types of ads. For example, Business Books_HA for a house ad and Business Software_PA for a paid ad.
    Status Select the ad campaign status from the drop-down list.

    The status can be either Active or Inactive.
    Type Select the type of ad you want.

    The type can be either Paid Ad or House Ad.
    Request or Click/Weight If your campaign is goaled at the campaign level, select Weight for either the House Ad or Paid Ad type.

    If your campaign is goaled at the advertising item level by requests, do the following:

    • If you selected Paid Ad as the ad type, type the number of ad request goals for the ad.

    • If you selected House Ad as the ad type, type the value for the weight of the house ad. House ads have a default weight of 1.

    If your campaign is goaled at the advertising item level by clicks, do the following:

    • If you selected Paid Ad as the ad type, type the number of ad click goals for the ad.

    • If you selected House Ad as the ad type, type the value for the weight of the house ad. House ads have a default weight of 1.
    Exposure limit Select the number of times the ad can be shown to a user within a session from the drop-down list.

    The maximum number of times the ad can be shown to a user is ten times within one session.
    Date received This box contains the current date as the default. Type or select the date the ad will be received from the drop-down calendar.

    After the ad campaign item is saved, the date cannot be changed.

    Industry | Select the industry code for the ad.
    Comments | Type any necessary comments pertaining to this ad.

Note

  • Before you can save the ad campaign item, you must set up the ad display.

To set up the ad display

  1. In the Ad Display section, do the following:
    Use this | To do this
    Size | Select the content size of the ad from the drop-down list.
    Type | Select the ad type from the drop-down list.

    Note

    • Different boxes appear below the Content Type box depending on the type of ad you select. You must enter the required information in the Ad Display section before you can save the ad campaign item. For more information about setting up your ad campaign display for a specific type of ad, see Setting Up an Ad Type.
  2. To save the ad and return to the Campaign Manager screen, click Save and go back on the toolbar.

The new ad appears in the Campaign Manager tree under the specified customer and campaign.

See Also

Adding a Campaign

Adding Industry Codes

Specifying Content Sizes

Specifying the Ad Display

Scheduling an Ad Campaign Item

Targeting an Ad to a Page Group

Targeting an Ad to a Group of Users


Scheduling an Ad Campaign Item

After you have created a new ad campaign item, you can select the start and end dates for running the ad. While the ad is running, you can change the end date, for example, you can add or subtract a day. The Need of Delivery (NOD) is then recalculated based on the remaining quantity and remaining time in the schedule.

To schedule an ad campaign item

  1. In Campaigns, click Campaign Manager.

  2. In the Campaign Manager screen, select the ad you want to schedule and click Open on the toolbar.

  3. In the Campaign Manager <Customer> <Campaign> <Ad Campaign Item>(ad ID: <number>) screen, in the Ad Schedule section, do the following:
    Use this | To do this
    Start date | Type or select from the drop-down calendar the date the ad is to start.
    End date | Type or select from the drop-down calendar the date the ad is to end.
    Days | Check each day of the week that you want the ad to run.
    Start time | Type or select from the drop-down list the time of day the ad is to start based on the server time.
    End time | Type or select from the drop-down list the time of day the ad is to end based on the server time.

    Notes

    • If you set the start time after the end time, the ad will start at the later time and run to the end time. For example, if the start time is set at 11:00, and the end time is set at 9:00, the ad will run for 22 hours.

    • If you set the start and end times as the same time, the ad will display over the entire 24 hours.
  4. To save the ad and return to the Campaign Manager screen, click Save and go back on the toolbar.

The schedule is saved with the ad.

See Also

Scheduling a Campaign

Adding an Ad Campaign Item


Targeting an Ad to a Page Group

You can specify that an ad campaign item will appear on all pages of the site or that it will appear only on assigned page groups. Page groups allow you to specify on what Web pages an ad campaign item will appear. For example, if your Web site is an online newspaper, you may want to assign an ad for golf clubs to only run on pages in the Sports page.

You can display ads on all of your page groups, or you can select from available page groups that have been created in the Page Groups section in the Reference Tables module.

Note

  • Before you can target an ad to a page group, your site developer must ad-enable the page. To ad-enable a page, see the Ad Sitelet sample in the Commerce Server 2000 Software Development Kit.

To target an ad to a page group

  1. In Campaigns, click Campaign Manager.

  2. In the Campaign Manager screen, select the ad for which you want to create a new page group, and then click Open on the toolbar.

  3. In the Campaign Manager <Customer> <Campaign> <Ad Campaign Item>(ad ID: <number>) screen, in the Ad Target section, do the following:
    Use this | To do this
    Show on all Page Groups Select this check box to display the ad on all page groups of the Web site.

    To assign the ad campaign to a specific page group, clear the check box, and follow the remaining steps in this procedure.
    Page groups: Available | Select the page group(s) you want to assign.

  4. Click Add.

The selected page is moved to the Assigned box.

  5. To save the ad and return to the Campaign Manager screen, click Save and go back on the toolbar.

The ad will now appear on the targeted page groups.

See Also

Adding an Ad Campaign Item

Adding Page Groups


Targeting an Ad to a Group of Users

Target groups are expressions associated with an action used to target an ad to a specific group of users. You can have multiple expressions and actions in one target group. You can create target groups to include specified users in a group, or exclude specified users from a group. You select the group of users you want to target from an existing list of groups, which you create using the Target Group module. For information about creating target groups, see Creating a Target Group.

To target an ad to a group of users

  1. In Campaigns, click Campaign Manager.

  2. In the Campaign Manager screen, select the ad for which you want to assign a new target group and click Open on the toolbar.

  3. In the Campaign Manager <Customer> <Campaign> <Ad Campaign Item>(ad ID: <number>) screen, in the Ad Target section, do the following:
    Use this | To do this
    Target groups: Available | Select the target group you want to assign.

  4. Click Add.

The target group is moved to the Assigned box.

  5. To save the ad and return to the Campaign Manager screen, click Save and go back on the toolbar.

The ad will now be targeted to the selected target group.

See Also

Adding an Ad Campaign Item

Creating a Target Expression

Creating a Target Group


Specifying the Ad Display

You perform two main steps to display an ad. These steps are:

  • Sizing an Ad

  • Setting Up an Ad Type

Sizing an Ad

Commerce Server 2000 includes a set of standard content sizes that you can apply to your ads. In addition, you can specify your own custom content sizes. Whether you want to apply a standard size or a custom size, use the following procedure to apply the size to an ad.

Note

  • To specify custom content sizes, use the Reference Tables module. For information, see Specifying Content Sizes.

To size an ad

  1. In Campaigns, click Campaign Manager.

  2. In the Campaign Manager screen, select the ad campaign containing the ad you want to size, and then click Open on the toolbar.

  3. In the Campaign Manager <Customer> <Campaign> <Ad Campaign Item>(ad ID: <number>) screen, in the Ad Display section, do the following:
    Use this | To do this
    Size | Select the ad size from the drop-down list.

You have specified the content size for the ad. You can now set up the ad type.

Setting Up an Ad Type

You may require a specific type of ad for your ad campaign. For example, you may want an ad that contains an image or you may want an ad that is text only.

To set up an ad type

To set up an image ad

To set up a text ad

To set up an HTML ad

To set up a non-clickable image ad

To set up a buy now ad

To set up a Windows Media Services ad

To set up a directional vignette ad

To set up an ad type

  • In the Campaign Manager <Customer> <Campaign> <Ad Campaign Item>(ad ID: <number>) screen, in the Ad Display section, in the Type box, select the type of ad you want from the drop-down list.

    Note

    • Different boxes appear below the Type box depending on the type of ad you select. For more information about setting up your ad campaign display for a specific type of ad, see the remaining procedures in the "Specifying the Ad Display" section.

To set up an image ad

You link an ad image to the designated Web page(s) on which the ad is scheduled to appear. Users see the image when they visit the Web pages where the ad is displayed.

  1. In the Campaign Manager <Customer> <Campaign> <Ad Campaign Item>(ad ID: <number>) screen, in the Ad Display section, do the following:
    Use this | To do this
    Size | Select the size of the ad you want.
    Type | Select Image.
    Image URL | Type the URL for the image that you want displayed in the ad.
    Click URL | Type the URL to which the displayed ad links.
    Alternate text | Type the alternate text that users see when graphics are not enabled on their computer.

  2. To save the ad and remain on the Campaign Manager <Customer> <Campaign> <Ad Campaign Item>(ad ID: <number>) screen, click Save on the toolbar.

The ad is set up as an image ad and is saved with the campaign item.

To set up a text ad

A text ad is composed of text only. Users see the text when they visit the Web pages where the ad is displayed.

  1. In the Campaign Manager <Customer> <Campaign> <Ad Campaign Item>(ad ID: <number>) screen, in the Ad Display section, do the following:
    Use this | To do this
    Size | Select the size of the ad you want.
    Type | Select Text.
    Text | Type the text that is to be displayed with the ad.
    Click URL | Type the URL to which the displayed ad links.

  2. To save the ad and remain on the Campaign Manager <Customer> <Campaign> <Ad Campaign Item>(ad ID: <number>) screen, click Save on the toolbar.

The ad is set up as a text ad and is saved with the campaign item.

To set up an HTML ad

An HTML ad is composed of HTML code. Users see the resulting text when they visit the Web pages where the ad is displayed.

  1. In the Campaign Manager <Customer> <Campaign> <Ad Campaign Item>(ad ID: <number>) screen, in the Ad Display section, do the following:
    Use this | To do this
    Size | Select the size of the ad you want.
    Type | Select HTML.
    HTML Text | Type the HTML text (in HTML format) that is to be displayed in the ad.

  2. To save the ad and remain on the Campaign Manager <Customer> <Campaign> <Ad Campaign Item>(ad ID: <number>) screen, click Save on the toolbar.

The ad is set up as HTML ad and is saved with the campaign item.

To set up a non-clickable image ad

A non-clickable image ad is a graphical image that users see when they visit the Web pages where the ad is scheduled to appear. The ad is not linked to a Web page.

  1. In the Campaign Manager <Customer> <Campaign> <Ad Campaign Item>(ad ID: <number>) screen, in the Ad Display section, do the following:
    Use this | To do this
    Size | Select the size of the ad you want.
    Type | Select Non-Clickable Image.
    Image URL | Type the URL for the image that you want displayed in the ad.
    Alternate Text | Type the alternate text that users see when graphics are not enabled on their computer.

  2. To save the ad and remain on the Campaign Manager <Customer> <Campaign> <Ad Campaign Item>(ad ID: <number>) screen, click Save on the toolbar.

The ad is set up as a non-clickable image ad, and is saved with the campaign item.

To set up a buy now ad

Buy Now ads enable users to purchase goods from any Web page on the Internet. When a user clicks a product image, a dialog box appears prompting the user for shipping address and credit card information.

  1. In the Campaign Manager <Customer> <Campaign> <Ad Campaign Item>(ad ID: <number>) screen, in the Ad Display section, do the following:
    Use this | To do this
    Size | Select the size of the ad you want.
    Type | Select Buy Now.
    Image URL | Type the URL for the image that is to be displayed in the ad.
    Click URL | Type the URL to which the displayed ad links.
    Alternate Text | Type the alternate text that the user sees if graphics are not enabled on their computer.
    Window Width | Enter the width of the ad in pixels.
    Window Height | Enter the height of the ad in pixels.

  2. To save the ad and remain on the Campaign Manager <Customer> <Campaign> <Ad Campaign Item>(ad ID: <number>) screen, click Save on the toolbar.

The ad is set up as a buy now ad, and is saved with the campaign item.

To set up a Windows Media Services ad

A Windows Media Services ad displays high quality audio and video advertisements.

  1. In the Campaign Manager <Customer> <Campaign> <Ad Campaign Item>(ad ID: <number>) screen, in the Ad Display section, do the following:
    Use this | To do this
    Size | Select the size of the ad you want.
    Type | Select Windows Media Services.
    Windows Media Services Advanced Streaming Format (ASF) | Type the Windows Media Services ASF for the ad.
    Click URL | Type the URL to which the displayed ad links.

  2. To save the ad and remain on the Campaign Manager <Customer> <Campaign> <Ad Campaign Item>(ad ID: <number>) screen, click Save on the toolbar.

The ad is set up as a Windows Media Services ad, and is saved with the campaign item.

To set up a directional vignette ad

A vignette ad is composed of text that is displayed adjacent to the image where the ad is displayed.

  1. In the Campaign Manager <Customer> <Campaign> <Ad Campaign Item>(ad ID: <number>) screen, in the Ad Display section, do the following:
    Use this | To do this
    Size | Select the size of the ad you want.
    Type Select Left, Right, or Top Vignette.

    Left - places the ad to the left of the text

    Right - places the ad to the right of the text

    Top - places the ad above the text
    Image URL | Type the URL for the image that is to be displayed in the ad.
    Text | Type the text that is to be displayed adjacent to the ad.
    Click URL | Type the URL to which the displayed ad links.
    Alternate Text | Type the alternate text that users see if graphics are not enabled on their computer.

  2. To save the ad and remain on the Campaign Manager <Customer> <Campaign> <Ad Campaign Item>(ad ID: <number>) screen, click Save on the toolbar.

The ad is set up as a directional vignette ad, and is saved with the campaign item.

See Also

Adding an Ad Campaign Item

Specifying Content Sizes

Previewing a Campaign Item

Publishing Campaign Changes on Your Web Site


Copying an Ad Campaign Item

You can copy an existing ad campaign item that has already been created to quickly add additional ad campaign items for a customer and its campaign. Using an existing ad as a template, you can change the properties of the existing ad to meet the new ad campaign item goals.

To copy an ad

  1. In Campaigns, click Campaign Manager.

  2. In the Campaign Manager screen, select the ad you want to copy, and then click Copy on the toolbar.

  3. In the Copy Ad item dialog box, do the following:
    Use this | To do this
    Select a customer | Select the customer from the drop-down list from which you want to copy the ad.
    Select a campaign | Select the campaign from the drop-down list from which you want to copy the ad.

  4. Click OK.

  5. In the Campaign Manager <Customer> <Campaign> New (Ad) screen, in the Ad Properties section, do the following:
    Use this | To do this
    Ad name | Type the name of the new ad.

  6. Edit the remaining properties as necessary.

  7. To save the ad and return to the Campaign Manager screen, click Save and go back on the toolbar.

The new ad appears in the Campaign Manager tree under the selected customer and campaign.

See Also

Adding an Ad Campaign Item


Adding a Discount Campaign Item

You can create discount campaign items and apply them to any item in your catalog. In the Campaign Manager module you can create new discount items, schedule when discounts are to appear on the site, determine to what products, page groups, or target groups the discount applies, and specify how the discount is to be displayed. You can also preview how the discount item will appear on the designated Web site or page group.

This section contains:

  • Creating a Discount Campaign Item

  • Previewing the Discount Display

  • Copying a Discount Campaign Item


Creating a Discount Campaign Item

After you create a campaign, you can create a discount campaign item. You can apply discounts to any item or category in your catalog. For example, you can apply a 20 percent discount to a Keyboard category in a Hardware catalog. When you create a discount campaign item, you specify how and in what form the discount is to appear to the user.

You use target expressions to target the discount to specific users. For example, you can award preferred shoppers a ten percent discount on the first two items in their shopping basket. You can also specify how many times a particular discount is shown to a user within a session. After you specify the discount display, you can preview the display before saving it in Campaign Manager.

Adding Discount Campaign Properties

Specifying the Discount Conditions, Awards, and Eligibility Requirements

Targeting a Discount to a Page Group

Specifying the Discount Campaign Display

Adding Discount Campaign Properties

You can prioritize the order in which discounts are applied when multiple discounts are created, and specify the start and end dates of the discount campaign item.

To add discount campaign properties

  1. In Campaigns, click Campaign Manager.

  2. In the Campaign Manager screen, select the campaign for which you want to create a new discount campaign item, click Add on the toolbar, and then select New Discount from the drop-down list.

  3. In the Campaign Manager <Customer Name> <Campaign Name> - New (discount) screen, in the Discount Properties section, do the following:
    Use this | To do this
    Discount name | Type the name for the discount campaign item.
    Status Select the discount campaign status from the drop-down list.

    The status can be either Active or Inactive.

    Priority Select the priority of the discount campaign from the drop-down list.

    The priority of the discount determines which discounts are applicable in the basket. For example, a discount with a priority of 10 is applied over a discount with a priority of 20.

    Comments | Type any comments that are pertinent to this discount campaign.
    Start date | Type or select the discount campaign item start date from the drop-down calendar.
    End date | Type or select the discount campaign end date from the drop-down calendar.

Note

  • Before you can save the discount campaign item, you must set up the discount display. For information about setting up the discount display, see Specifying the Discount Campaign Display.

Specifying the Discount Conditions, Awards, and Eligibility Requirements

You identify the product or category in the catalog to which you want to apply the discount, and state the amount of the discount (either in a dollar value or unit value). You specify the user(s) that will receive the discount and the number of items a user must purchase before the discount applies. You also specify the award (for example, a percentage off the price of the product, a free product, or free shipping) the user receives if they receive this discount. For example, you can award users over the age of 40 a 20 percent discount off a Jazz CD, if they buy 3 items from the CD category in your catalog.

Sample scenarios

To specify the discount definition

Example: Setting up a discount condition, award, and eligibility requirements

Sample scenarios

The following scenarios show a variety of awards offered, and the eligibility requirements for each award.

  • Scenario 1: If a user buys more than $100.00 of any product, they receive free shipping.
    Discounts - free shipping

    Click the illustration to enlarge or reduce.

  • Scenario 2: If a user buys any product in the catalog, they receive ten percent off any brand of blue jeans.
    Discounts - 10 percent off jeans

    Click the illustration to enlarge or reduce.

  • Scenario 3: A preferred shopper receives ten percent off the first two items in their basket.
    Discounts - perferred shoppers

    Click the illustration to enlarge or reduce.

  • Scenario 4: If users click on the discount image, they receive $5.00 off the price of any set of bath towels.
    Discounts - $5.00 off bath towels

    Click the illustration to enlarge or reduce.

  • Scenario 5: Users over the age of 40 who buy three items from the CD category receive an award of 50 percent off the price of a Jazz CD.
    Discounts - 50 percent off jazz cd

    Click the illustration to enlarge or reduce.

To specify the discount definition

To specify the discount definition, you set up the conditions of the discount, the award, and the eligibility requirements. For an example of a discount definition, see Example: Setting up the discount condition, award, and eligibility requirements.

  • In the Campaign Manager <Customer Name> <Campaign Name> - New (discount) screen, in the Discount Definition section, do the following:
    Use this | To do this
    Buy: Anything Select this check box if the discount will be applied to any product.

    Leave this check box unchecked if the discount is to be applied to specific products or categories, and then follow the remaining steps outlined in this procedure.

    Buy:
    • First box. Select Value or Quantity from the drop-down list.

    • Second box. Enter the dollar value or unit value of the discount, depending on the measure you selected in the Buy: (first box) for the discount.

    • Third box. Select the option that pertains to this discount from the drop-down list. Values for this box are [any product], [Product Picker] and [Expression Builder].

      [any product] Select this option if the discount pertains to any product.

      [Product Picker…] Select this option if the discount pertains to a specific product or category in your catalog. Use the Product Picker dialog box find specific products or categories in your catalogs. For information about how to use the Product Picker, see New from Product Picker.

      -Or-

      Click the ellipsis […] button or select the [Expression Builder] option to open the Catalog Expressions dialog box. You can create a catalog expression to specify which categories or products you want to apply a discount to. For information about building catalog expressions, see Creating a Catalog Expression.

      Note

      • Additional products and categories appear in the drop down list if they have been previously selected.
    Get: Free Shipping Select this check box to provide free shipping as a discount award to all products ordered.

    Leave the Free Shipping check box unchecked to specify the products or categories that will receive discount awards, and then follow the remaining steps outlined in this procedure.

    Get
    • First Box. Type the number of units that the user is awarded when the rules of the discount are met.

      Second Box. Select the option that pertains to this discount from the drop-down list. Values for this box are [any product], [Product Picker…], and [Expression Builder].

      [Any product] Select this option if the discount award pertains to any product.

      [Product Picker…] Select this option if the award pertains to a specific product or category in your catalog. The Product Picker dialog box provides an interface you use to find specific products or categories in your catalogs. For information about how to use the Product Picker, see New from Product Picker.

      -Or-

      Click the Ellipse button […] or select the [Expression Builder] option to open the Catalog Expressions dialog box. You can create a catalog expression to specify which categories or products you want to apply the award to. For information about building catalog expressions, see Creating a Catalog Expression.

      Note

      • Additional products and categories appear in the drop down list if they have been previously selected.
    • Third Box. Select the measure for the discount award from the drop-down list.

    • Fourth Box. Enter the dollar value or unit value of the discount award, either by price or percent depending on the measure you selected for the discount award.
    Limit | Select a discount limit from the drop-down list. A limit of None indicates no limit for the discount. There is a maximum discount of 10 awards per user.
    Apply offer on Get product alone Select this option to apply the discount only to the award.

    For example, if a user buys two pairs of shoes (including a pair of tennis shoes), and they receive a discount of 20 percent off a pair of tennis shoes, the 20 percent off will only apply to the tennis shoes they are receiving as an award.

    Apply offer on both Get and Buy Products Select this option to apply the discount to both the qualifying product and the award.

    For example, if a user buys two pairs of shoes (including a pair of tennis shoes), and they receive a discount of 20 percent off a pair of tennis shoes, the 20 percent off will only apply to both pairs of tennis shoes.

    Discount is click required. Only apply discount when discount ad is clicked Select this check box to have the discount apply only when the customer actually clicks on the discount.

    If you do not want the discount to be click-required, leave this box unchecked.

    Eligibility Requirements: Expression Available Select the expression(s) for the discount from the list of available expressions, and then click Add.

    For information about creating target expressions, see Creating a Target Expression.

The condition, award, and eligibility requirements are specified for the discount campaign item.

Note

  • Before you can save the discount campaign item, you must set up the discount display. For information about setting up the discount display, see Specifying the Discount Campaign Display.

Example: Setting up the discount condition, award, and eligibility requirements

The following example shows how to set up a discount that targets users over the age of 40 who buy three items from a category in the catalog, and receive an award of 50 percent off a catalog item.

  • In the Campaign Manager <Customer Name> <Campaign Name> - New (discount) screen, in the Discount Definition section, do the following:
    Use this | To do this
    Buy: Anything | Verify that this check box is unchecked to apply specific products or categories to the discount, and then follow the remaining steps in this procedure.
    Buy:
    • First box. Select Quantity from the drop-down list.

      In the Product Picker dialog box, select the catalog you want to use from the drop-down list. In the Categories box select the category you want the discount to apply to, and then click OK.

    • Second box. Enter 3 for as the quantity to be purchased.

    • Third box. Select [Product Picker] from the drop-down list.
    Get: Free Shipping | Verify that this check box is unchecked to specify the products or categories that will receive discount awards, and then follow the remaining steps in this procedure.
    Get
    • First Box. Type 1 as the number of units that the user is awarded when the rules of the discount are met.

      Second Box. Select [Product Picker…] from the drop-down list.

      In the Product Picker dialog box, select the catalog you want to use from the drop-down list. In the Categories box select the category you want the discount award to apply to. In the Products in category box, select the product you want the discount award to apply to, and then click OK.

      • Third Box. Select Percent (%) from the drop-down list.

      • Fourth Box. Enter 50 as the dollar value of the discount award.
    Limit | Verify None is selected as the limit, which indicates no limit for the discount.
    Apply offer on Get product alone | Select this option to apply the discount only to the award.
    Discount is click required. Only apply discount when discount ad is clicked | Select this check box to have the discount apply only when the customer actually clicks on the discount.
    Eligibility Requirements: Expression Available Select the expression(s) for the discount from the list of available expressions, and then click Add.

    For example, a target expression can be created targeting users over the age of 40.

An award of 50 percent off the specified catalog item price will be awarded to all users over the age of 40 who buy three products from the specified catalog category.

Targeting a Discount to a Page Group

You can specify if a discount campaign item is to appear on all pages of the site or if it is to appear only on assigned page groups. You use page groups to specify on which Web pages a discount campaign item will appear. For example, if your Web site is an online newspaper, you can assign a discount for golf clubs to only run on the Sports page.

You can display your discount items on all of your page groups, or you can select from the page groups that have been created in the Page Groups section in the Reference Tables module.

Note

  • Before you can target an ad to a page group, your site developer must ad-enable the page. To ad-enable a page, see the Ad Sitelet sample in the Commerce Server 2000 Software Development Kit.

You can also specify the target groups that the discount will apply to. Target groups are a collection of two or more expressions used to target a specific group of users. You can use target groups to include specified users in a group, or to exclude specified users from a group. For information about creating target groups, see Creating a Target Group.

To target a discount to a page group

  1. In Campaigns, click Campaign Manager, select the discount for which you want to specify the discount target, and then click Open on the toolbar.

  2. In the Campaign Manager <Customer> <Campaign> <Campaign Discount Item> (discount ID: <number>) screen, in the Discount Display Target section, do the following:
    Use this To do this
    Use these targets in addition to selected eligible targets Select this option if you want to use a page group(s) and/or a target group(s) in addition to the selected eligible targets, which are selected in the Discount Definition screen.

    For information about page groups, see Adding Page Groups. For information about target groups, see Creating a Target Group.

    Use these targets instead of selected eligible targets Select this option if you want to use a page group(s) and/or a target group(s) instead of the selected eligible targets, which are selected in the Discount Definition screen.

    For information about page groups, see Adding Page Groups. For information about target groups, see Creating a Target Group

    Show on all Page Groups Select this check box to display the ad on all page groups of the Web site.

    To assign the discount campaign item to a specific page group, clear the check box, and follow the remaining steps in this procedure.

    Page groups: Available Select the page group(s) you want to assign, and then click Add.

    The page group is moved to the Assigned box. To remove a page group from the Assigned box, click Remove. This moves the page group to the Available box.

    Target groups: Available Select the target group(s) this discount applies to, and then click Add.

    The target group is moved to the Assigned box. To remove a target group from the Assigned box, click Remove. This moves the target group to the Available box.

    For information about creating target expressions, see Creating a Target Expressions.

The selected page group(s) and discount campaign target information is specified for the discount campaign item.

Note

  • Before you can save the discount campaign item, you must set up the discount display. For information about setting up the discount display, see Specifying the Discount Campaign Display.

Specifying the Discount Campaign Display

You can specify how and in what form a discount appears to the user. For example, you can display a large ad on your home page promoting 20 percent off all products in your catalog. You can also specify how many times a particular discount is to appear to a user within a session.

To specify the discount campaign display

  1. In Campaigns, click Campaign Manager, select the discount for which you want to specify the discount campaign display, and then click Open on the toolbar.

  2. In the Campaign Manager <Customer> <Campaign> <Campaign Discount Item> (discount ID: <number>) screen, in the Discount Display section, do the following:
    Use this | To do this
    Exposure limit Select the number of times the discount is to be shown to the user within a session from the drop-down list.

    By default the exposure limit is set to zero, indicating that no exposure limit is set. The exposure limit should have an upper limit of 10 exposures per user per session.

    Basket display | Type the text you want to display on the basket page concerning the discount.
    Content size Select the discount content size from the drop-down list of available types.

    You may require a specific type of ad for your discount campaign.

    Content type | Select the discount content type from the drop-down list of available types.

    Note

    • Different discount boxes appear below the Content Type box depending on the content type you select. For information about setting up your ad campaign display for a specific type of discount, see Setting Up an Ad Type.
  3. To save the discount campaign and return to the Campaign Manager screen, click Save and go back on the toolbar.

The discount display is saved with the discount campaign.

For information about publishing the discount on your Web site, see Publishing Campaign Changes on Your Web Site.

See Also

Discounts

Previewing the Discount Display

Creating a Target Expression

Creating a Target Group

Creating a Catalog Expression

New from Product Picker

Adding Page Groups

Publishing Campaign Changes on Your Web Site


Previewing the Discount Display

After you define the discount display, you can preview the display before you send it to production.

To preview a discount display

  1. In Campaigns, click Campaign Manager.

  2. In the Campaign Manager screen, select the discount for which you want to preview the discount campaign display, and then click Open on the toolbar.

  3. In the Campaign Manager <Customer> <Campaign> <Campaign Discount Item> (discount ID: <number>) screen, in the Discount Display section, click Preview.

  4. In the Preview dialog box, click Yes to save the discount campaign item.

A copy of your discount appears in the display area below the Preview button.

The Web page associated with the discount appears in a new Internet Explorer window.

See Also

Creating a Discount Campaign Item

Specifying the Ad Display

Previewing an Campaign Item


Copying a Discount Campaign Item

You can copy an existing discount campaign item to quickly add additional discount campaign items for a customer and its campaign. Using an existing discount as a template, you can change the properties of the existing discount to meet the new discount campaign item goals.

To copy a discount

  1. In Campaigns, click Campaign Manager.

  2. In the Campaign Manager screen, select the discount you want to copy, and then click Copy on the toolbar.

  3. In the Copy Discount item dialog box, do the following:
    Use this | To do this
    Select a customer | Select the customer from the drop-down list from which you want to copy the discount.
    Select a campaign | Select the campaign from the drop-down list from which you want to copy the discount.

  4. Click OK.

  5. In the Campaign Manager <Customer> <Campaign> New (discount) screen, in the Discount Properties section, do the following:
    Use this | To do this
    Discount Name | Type a name for the new discount.

  6. Edit the remaining properties as wanted, and then to save the discount and return to the Campaign Manager screen, click Save and go back on the toolbar.

The new discount appears in the Campaign Manager tree under the customer and campaign.

See Also

Creating a Discount Campaign Item


Targeting an Ad or Discount

You can use the Campaign Expressions module to define what categories, products, or product properties you want to deliver to users who meet your target criteria. You use the Campaigns Expressions module to build expressions for targeting an ad or discount to groups of users.

You can build the following types of expressions:

  • Catalog expressions. Define which categories, products, or product properties a discount applies to. For example, "if Book_Price is greater than $20.00, apply discount." After you create the catalog expression, you can target your discount campaigns to those products that match your campaign expressions criteria.

  • Target expressions. Define which users you want to deliver ads or discounts to. For example, "if User is female, deliver ad for blue paint."

  • Target groups. Combine several target expressions together, which enable you to target your ad and discount campaigns to groups of users that match your target expressions criteria. You can also use target expressions to target page groups on your Web site. After you have defined your target expressions, you can combine several expressions together to create target groups. For example, the expressions "if User is female", and "if User has purchased paint before", can be combined to create the target group "Female paint users." You can then deliver an ad or discount for wallpaper to the "Female paint users" group.

This section contains:

  • Creating a Catalog Expression

  • Creating a Target Expression

  • Creating a Target Group


Creating a Catalog Expression

You create catalog expressions to specify which categories or products you want to apply a discount to. You create an expression by selecting from a list of products, product properties, or categories in a catalog, operators, and if required, entering the value to be evaluated by the expression. For example, a catalog expression might be "Books are greater than 20.00" or "Category is equal to Fiction". If the expression evaluates to "True," the discount is applied to the product or category.

In the Catalog Expressions screen, you build a catalog expression by selecting one of the following:

  • New from Product Picker. Select this option when you want to search for the catalog, product, product property, or category that is used in the expression criteria.

  • New Catalog Expression. Select this option to open the Expression builder.

New from Product Picker

You use the Product Picker to find and select the product or category you want to target a discount campaign. You can find products and categories by using the following search methods:

  • To open the Product Picker

  • To browse a catalog

  • To conduct a keyword search

  • To search by product properties

To open the Product Picker

  1. In Campaigns, click Campaign Expressions.

  2. In the Campaign Expression: Target Expressions screen, click View on the toolbar, and then select Catalog Expressions from the drop-down list.

  3. In the Campaign Expressions: Catalog Expressions screen, click Add on the toolbar, and then select New from Product Picker from the drop-down list.

To browse a catalog

  1. In the Product Picker dialog box, do the following:
    Use this | To do this
    Search method | Select Browse catalog.
    Catalog | Select the catalog you want to search from the drop-down list.
    Categories | Select the category you want to search.

  2. Click OK.

The selected category appears in the Catalog Expression box.

To conduct a keyword search

  1. In the Product Picker dialog box, do the following:
    Use this | To do this
    Search method | Select Keyword search.
    Catalog | Select the catalog you want to search from the drop-down list.
    Keywords | Type the word(s) you want to search on, and then click Find Now.
    Products | Select the product you want to target.

  2. Click OK.

The selected product appears in the Catalog Expression box.

To search by product properties

  1. In the Product Picker dialog box, do the following:
    Use this | To do this
    Search method | Select Search by properties.
    Catalog | Select the catalog you want to search from the drop-down list.
    Target based on the following conditions Click New.

    The first of three edit boxes in the Target based on the following conditions box is activated, so you can select or type the expression clauses.

    Target based on the following conditions:
    • First Box. Select the property group from the drop-down list, and then select the property you want to use to create the new catalog expression.

      • Second Box. Select the operator you want to use with this catalog expression from the drop-down list.

      • Third Box. Type the property or value to be evaluated by the catalog expression.

    Note

    • In campaign expressions, use a semi-colon (;) to separate multiple values. Do not use a comma, because the comma is not recognized as a separator. For example, a list of numbers would be input as 2,534; 3,485; 6,982. The escape character for a literal semi-colon is a backslash (\). For example, a value such as ABC;12 would be input as ABC\;12.

    For example, in a catalog of books, the expression Author (property) contains (operator) Penn (string), applies a discount to books only authored by Daniel Penn.

    Click the illustration to enlarge or reduce.

    2. Click Apply.

    The Products matching the target criteria appear in the Products box.

    3. Click OK.

    4. To save the expression and return to the Campaign Manager screen, click Save and go back on the toolbar.

    The expression is added to the Campaign Expressions: Catalog Expressions screen in the Campaigns Expressions module. You can now use the expression to target a discount campaign to a group of users.

    New Catalog Expression

    In the Catalog Expressions screen, you use the Expression Builder to create catalog expressions.

    To create a catalog expression

    1. In Campaigns, click Campaign Expressions, click View on the toolbar, and then select Catalog Expressions from the drop-down list.

    2. In the Campaign Expressions: Catalog Expressions screen, click Add on the toolbar, and then select New Catalog Expression.

    3. In the Catalog Expression dialog box, do the following:
      Use this | To do this
      Name | Type a name for the new catalog expression.
      Description Type a description for the new catalog expression, and then click New.

      The first of three edit boxes in the Target based on the following conditions box are activated. Select or type the expression clauses.

      Target based on the following conditions:
      • First Box. Select the option that pertains to this expression from the drop-down list. Values for this box are Product, and Expressions (if any exist).
        • If you select Product, a list of the product properties appears. Select the property you want to use to create the new catalog expression.

        • If you select Expressions, a list of all current catalog expressions appears. Select the catalog expression you want to use to create the new catalog expression, and then click OK.
      • Second Box. Select the operator you want to use with this catalog expression from the drop-down list.

      • Third Box. Type the property or value to be evaluated by the catalog expression.

      Note

      • In campaign expressions, use a semi-colon (;) to separate multiple values. Do not use a comma, because the comma is not recognized as a separator. For example, a list of numbers would be input as 2,534; 3,485; 6,982. The escape character for a literal semi-colon is a backslash (\). For example, a value such as ABC;12 would be input as ABC\;12.

      For example, in a catalog of books, the expression Artist (product property) contains (operator) Penn (property), will apply a discount to books only authored by Daniel Penn.

      Click the illustration to enlarge or reduce.

      4. Click Apply.

        The new catalog expression is added to the Target based on the following conditions box.

        Note

        • To add additional conditions to the catalog expression you just created, repeat steps 2 through 4, and then select either And or Or from the drop-down list.
      5. To save the catalog expression and return to the Campaign Expressions screen, click Save.

      The expression is added to the Campaign Expressions: Catalog Expressions screen. You can now use the expression to target a discount campaign to a group of users.

      See Also

      Creating a Discount Campaign Item


Creating a Target Expression

You create target expressions to specify the users you want to target ads and discounts to. Expressions are a combination of properties, operators, and values that yield a result upon evaluation. You create an expression by selecting from a list of pre-defined targets, operators, and if required, entering the value to be evaluated by the expression, such as a number. For example, a target expression might be "Account Class is equal to 10" or "Female User is True". You use the Expression Builder in the Target Expressions screen to build your target expressions.

To create a new target expression

  1. In Campaigns, click Campaign Expressions.

  2. In the Campaign Expressions: Target Expressions screen, click View on the toolbar, and then select Target Expressions from the drop-down list.

  3. In the Campaign Expressions: Target Expressions screen, click Add on the toolbar.

  4. In the Target Expression dialog box, do the following:
    Use this | To do this
    Name | Type a name for the new target expression.
    Description Type a description for the new target expression, and then click New.

    The first of three edit boxes in the Target based on the following conditions box is activated, so you can select or type the expression clauses.

    Target based on the following conditions:
    • First box. Select the option that pertains to this expression from the drop-down list. Values for this box are User Object, Targeting Context, and Expressions (if any exist).

      If you select User Object, a drop-down list of user objects appears. Select the user object, and then select the user object type that you want to use in this expression.

      If you select Targeting Context, the Page Group property appears and additional properties that have been created for the Targeting Context profile. Select the property that you want to use in this expression. For information about adding profile properties, see Adding Properties to Profiles.

      If you select Expressions, the Choose an Expression dialog box appears. Select the expression from the list of expressions that you want to use, and then click OK.

      Expressions appear only if an expression has been created previous to opening the Target Expressions dialog box.

    • Second box. Select an operator type for the expression from the available types in the drop-down list.

    • Third box. Type the property or value to be evaluated by the expression.

      If an object or function is not listed, it is not valid in the context where you started the builder. For example, a different set of operators will appear if the target is based on an expression rather than on a user object.

      If you selected the User Catalog Set object in the first box, type the Catalog Set property to be evaluated by the expression. For information about adding a property for catalog set name, see Adding a property definition.

    Note

    • In campaign expressions, use a semi-colon (;) to separate multiple values. Do not use a comma, because the comma is not recognized as a separator. For example, a list of numbers would be input as 2,534; 3,485; 6,982. The escape character for a literal semi-colon is a backslash (\). For example, a value such as ABC;12 would be input as ABC\;12.

      For example, the expression State (product property) is equal to (operator) CA (string), will apply a discount to Customers that only live in the state of California.

    Click the illustration to enlarge or reduce.

  5. Click Apply.

    The new target expression is added to the Target based on the following conditions box.

    Note

    • To add additional conditions to the catalog expression you just created, repeat steps 3 through 5, and then select either And or Or from the drop-down list.
  6. To save the target expression and return to the Campaign Expressions: Target Expressions screen, click Save.

The expression is added to the Campaign Expressions: Target Expressions screen. You can now group several target expressions together to create a target group that you use to target your ads or discounts.

See Also

Adding an Ad Campaign Item

Creating a Target Group


Creating a Target Group

You use the Target Group module to bundle together several expressions in order to deliver an ad or discount a group of users. You can specify whether certain users are required for or excluded from the group. For example, in a target group of animal owners, you can specify that cat owners are included, but dog owners are excluded by applying actions to the target expressions. You define target groups to create business rules that determine the groups of users you target ads or discounts to.

Target groups are created from existing target expressions and actions. You can create new target expressions from the Target Group module using the Target Expression Builder. In the Target Group module, you can specify whether an expression is targeted, required, excluded, or sponsoring a home page.

To create a new target group

  1. In Campaigns, click Target Group.

  2. In the Target Group screen, click Add on the toolbar.

  3. In the Target Group: New screen, do the following:
    Use this | To do this
    Target group name | Type a name for the new target group.
    Expression Select the expression to use to create the new target group from the drop-down list.

    If you want to create a new expression, click the Create New Expression button. For information about creating new target expressions, see Creating a Target Expression.
    Action Select the action for the new target group from the drop-down list.

    Available actions are:

    • Target - The target action can be used in situations that have a limited population of the property available, but the user wants to buy many requests.

    If the expression evaluates to "True," the score is increased, as is the probability the content will be shown. If the expression evaluates to "False," the score is not changed. In both scenarios, the content is eligible for delivery.

    • Sponsor - the ad associated with the target group will be exclusively displayed on the site.

    If the expression evaluates to "True," the content is eligible for delivery and no other content is eligible unless it too has an expression with action = Sponsor. (Sponsor has only one multiplier.)

    • Require - the group of users in the target expression will be included in the target group.

    If the expression evaluates to "True," the content is eligible for delivery; if it is "False," the content is not eligible for delivery.

    • Exclude - the group of users in the target expression will be excluded from the target group.

    If the expression evaluates to "True," the content is not eligible for delivery; if it is "False," the content is eligible for delivery.

    Caution

    • The Require and Exclude action prevents an ad from being displayed to users with the excluded property. Additionally, if a user does not have the required or excluded property defined, they will not receive the ad. For example, if you create a target group that excludes hotmail users, the target group will also exclude users that do not have an e-mail account defined. Therefore, all users that have e-mail accounts defined and do not have hotmail accounts will see the ad.
  4. Click Accept.

  5. To save the target group and return to the Target Group screen, click Save and go back on the toolbar.

The new target group is saved in the list of available target groups. You can now use the target group to target your ads or discounts.

See Also

  • Adding an Ad Campaign Item

  • Creating a Discount Campaign Item

  • Targeting an Ad or Discount

  • Creating a Target Expression


Adding a Direct Mail Campaign Item

You use the Campaign Manager module to create and manage direct e-mail advertising campaigns. A direct mail campaign can be targeted toward specific users by using mailing lists that reside in List Manager. You use the Campaign Manager module to create new direct mail campaigns, personalize messages, add attachments to your direct mail messages, and modify direct mail properties. You can also test your direct mail lists before sending them to production.

The following workflow illustrates a sample scenario for creating and managing a direct mail campaign:

Workflow for creating and managing a direct mail campaign
List Manager

Adding Attachments to a Direct Mail Campaign

Campaign Manager
Importing a Mailing List
Creating a Direct Mail Campaign
Scheduling a Direct Mail Campaign
Testing a Direct Mail Campaign
Personalizing a Direct Mail Message

  1. In the List Manager module, import a mailing list (for example, a list of top customers).

  2. In the Campaign Manager module, create a direct mail campaign targeting the mailing list of top customers.

  3. Enter the name of a Hypertext Markup Language (HTML) page containing personalized content.

  4. Add an attachment to the direct mail campaign.

  5. Schedule the start times and end times for the direct mail campaign, and specify how often the direct mail job is to be sent.

  6. Test the direct mail you sent against a test list, and view your personalization pages.

This section contains:

  • Creating a Mailing List

  • Importing a Mailing List

  • Creating a Direct Mail Campaign

  • Personalizing a Direct Mail Message

  • Adding Attachments to a Direct Mail Campaign

  • Scheduling a Direct Mail Campaign

  • Testing a Direct Mail Campaign

  • Copying a Direct Mail Campaign Item


Creating a Mailing List

Before you create a direct mail campaign, the List Manager module must contain a valid mailing list. Mailing lists are used by Direct Mailer to send pieces of mail to selected recipients in a list.

You can create a mailing list using any text editor. A mailing list contains one or more rows of recipients. List Manager requires the field names in the following table when importing lists from SQL Server. Each row in the list contains a single recipient and is comprised of the following elements in comma-delimited format:

Field name | Parameter | Description
rcp_email | Email address | Required. Name or a name@domain.
rcp_guid | GUID | Optional. Globally unique identifier. The unique user ID that is used to provide content in a personalized mail message.
rcp_fmt | Message format | Optional. Controls the message format type that the Collaboration Data Object (CDO) translates the results into. For example, text, MIME Encapsulation of Aggregate HTML Documents (MHTML), or Multipurpose Internet Mail Extensions (MIME), MIME.
rcp_locale | Language | Optional. The code-page value for the mail message.
rcp_url | URL | Optional. Provides the ability to pass individual URLs per user to CDO.

Notes

  • The field names are restricted to the order listed in the table. You must supply the delimiter if an optional parameter is omitted in order to line up the subsequent optional parameters.

  • To create a list using program information in a .pst file (files which contain messages, appointments, contacts, and other Outlook items), see the "Export items to a file or to a personal folder file" topic in Microsoft Outlook Online Help.


Importing a Mailing List

The List Manager module must contain a valid mailing list before you can create a direct mail campaign. You use the List Manager module to import lists of users that you can then target through a direct mail campaign. You can import ASCII text files, files from Microsoft Excel, or tables from SQL Server databases.

To import a list

  1. In Campaigns, click List Manager.

  2. In the List Manager screen, click Import on the toolbar.

  3. In the Import a List dialog box, do the following:
    Use this | To do this
    List type Select the list type.

    The available options are Static and Dynamic.

    • Select Static to import a static, flat text file list.

    • Select Dynamic to import a dynamic list (a list that changes, such as one from a SQL Server database).
    Type name of list to copy to | Type a name for the imported list.
    List source Select the source type for the list.

    The available options are From File or From SQL Database.

    • Select From File for a static list.

    • If you select From SQL Database, do the following:
      1. In the Connection string box, enter the database connection string, which defines the location of a database and how to connect to it.

      2. In the SQL query box, enter the SQL query to return the wanted information.

        Example: SQL query:

        SELECT u_email_address AS rcp_email FROM UserObject WHERE d_date_registered >= '03/01/2000'

        For information about List Manager field name requirements, see Creating a Mailing List.

      Note

      • Contact your system administrator for database properties and SQL query information. For information about writing SQL queries see Query Fundamentals in SQL Books Online.
    File name | Type the path, file name, and extention of the list you want to import.

  4. Click OK.

The new list is imported and appears in the List Manager. You can now use the list in a direct mail campaign.

See Also

Managing Lists of User Records

Importing and Exporting Lists


Creating a Direct Mail Campaign

Direct mail campaigns are a way to get users to view your ads. A direct mail campaign can be targeted toward specific users by using mailing lists that reside in List Manager. You can import ASCII text files, tables from SQL Server databases, and Analysis reports into List Manager. You can use these lists to run Direct Mailer jobs in order to target your users more successfully.

To create a Direct Mail campaign

  1. In Campaigns, click Campaign Manager.

  2. In the Campaign Manager screen, select the campaign for which you want to create a direct mail campaign, click Add on the toolbar, and then select New Direct Mail from the drop-down list.

  3. In the Campaign Manager <Customer> <Campaign> New (direct mail) screen, in the Direct Mail Properties section, do the following:
    Use this | To do this
    Direct mail name | Type a name for the Direct Mailer job.
    Message from e-mail address | Type the address that the direct mail is being sent from.
    Reply to e-mail address Type the address to which the recipient is to reply if different from the default address.

    This box defaults to the address the direct mail is being sent from.
    Message subject | Type the subject text for this Direct Mailer job.
    File path or URL containing message body Type the path of the file or the URL that you are using to display the direct mail message.

    The URL of the personalized message body must have a valid HTML content type extension, such as .htm or .asp. Invalid extensions such as .xml will result in a Collaboration Data Objects (CDO) error and the message will not be sent.

    To view personalized pages, see Testing a Direct Mail Campaign.

    Caution

    • A file over two megabytes in size will be truncated. Only the first two megabytes of data will be used in the direct mail.
    Attachment Type the file path and name of the attachment being sent with the message.

    If no attachment is being sent, leave this box unchecked.
    Mailing list | Select the mailing list that this direct mail campaign will use from the drop-down list.
    Personalize direct mail per user Select this check box to enable personalization for this direct mail campaign.

    Leave this check box unchecked to disable personalization for this direct mail campaign.
    Mail format Select the format for this mail.

    The options are:

    • Text - Formats the mail in ASCII format.

    • MHTML - Formats the mail in multilingual HTML.

    • MIME - Formats the mail with Multipurpose Internet Mail Extensions.
    Comments (not included in message) | Type any required comments that are pertinent to this direct mail job.

  4. To save the direct mail campaign and return to the Campaign Manager screen, click Save and go back on the toolbar.

The direct mail campaign is added to the Campaign Manager. You can now schedule, and then test the direct mail campaign.

Note

  • In the File path or URL containing message body box, to verify that the message body URL path is valid, select the path and the file or URL, and then press [CTRL C] to copy the selection. Open your browser, and then press [CTRL P] to paste the selection into the Address line, and then press [ENTER]. If the file or URL is correct, the appropriate page will appear in your browser.

For information about scheduling a direct mail campaign, see Scheduling a Direct Mail Campaign. For information about testing a direct mail campaign, see Testing a Direct Mail Campaign.

See Also

Adding a Campaign

Managing Lists of User Records

Importing and Exporting Lists


Personalizing a Direct Mail Message

You can personalize e-mail messages to users by using an Active Server Page (ASP) that has been designed for personalization. For example, you could include the first name of the user in a personal greeting. Special text can be added to the ASP page for delivery. If personalization is not specified, the direct mail message is delivered as a plain HTML page.

To personalize a direct mail message

  1. In Campaigns, click Campaign Manager.

  2. In the Campaign Manager screen, select the direct mail campaign you want to personalize and click Open on the toolbar.

  3. In the Campaign Manager <Customer> <Campaign> <Direct Mail Item> (direct mail ID: <number>) screen, do the following:
    Use this | To do this
    File path or URL containing message body | Enter the name of the HTML page containing the personalized content.
    Personalize direct mail per user Select this check box to enable personalization for this direct mail campaign.

    Leave this check box unchecked to disable personalization for this direct mail campaign.
    Mail format Select the format for this mail.

    The options are:

    • Text - Formats the mail in ASCII format.

    • MHTML - Formats the mail in multilingual HTML.

    • MIME - Formats the mail with Multipurpose Internet Mail Extensions.

  4. To save the direct mail campaign with personalization and return to the Campaign Manager screen, click Save and go back on the toolbar.

    Note

    • To view your personalized pages, see Testing a Direct Mail Campaign.

The direct mail message will be sent with personalization.

See Also

Creating a Direct Mail Campaign

Testing a Direct Mail Campaign


Adding Attachments to a Direct Mail Campaign

You can add attachments to direct mail campaigns using the Direct Mail Properties section of the Campaign Manager screen. An attachment can be any file containing information you want to send with the direct mail campaign.

To add an attachment to a Direct Mail campaign

  1. In Campaigns, click Campaign Manager.

  2. In the Campaign Manager screen, select the direct mail campaign you want to add an attachment to and click Open on the toolbar.

  3. In the Campaign Manager <Customer> <Campaign> <Direct Mail Item> (direct mail ID: <number>) screen, do the following:
    Use this | To do this
    Attachment | Type the path to the attachment that is to be sent with the mail message.

  4. To save the attachment with the direct mail campaign and return to the Campaign Manager screen, click Save and go back on the toolbar.

The attachment is saved with this Direct Mailer job.

See Also

Creating a Direct Mail Campaign


Scheduling a Direct Mail Campaign

You use the Mail Schedule section of the Campaign Manager screen to schedule the start times and end times for a direct mail campaign, and to specify how often the direct mail is to be sent.

To schedule a Direct Mail campaign

  1. In Campaigns, click Campaign Manager.

  2. In the Campaign Manager screen, select the direct mail campaign you want to schedule and click Open on the toolbar.

  3. In the Campaign Manager <Customer> <Campaign> <Direct Mail Item> (direct mail ID: <number>) screen, in the Mail Schedule section, do the following:
    Use this | To do this
    Start date | Type or select the start date for the campaign from the drop-down calendar.
    End date Type or select the end date for the campaign from the drop-down calendar.

    The End Date box will be unavailable if the direct mailing interval is set to one time only.
    Start time | Select a starting time from the drop-down list for the campaign.
    Mailing interval | Select how often you want to send the mail from the drop-down list.

    Note

    • Several options are available for the mailing interval. Depending on the option you select, boxes are displayed that you use to select the recurrence pattern for the campaign.
  4. To save the schedule with the direct mail campaign and return to the Campaign Manager screen, click Save and go back on the toolbar.

The schedule is saved with the direct mail campaign.

Note

  • If SQL Server Agent is stopped while a scheduled Direct Mailer job is running, the Direct Mailer job will stop running and cannot be restarted. When a scheduled job is stopped in this way, there is no indication that the job has failed. You must restart SQL Server Agent, and then restart the Direct Mailer job.

See Also

Creating a Direct Mail Campaign


Testing a Direct Mail Campaign

You can test your direct mail campaigns against a test list before sending it out to a larger mailing list. The test mail will also enable you to review your personalization pages for accuracy.

To test a direct mail campaign

  1. In Campaigns, click Campaign Manager.

  2. In the Campaign Manager screen, select the direct mail campaign you want to test and click Open on the toolbar.

  3. In the Campaign Manager <Customer> <Campaign> <Direct Mail Item> (direct mail ID: <number>) screen, in the Test section, do the following:
    Use this | To do this
    Test list | Select the mail list with which to test the direct mail campaign.

  4. Click Send Test Mail.

Direct Mailer has sent out mail against the selected Test list.

See Also

Creating a Direct Mail Campaign


Copying a Direct Mail Campaign Item

You can copy an existing direct mail campaign item that has already been created to quickly add additional direct mail items for a customer and its campaign. Using the existing direct mail item as a template, you can change the properties of the existing direct mail campaign to meet the goals of the new direct mail campaign.

To copy a direct mail campaign item

  1. In Campaigns, click Campaign Manager.

  2. In the Campaign Manager screen, select the direct mail campaign you want to copy, and then click Copy on the toolbar.

  3. In the Copy Direct Mail item dialog box, do the following:
    Use this | To do this
    Select a customer | Select the customer from the drop-down list from which you want to copy the direct mail item.
    Select a campaign | Select the campaign from the drop-down list from which you want to copy the direct mail item.

  4. Click OK.

  5. In the Campaign Manager <Customer> <Campaign> New (direct mail) screen, in the Direct Mail Properties section, do the following:
    Use this | To do this
    Direct mail name | Type a name for the new direct mail item.

  6. Edit the remaining properties as necessary.

  7. To save the direct mail item and return to the Campaign Manager screen, click Save and go back on the toolbar.

The new direct mail item appears in the Campaign Manager tree under the selected customer and campaign.


Managing Lists of User Records

You use List Manager to create and manage lists. There are two types of lists: generic lists and mailing lists. Generic lists are lists imported into List Manager from the Reports module, the Segment Viewer module, SQL Server table, or ASCII text file. List Manager automatically attempts to convert generic lists into mailing lists if they contain rows of e-mail addresses. Mailing lists are used by Direct Mailer to create and send pieces of mail to selected recipients in the list. If the generic list does not contain e-mail addresses, the list is imported as a user list if the requirements of a user list are met. For more information about user list requirements, see "ListManager Object" in Commerce Server 2000 Help.

After the lists are imported into List Manager, you can use them to run Direct Mailer jobs to target your users more successfully. For example, you can run reports that show you the characteristics and past behavior of your users, and then create a direct mail campaign to target advertisements or products to those users.

Individual recipients can request to be placed on either a campaign level or site level opt-out list. Recipients who request that they not receive direct mail messages created as part of a particular campaign item are placed on a campaign level opt-out list. The campaign level opt-out list is named Opt Out <campaign item ID>. Users who request to be placed on the site opt-out list will not receive direct mail messages created by any direct mail campaigns on your site. In the List Manager screen, the site level opt-out list is named Opt Out. For more information about opt out lists, see Opt Out Lists.

Lists are created in List Manager by importing lists created by other applications, such as Microsoft SQL Server (to create a SQL table), Notepad (to create an ASCII text file), Microsoft Excel (to create a spreadsheet) or Microsoft Outlook (to create .pst files that contain messages, appointments, contacts, and other Outlook items).

You can also use List Manager to export lists to a file or SQL Server database, add or subtract lists, copy lists, extract lists, and delete lists.

This section contains:

  • Importing and Exporting Lists

  • Viewing Exported Lists

  • Adding and Subtracting Lists

  • Copying Mailing Lists

  • Extracting Mailing Lists


Importing and Exporting Lists

Lists are created in List Manager by importing lists created by other applications, such as Microsoft SQL Server (to create a SQL table), Notepad (to create an ASCII text file), Microsoft Excel (to create a spreadsheet) or Microsoft Outlook (to create .pst files which contain messages, appointments, contacts, and other Outlook items). You can also import Analysis reports and Segment Viewer lists into List Manager. You can then use these lists to run Direct Mailer jobs in order to target your users more successfully.

You can also export lists from List Manager to a file or SQL Server database, and then search on and view members of the exported list.

Note

  • You cannot use List Manager to import generic lists with header rows as shown in the following example:
    Productid | ProductName | Unit
    1 | Socks | 100
    2 | Shirts | 20

If you want to use a generic list with header rows, you must first import the list into SQL Server, using a SQL Server import tool, such as the BULK INSERT command, and then import the list into List Manager. For more information about SQL import tools, see SQL Server Books Online.

To import a list

To export a list

To import a list

  1. In Campaigns, click List Manager.

  2. In the List Manager screen, click Import on the toolbar.

  3. In the Import a list dialog box, do the following:
    Use this | To do this
    List type Select the list type from the drop-down list.

    The available options are Static and Dynamic.

    • Select Static to import a static, flat text file list.

    • Select Dynamic to import a dynamic list (a list that changes, such as one from a SQL Server database).
    Type name of list to copy to | Type a name for the imported list.
    List source Select the source type for the list.

    The available options are From File or From SQL Database.

    • Select From File for a static list.

    • If you select From SQL Database, do the following:
      1. In the Connection string box, enter the database connection string, which defines the location of a database and how to connect to it.

      2. In the SQL query box, enter the SQL query to return the wanted information.

        Example: SQL query:

        SELECT u_email_address AS rcp_email FROM UserObject WHERE d_date_registered >= '03/01/2000'

        For information about List Manager field name requirements, see Creating a Mailing List.

      Note

    • Contact your system administrator for database properties and SQL query information. For information about writing SQL queries see Query Fundamentals in SQL Books Online.
    File name | Type the path, file name, and extension to the list you want to import, or click Browse to find the path for the list.

  4. Click OK.

The new list appears in the List Manager. You can now use this list in a direct mail campaign.

To export a list

  1. In Campaigns, click List Manager.

  2. In the List Manager screen, select the list you want to export and click Export on the toolbar.

  3. In the Export a List dialog box, do the following:
    Use this To do this
    Export list to Select File or SQL Database from the drop-down list.
    • Select File to export the list to a file

    • Select SQL Database to export the list to a SQL Server database.

    If you select File, in the File name box, type the path to the file to which you want to export the list.

    If you select SQL Database, in the Connection String box, type the connection string name from the SQL Server database. In the Table Name box type the name of the table to export the list to.

    Note

    • Contact your system administrator for database properties information.

  4. Click OK.

The report is exported to the selected source.

See Also

Exporting Segment Data to List Manager

Exporting a Static Report

Exporting a Dynamic Report

Importing a List of User Profiles


Viewing Exported Lists

You can search on and view members of an exported mailing list. You can locate an individual e-mail address and view all addresses in a particular list.

To view a list exported to a SQL Server table

  1. Open SQL Enterprise Manager from the Start menu. Click Start, point to Programs, point to Microsoft SQL Server, and then click Enterprise Manager.

  2. In the left pane, expand Microsoft SQL Servers>SQL Server Group>(ServerName)>Databases, and then expand the database in which the table containing the list belongs.

  3. In the details pane, right-click the table, point to Open Table, and then click Return all rows to view all the data in the table.

For information about searching SQL Server tables, see "Specifying Search Criteria," in the SQL Server Enterprise Manager online documentation.

Note

  • To sort or search for specific records in a list exported to a comma separated value (CSV) file, you can open the file in any application that has sorting and searching capabilities.

See Also

Adding a Direct Mail Campaign

Exporting a Static Report

Viewing a Static Report


Adding and Subtracting Lists

You may have several lists in the List Manager that you want to combine into a new list. Or, you may have already combined several lists in the List Manager and want to delete one list from a combined list. The List Manager provides the capability of managing multiple lists.

To add one list to another list

  1. In Campaigns, click List Manager.

  2. In the List Manager screen, select the list that you want to combine with another list and click Add or Subtract a list on the toolbar.

  3. In the Add/Subtract Lists dialog box, do the following:
    Use this | To do this
    Operation | Select Add to from the drop-down list.
    Target list | Select the list to which you want to add the original list.
    Name for new list | Type the name for the new list.
    Description | Type a description for the new list.

  4. Click OK.

The new list appears in List Manager.

To subtract one list from another list

  1. In Campaigns, click List Manager.

  2. In the List Manager screen, select the list that you want to delete information from and click Add or Subtract a list on the toolbar.

  3. In the Add/Subtract List dialog box, do the following:
    Use this | To do this
    Operation | Select Subtract from from the drop-down list.
    Target list | Select the list from which you want to subtract information.
    Name for new list | Type the name for the new list.
    Description | Type a description for the new list.

  4. Click OK.

The new list appears in List Manager, excluding the list that was subtracted

See Also

Managing Lists of User Records


Copying Mailing Lists

You may have an existing mailing list that you want to use to create additional mailing lists. In List Manager, you can copy a mailing list that has already been created, and then quickly modify the copied list. For example, you can combine it with an existing list to create a larger mailing list.

To copy a mailing list

  1. In Campaigns, click List Manager.

  2. In the List Manager screen, select the list you want to copy, and then click Copy on the toolbar.

  3. In the Copy List dialog box, do one the following:
    Use this | To do this
    Select an existing list to copy to | Select an existing list to which you want to copy the mailing list.
    Type name of list to copy to | Type the name of a new list to which you want to copy the mailing list.

  4. Click OK.

The list is copied and you can now modify the copied list.


Extracting Mailing Lists

In List Manager, you can remove duplicate and blank e-mail addresses from a generic list, leaving only the necessary fields for a mailing. The resulting list is a more accurate count of the number of unique e-mail addresses contained in the list, making the list more useful and increasing performance during runtime.

To extract a mailing list

  1. In Campaigns, click List Manager.

  2. In the List Manager screen, select the list you want to extract, and then click Extract direct mail list on the toolbar.

  3. In the Extract Mailing List dialog box, do the following:
    Use this | To do this
    Type name of list to copy to | Type the name of a new list to which you want to extract the mailing list.
    Description | Type a description for the extracted list.

  4. Click OK.

The list is extracted with unique e-mail addresses.


Analyzing a Campaign

You can use the Campaign Manager module to run campaign reports that help you to make decisions about pricing, marketing, advertising, and other aspects of your business. Analyzing your campaigns gives you the ability to promote the campaigns that are the most successful.

This section contains:

  • Running a Campaign Report

  • Exporting a Report to List Manager


Running a Campaign Report

After the import log files containing your campaign data are imported into the Data Warehouse, you can run reports to analyze the effectiveness of your ad campaigns. Log files can be run daily, weekly, or monthly. To receive the schedule for importing log files on your site, contact your system administrator.

You can use Campaign Manager module to view a list of reports. When you view the list of reports, the Analysis Reports module appears on top of the Campaign Manager. From the Reports module, you can run both dynamic and static reports. When you first open the Reports module, the default view assumes a search for "All Reports." You can narrow your list by using more specific search criteria. For information about advertising reports, see Advertising Reports.

To find a campaign report

  1. In Campaigns, click Campaign Manager.

  2. In the Campaign Manager screen, click Preview report on the toolbar to view a list of campaign reports.

    Note

    • To view the entire list of reports, use the Page Scrolling buttons at the bottom of the list.
  3. In the Reports screen, click Find on the toolbar.

  4. In the Find pane, do the following:
    Use this To do this
    Find By Select the criteria you want to search on from the drop-down list.

    Different boxes appear below the Find By box depending on the type of criteria you select.

    In the box(s) under the Find By box, type or select from the list the specific value for the criteria that you have selected (name, category, creator, type).

  5. Click Find Now.

A list of reports matching the search criteria appears in the lower section of the Find pane.

To run a campaign report

  • In Reports, in the list of available reports, select the report you want to run, and then click Run report on the toolbar.

While a dynamic report is running, a new Internet Explorer window appears immediately on your screen, on top of the Reports module window. While the report is running, you can minimize that window and continue working in Commerce Server Business Desk.

While a static report is running, the Reports module remains on your screen and is available for continued work. For information about running reports, see Running Reports.

To check report status

  • In Analysis, click Competed Reports.

In the Completed Reports screen, you can view the list of completed reports and check the status of the report.

See Also

Running Reports

Finding Reports


Exporting a Report to List Manager

You can export a static Analysis report to the List Manager module and then use that list to run a Direct Mailer job. By analyzing usage at your site, you can generate a list of registered users to which you can then target your ad (using the Campaign Manager module) through Direct Mail. For example, you want to run an ad for a new book about biking. Using the Reports module, you can generate a list of registered users who enjoy biking. You can then target the ad to that list of registered users.

To find a static report

  1. In Campaigns, click Campaign Manager.

  2. In the Campaign Manager screen, click Preview report on the toolbar to view the list of reports.

  3. In the Reports screen, click Find on the toolbar.

  4. In the Find pane, do the following:
    Use this | To do this
    Find By | Select Type from the drop-down list.
    Type | Select Static from the drop-down list.

  5. Click Find Now.

A list of static reports appears in the Find pane.

To export a report to List Manager

  • In the Reports screen, select the report you want to export, and then click Export on the toolbar.

The report is exported to List Manager.

See Also

Finding Reports

Managing Lists of User Records


Deleting and Restoring Campaigns

You can delete customers, campaigns, or campaign items from the Campaign Manager module when they are no longer required. Campaign Manager is organized hierarchically by customer, campaign, and campaign items. When you delete customers, campaigns, or campaign items, you should delete down the hierarchical tree. For example, if you delete a customer, the campaigns and campaign items for that customer are deleted as well. When you restore campaign items, you should restore up the hierarchical tree. For example, if you restore a campaign item, you must ensure that that the subordinate campaign and customer records are restored as well.

When you delete a customer, the customer is archived along with the campaigns and campaign items. After a customer, campaign, or campaign item is deleted, you can restore them using Campaign Manager.

This section contains:

  • Deleting and Restoring a Customer

  • Deleting and Restoring a Campaign

  • Deleting and Restoring a Campaign Item


Deleting and Restoring a Customer

You can remove a customer using the Campaign Manager module. After you remove a customer, the customer is archived along with its campaigns and campaign items and can be restored using Campaign Manager.

To delete a customer

  1. In Campaigns, click Campaign Manager.

  2. In the Campaign Manager screen, select the customer you want to delete, and then click Delete on the toolbar.

  3. In the Delete dialog box, click Yes.

The customer is deleted from the Campaign Manager and has been archived with its campaigns and campaign items.

To restore a customer

  1. In Campaigns, click Campaign Manager.

  2. In the Campaign Manager screen, click Find on the toolbar.

  3. In the Find pane, do the following:
    Use this | To do this
    Customer Type the name of the customer you want to restore.

    Note

    • You can type a string of letters to narrow your search. For example, "ar" will retrieve only those customers that contain an "ar" in them, such as Arbor Shoes, and School of Fine Art.
    Deleted | Select Both from the drop-down list.

  4. Click Find Now.

The customer appears in the Filtered View list, with a status of Deleted.

  5. Select the Customer from the Filtered View list, and then click Restore on the toolbar.

  6. In the Restore? dialog box, click Yes.

The customer status is restored to active.

  7. Click Reset to restore the Filtered View, and then click the Close the Find Pane button.

The customer is restored and appears in the Campaign Manager Filtered View list.

See Also

About Campaigns

Deleting and Restoring a Campaign

Deleting and Restoring a Campaign Item

Searching Campaigns


Deleting and Restoring a Campaign

You can remove a campaign using the Campaign Manager module. After you remove a campaign, the campaign is archived along with its campaign items and can be restored using Campaign Manager.

To delete a campaign

  1. In Campaigns, click Campaign Manager.

  2. In the Campaign Manager screen, select the campaign you want to delete, and then click Delete on the toolbar.

  3. In the Delete? dialog box, click Yes.

The campaign is deleted from the Campaign Manager and is archived with its campaign items.

To restore a campaign

  1. In Campaigns, click Campaign Manager.

  2. In the Campaign Manager screen, click Find on the toolbar.

  3. In the Find pane, do the following:
    Use this | To do this
    Customer | Type the name of the customer of the campaign you want to restore.
    Deleted | Select Both from the drop-down list.
    From | Type or select from the drop-down calendar the date the campaign was created.
    To | Type or select from the drop-down calendar the date the campaign was deleted.

  4. Click Find Now.

The campaign appears in the Filtered View list, with a status of Deleted.

  5. Select the Campaign from the Filtered View list, and then click Restore on the toolbar to restore the campaign status to active.

  6. In the Restore? dialog box, click Yes.

The Campaign status is changed to active.

  7. Click Reset to restore the Filtered View, and then click the Close the Find Pane button.

The campaign is restored and appears in the Campaign Manager Filtered View list.

See Also

About Campaigns

Deleting and Restoring a Customer

Deleting and Restoring a Campaign Item

Searching Campaigns


Deleting and Restoring a Campaign Item

You can remove a campaign item using the Campaign Manager module. After you remove a campaign item, it is archived and can be restored using Campaign Manager.

To delete a campaign item

  1. In Campaigns, click Campaign Manager.

  2. In the Campaign Manager screen, select the campaign item you want to delete, and then click Delete on the toolbar.

  3. In the Delete? dialog box, click Yes.

The campaign item is deleted from the Campaign Manager.

To restore a campaign item

  1. In Campaigns, click Campaign Manager.

  2. In the Campaign Manager screen, click Find on the toolbar.

  3. In the Find pane, do the following:
    Use this | To do this
    Item type | Select the type of campaign item you want to restore.
    Customer | Type the name of the customer of the campaign item you want to restore.
    Deleted | Select Both from the drop-down list.
    From | Type or select from the drop-down calendar the date the campaign item was created.
    To | Type or select from the drop-down calendar the date the campaign item was deleted.

  4. Click Find Now.

The campaign item appears in the Filtered View list, with a status of Deleted.

  5. Select the Campaign from the Filtered View list, and then click Restore to restore the campaign item status to active.

  6. In the Restore? dialog box, click Yes.

The Campaign item status is changed to active.

  7. Click Reset to restore the Filtered View, and then click the Close the Find Pane button.

The campaign item is restored and appears in the Campaign Manager Filtered View list.

See Also

About Campaigns

Deleting and Restoring a Customer

Deleting and Restoring a Campaign

Searching Campaigns


Searching Campaigns

The Campaign Manager tree structure can be extensive. You can use the Find pane in Campaign Manager module to search for campaigns using filter criteria. Using filter criteria reduces the number of items displayed in the Campaign Manager tree, making it easier to locate and manage your campaigns.

You can search for campaigns by campaign item, customer name, or by status (active or inactive). You can also search for campaigns that have been deleted. Once a campaign has been deleted, the campaign and campaign items are archived and can be restored if required.

To search for a campaign item

To search for a deleted discount campaign item

To search for a campaign item

  1. In Campaigns, click Campaign Manager.

  2. In the Campaign Manager screen, click Find on the toolbar.

  3. In the Find pane, do the following:
    Use this | To do this
    Item type | Select the campaign item type from the drop-down list, or select All to include all campaign items.
    Customer | Type the name of the customer of the campaign you want to search.
    Status | Select Active or All from the drop-down list.
    Deleted | Select No or Both from the drop-down list.
    From | Type or select the date the campaign started from the drop-down calendar.
    To | Type or select the date the campaign ended or is scheduled to end from the drop-down calendar.

  4. Click Find Now.

The campaign items that match the search criteria appear in the Filtered View box.

Note

  • To restore the default search criteria, click Reset.

To search for a deleted discount campaign item

  1. In Campaigns, click Campaign Manager.

  2. In the Campaign Manager screen, click Find on the toolbar.

  3. In the Find pane, do the following:
    Use this | To do this
    Item type | Select Discount from the drop-down list.
    Customer | Type the name of the customer of the discount campaign.
    Status | Select All from the drop-down list.
    Deleted | Select Both from the drop-down list.
    From | Type or select the date the campaign started from the drop-down calendar.
    To | Type or select the date the campaign ended or is scheduled to end from the drop-down calendar.

  4. Click Find Now.

The campaign items that match the search criteria appear in the Filtered View box.

Note

  • To restore the default search criteria, click Reset.

See Also

About Campaigns

Deleting and Restoring Campaigns


Business Desk Catalogs

You use the Catalogs modules to create catalogs of products, and to add and update product data. You do not need any specialized knowledge about the databases that store your product data, even if you are assembling a catalog of products from different sources, such as several different suppliers.

This section contains:

  • Workflow for Catalogs Management. Illustrates the workflow for creating and managing a catalog.

  • About Catalogs. Describes the components of a catalog, and provides an overview of the steps to create a catalog schema.

  • Importing a Catalog. Explains how to import either a comma-separated values CSV catalog file or an Extensible Markup Language (XML) catalog file.

  • Creating a Catalog Schema. Explains how to define category, product, and property definitions for a catalog.

  • Creating a Catalog. Explains how to create catalogs and catalog sets, add items to a catalog, and price products in a catalog.

  • Pricing Products. Explains how to set product prices in your catalog at both the product level and the product variant level, and how to price groups of products. Explains how to set prices in a custom catalog.

  • Discounting Product Prices. Describes several ways you can discount product prices.

  • Creating Category Hierarchies. Explains how to establish hierarchies for categories within a catalog.

  • Creating Category and Product Relationships. Explains how to create relationships within a catalog.

  • Refreshing and Publishing a Catalog. Explains how to publish catalogs to your Web site, and how to refresh all caches and full-text indexes.

  • Sending a Catalog to a Trading Partner. Explains how to send a catalog to a trading partner. To do this, both you and your trading partner must have Microsoft BizTalk Server installed on your computer system.

  • Exporting a Catalog. Explains how to export a catalog to a shared folder.

  • Managing Catalog Schema. Explains how to change and delete property definitions, product definitions, and category definitions.

  • Managing Products, Categories, Catalogs, and Catalog Sets. Explains how to change and delete products, categories, catalogs, and catalog sets.

  • Managing Category and Product Relationships. Explains how to edit and delete category and product relationships.


Workflow for Catalogs Management

The following figure illustrates a sample scenario for creating a catalog. It shows how you can create a catalog by importing an XML catalog file or a CSV catalog file, or by creating catalog schema. It shows how after you create your catalog schema, you can then adding a category, add a product, and add product variants to the product. After you create one or more catalogs, you can create a catalog set. And finally, after you make changes to your catalog, you publish the catalog to your Web site.

Workflow diagram for Catalogs Management
XML or CSV
Importing a Catalog
Creating a Catalog Schema
Creating a Catalog
Property Definitions
Product Definitions
Category Definitions
Pricing Products
Pricing a Custom Catalog
Pricing a Product
Pricing at the Product Variant Level
Creating a New Catalog
Creating a Catalog Set
Adding a Category to a Catalog
Adding a Product to a Catalog
Adding Product Variants to a Product
Relationships and Hierarchies
Creating Category Hierarchies
Creating Category and Product Relationships
Refreshing and Publishing a Catalog


About Catalogs

A catalog is a way of organizing the products you want to sell. Business Desk helps you create and organize catalogs by maintaining a description of what properties various catalog items must have. This description is called the catalog schema. The schema lists all the types of categories, products, and properties allowed in your catalog.

In Commerce Server 2000 you use catalogs to organize and manage the product data in your database for display on your site, and to target products to users.

Using Catalogs in Web Site Management

Populating Your Catalog with Product Data

Exchanging Catalogs Using BizTalk Server

Catalog Structure

Catalog Organization: Hierarchies and Relationships

Unique Identifiers in a Catalog

Base Catalogs, Custom Catalogs, and Catalog Sets

Product Pricing Methods

Analyzing Catalog Sales

Using Catalogs in Web Site Management

You use the Catalogs modules in Commerce Server Business Desk to maintain, analyze, and enhance your catalogs. For example, when your site is in production, you can run reports from Business Desk to identify which products are not selling, and then create a discount campaign to sell more of these products.

Using Business Desk, you can:

  • Import catalogs from other data sources. You can import catalogs in Extensible Markup Language (XML) or comma-separated value (CSV) format from external sources. For example, if you have catalogs in other databases, you can import them to the Commerce Server database, and then use Business Desk to manage them.

    To convert a catalog to XML or CSV format, you can use your existing database management system to save the catalog in XML or CSV format, or a site developer can write a script using Microsoft Visual Basic to convert the catalog for you.

    Before you can import a catalog, the system administrator must create a shared folder on Commerce Server. You can use Windows Explorer to copy the catalog to the shared folder, and then use Business Desk to import it to the Commerce Server database.

  • Export catalogs. You can export your catalogs in XML format. You may want to export a catalog if, for example, you are selling products wholesale, and you want to export your catalogs to retailers. Or you may want to export a catalog to another application, for example, an inventory system or a pricing system.

    Before you can export a catalog, the system administrator must create a shared folder on Commerce Server or you must know the name of a directory on the server that you have access to. You can then use Business Desk to export the catalog to the shared folder or the directory.

    If you want Commerce Server to import or export catalogs on a scheduled basis, a site developer can provide this functionality.

  • Apply discounts to products. You can apply discounts to all products in a category, or to certain products that meet specified criteria. For example, if a Product.price = 20.00, then a discount of 10 percent is applied to the price of that product when users add it to their shopping baskets.For information about applying discounts to products, see Campaigns: Ads, Discounts, and Direct Mail. For instructions about adding a discount campaign, see Adding a Discount Campaign Item.

  • Edit products in the catalog. You can change the product name, price, description, and so on.

  • Update product information in real time. You can update product information, such as the product price, and then publish the changes to your Web site. For example, if shoppers have added the product to their baskets, and your site is updated before they check out, Commerce Server applies the new price to their basket. If shoppers have saved their baskets, and then return to them after you have updated the price, the new price is displayed.

  • Identify which products are selling. You can run Commerce Server reports to identify the top-selling products by units sold and by total sales, and you can identify the top-selling categories by units sold and by total sales. You can use the results of your analysis, for example, to discount products that are not selling well, or to promote accessories for products that are selling well. In addition, your site developer can customize your site to support related sells such as up sells and intelligent cross-sells.

  • Search for products. You can find products easily by performing a property search or a free text search.

Populating Your Catalog with Product Data

You can use the Catalog Editor module in Business Desk to manually enter product data, or you can use it to import data from an XML file or a CSV file. If, for example, you already have a catalog in another database, your system administrator can export it as an XML file, and then you can use the Catalog Editor module to import the catalog into your Commerce Server database.

Exchanging Catalogs Using BizTalk Server

BizTalk Server 2000 acts as a gateway for sending business documents between your company and your trading partners (also known as vendors). If your company and your trading partners all use BizTalk Server, you can trade catalogs, orders, documents, and other electronic forms. For example, vendors can send you their catalogs, and you can post them on your Web site with your own catalog. When users enter orders on your Web site, the orders are sent to the vendor directly to fill them.

Each of your trading partners can send you one or more catalogs of their products. Depending on how you set up your site, you can present these catalogs on your Web site as one catalog, or as different catalogs. For more information about using BizTalk Server, see Using BizTalk Server.

Catalog Structure

A Commerce Server catalog consists of two main parts:

  • Catalog schema. A description of the categories and products for a site. The catalog schema is available to all catalogs in the site.

  • Catalog. A single instance of the catalog schema that contains data.

The following table shows a sample catalog schema, Clothes, and then a single instance of the Clothes catalog schema with data for the catalog Sports Clothes.

Catalog schema | Catalog: Sports Clothes
Category Definition: Department Category Properties Name Description Image_filename Image_width Image_height | Category: Sport Shirts Department Sport Shirts Department 2000 catalog of sports shirts Sports_shirts.gif 100 200
Product Definition: Shirts Product Properties: Name Manufacturer Price Product Variant Properties: Size Color SKU | Product: Ace Soccer Shirt Ace Soccer Shirt Ace Shirts $20.00 M Green 23354

Catalog Schema

The catalog schema describes the characteristics of the categories and products in a particular type of catalog. For example, the catalog schema for a Sports Clothes catalog could contain the following product definitions: Shirts, Pants, and Shoes. To create a catalog schema, you use the Catalog Designer module in Business Desk.

The catalog schema consists of category definitions, product definitions, and property definitions. Category definitions and product definitions are created by using property definitions. The following figure shows the parts of a sample catalog schema.

A figure illustrating how properties are used in both product definitions and category definitions
Name (Text)
Manufacturer (Text)
Price (Currency)
Catagory Definition
Color (Multiple Choice) Description (Text) Image_filename (File Name) Image_width (Number) Image_height (Number) Manufacture (Text)
Name (Text)
Price (Currency)
Size (Multiple Choice)
SKU (Number)
Properties
Product Definition
Color (Multiple Choice) Description (Text) Image_filename (File Name) Image_width (Number) Image_height (Number) Manufacture (Text)
Name (Text)
Price (Currency)
Size (Multiple Choice)
SKU (Number)
Name (Text) Description (Text) Image_file name (File Name) Image_width (Number) Image_height (Number)
Variant Properties
Size (Multiple Choice)
Color (Multiple Choice)
SKU (Number)
Catalog Schema

Category definitions describe the specific qualities of the categories in your catalog. These category qualities are called category properties. You create a category definition by assigning category properties to it. For example, the Department category definition might have the following category properties: Name, Description, Image File Name, Image Height, and Image Width. When you create a category based on the Department category definition, you will enter values for the category properties. For example, the Name category property might be "Sport Shirts Department."

Product definitions describe the specific qualities of a particular product. These product qualities are called product properties. You create a product definition by assigning product properties to it. For example, you might create a product definition named Shirt that would include three product properties: Name, Manufacturer, and Price. When you create a product based on the Shirt product definition, you will enter values for the product properties. For example, the Name product property might be "Ace Soccer Shirt."

Both product properties and category properties are based on property definitions. A property definition describes information about the property such as the data type of the property (for example, number, text, and decimal), the name of the property, and a minimum value for the property. For example, you can create a property named Shirt_Size with the values Small, Medium, and Large, or a property named Length with a minimum value of 10 and a maximum value of 120.

Catalog schema can be changed. You can edit a catalog schema even after a catalog has data in it. For example, you can add, remove, or rename property definitions, and you can change the data type of the property, for example, from a number to a string.

For instructions about creating a catalog schema, see Creating a Catalog Schema.

Catalogs

A catalog is an instance of a catalog schema that contains data about individual products and the categories in which they are organized. To create a catalog, you use the Catalog Editor module in Business Desk.

A catalog consists of categories, products, product variants, and properties. The following figure shows the parts of a sample catalog schema, and how they map to the parts of a catalog. Properties are used in the category definition and the product definition. The category definition "Dept" is the used for the "Soccer Shirts" category. The product definition "Soccer Shirt" is used for the "Ace Soccer Shirt" product.

A figure illustrating the parts of a sample catalog schema and catalog
Catalog Schema
Catalog Data
Category Definition
Category Type 'DEPT'
Property Name
Property Size
Property Color
Property 'SKU'
Price: 20
Properties
Product Definition
Soccer Shirt
Soccer Shirt Category
Ace Soccer Shirt Price: 20
Sports Clothes Catalog
Size: S
Size: S
Size: M
Size: M
Size: L
Color: Green
SKU:115
Category
Catalog
Product Family Unique ID = Name
Product Variants Unique ID = SKU

Categories are individual instances of a category definition. For example, a category definition named Department might be used to create the category Soccer Shirts.

Products are single items in your catalog. A product is defined by a combination of property definitions. For example, if you have a product definition named Soccer Shirts, which has the properties Name, Color, and Size, you create a product for each name, color, and size combination that you want to include in your catalog.

Products can be arranged into groups of closely related items, which are called product families. A product family is a group of products that contain product variants. For example, a large-sized, green shirt with the SKU 114 is one product variant of the Soccer Shirt product; taken together, size, color, and SKU form one variant. A product variant always includes a unique identifier, such as a SKU, and a price. Each product variant is based on the same product definition.

For instructions about creating a catalog, see Creating a Catalog.

Catalog Organization: Hierarchies and Relationships

To organize the products in your catalog and make it easier for users to navigate to what they want, you can create category hierarchies and relationships among categories and products. For example, you can create a parent category that includes two different categories, known as child categories. When users navigate to the parent category, the child categories are displayed, enabling users to quickly find the products they want.

The following figure illustrates how a parent category can have several child categories, and how each child category can also be a parent category.

A figure illustrating a sample catalog
Catalog Collection
Catalog B
Catalog C
Sport Clothes Catalog
Pants
Shirts
Soccer Shirts
Two-Piece
Track Suits
Ace Soccer Shirt
Ace Soccer Shorts
Accessory

Size:
Color:
SKU:

Size:
Color:
SKU:

Size:
Color:
SKU:

S
Black
113

M
Blue
114

L
Green
115

In the above figure, the Sports Clothes Catalog has two categories: Shirts and Pants. The Shirts category has two children categories: Soccer Shirts and Two-piece Track Suits. This organization gives users two paths to the Two-piece Track Suits category. They can navigate to track suits through the Shirts category or through the Pants category. This figure also illustrates an accessory relationship between Ace Soccer Shirt and Ace Soccer Shorts. If the users are interested in the shirts, they may also be interested in the shorts.

For instructions about creating hierarchies, see Creating Category Hierarchies. For instructions about creating relationships, see Creating Category and Product Relationships.

Unique Identifiers in a Catalog

Both products and product variants have unique identifiers. The unique identifiers are either a text or a number type of property. For example, if you have a catalog of books, the title of the book might be the unique identifier for the product, and the ISBN number might be the unique identifier for the product variant. For the book The Quest Ahead, the hard cover version would be one variant, the paperback version another, and the audio version a third. All three product variants are part of the product family The Quest Ahead.

The following example shows the components of the product family The Quest Ahead.

Product Family = The Quest Ahead
Unique ID = Title: The Quest Ahead

Product Variant = The Quest Ahead hardback
Unique ID = ISBN: 1102334
Price = 20.00

Product Variant = The Quest Ahead paperback
Unique ID = ISBN: 1102335
Price = 10.00

Product Variant = The Quest Ahead audio
Unique ID = ISBN: 1102336
Price = 15.00

When you create a catalog, you specify which properties are the unique identifiers for products and product variants.

Base Catalogs, Custom Catalogs, and Catalog Sets

You can create two types of catalogs. You can also join two or more catalogs into catalog sets.

  • Base catalogs contain categories and products, but they do not contain any specific pricing rules. For information about creating a base catalog, see Creating a New Catalog.

  • Custom catalogs are derived from base catalogs, but they contain specific pricing rules for the products in that catalog. The prices in a custom catalog override the prices in a base catalog. You use custom catalogs in a supplier site, for example, when you want to give one or more companies a custom price on certain products. You use custom catalogs in a retail site, for example, when you have different membership levels for customers, and you want to price products according to the membership level. Or you might want to show different prices to users who shop at your site frequently. For information about creating a custom catalog, see Creating a Custom Catalog.

You determine which catalog a user sees on your site by creating catalog sets. A catalog set is a group of one or more catalogs that you make available to different users or organizations. For example, you may create one custom catalog, and then combine it with a general catalog, and then display that catalog set to members of a specific organization. The following figure illustrates how members of a soccer club can view a team clothes catalog that has special pricing.

A figure illustrating how different users can view different catalog sets
Sports Clothes Catalog
Winter Clothes Catalog
Sports Clothes Catalog
Winter Clothes Catalog
Team Clothes Catalog (Custom pricing at the category level)
Soccer Member Catalog Sets
Members of a Soccer Club
All Users
General Catalog Set

For information about creating catalog sets, see Creating a Catalog Set.

You specify which catalog set a user sees in the Users module in Business Desk. When you create a new user, you specify the catalog set name. For information about creating a new user and specifying the catalog set, see Adding a User.

Product Pricing Methods

You can set the price of a product in a catalog using one of three methods:

  • Direct pricing. You define the price for a product in the product definition. You can do this either when you create the product or when you edit it to change the price. For instructions about applying direct pricing, see Pricing a Product and Pricing at the Product Variant Level.

  • Indirect pricing. The price is determined by its association with a particular pricing category. When a product is associated with a pricing category, the price on the product is overwritten by the price defined on the pricing category. Indirect pricing is typically used when you want to price a group of products the same way, for example, to create special category where all products are $1.99. For instructions about applying indirect pricing, see Pricing Products in a Category.

  • Custom pricing. You apply the price to a category. By doing this you create a custom catalog. There are three types of custom pricing that you can apply to a custom catalog:
    • Percentage adjustment. Specifies the percentage of the list price that should be charged for a product. For example, to apply a 10 percent discount, you would enter 90, indicating that the product is selling for 90 percent of the list price.

    • Fixed adjustment. Specifies the exact amount to either increase or decrease the list price. For example, to take $2.00 off, you would type –2, indicating that the product is selling for $2 less; to increase the cost by $2.00, type 2, indicating that it is selling for $2.00 more.

    • Set Price. Specifies the exact price of the product. For example, the product is selling for exactly $10.00.

    For instructions about applying custom pricing, see Pricing a Custom Catalog.

Analyzing Catalog Sales

The following table lists the reports included with Commerce Server that you use to analyze catalog sales data.

Report | Description
Customer Sales | Review customer details, total sales, and total orders. This information can be used to target those customers with online campaigns, for example direct mail promotions.
Shopping Basket Events | Determine when items have been added to or removed from shopping baskets.
Buyer Browsing to Purchase | Analyze user visit patterns. This report provides data such as average number of visits, visits per buy, total sales, count sales, and visitor count.
Product Sales | Analyze product sales volume and revenue by date. This report provides quantity and revenue data.
Order Events | Analyze when orders are placed on your site. This report provides data such as date, time, event, and user type.
Customer Spend Summary | Analyze sales volume and revenue by customer.

For a list of all Commerce Server reports, see Commerce Server Reports. For information about running reports, see Running Reports.

See Also

Importing a Catalog

Creating a Catalog Schema

Creating a Catalog

Pricing Products

Using BizTalk Server


Importing a Catalog

You use the Catalog Editor module to import catalogs from external sources that are in either Extensible Markup Language (XML) or comma-separated values (CSV) file formats. By importing a catalog you can integrate an existing catalog from another source to your database.

The time required to import a catalog depends on the size of the catalog. Because catalogs can be quite large, the import and export processes are asynchronous so you can continue working in other parts of Commerce Server Business Desk while they are running. You can also exit Business Desk and come back to it at another time.

This section contains:

  • Importing an XML Catalog File

  • Importing a CSV Catalog File


Importing an XML Catalog File

A Commerce Server catalog in Extensible Markup Language (XML) file format contains both catalog schema and product data. You can import a Commerce Server catalog XML file, and then use the Catalog Editor to make changes to the product data.

You can copy a catalog that resides on your local computer to the CommerceCatalogs shared folder on the server. Use Windows Explorer to copy your file to the shared folder. If you use the CommerceCatalogs share, you do not have to specify the complete path and file name during the import process.

Note

  • Contact your system administrator to ensure that the CommereCatalogs shared folder exists on the server.

To import an XML catalog file

  1. In Catalogs, click Catalog Editor.

  2. In the Catalogs screen, click Import on the toolbar, and then select Import XML from the drop-down list.

  3. In the Import XML Catalog dialog box, do the following:
    Use this | To do this
    Filename | Type the complete path and file name for the catalog you want to import or, if the file is in the CommerceCatalogs share on your server, type only the name of the file. For example, type SportsCatalog.xml if this file is in the CommerceCatalogs share on your server. If the file is in any other folder, you must type the full file name and path to the catalog you want to import, for example, type C:\CatalogsforBusiness\SportsCatalogs.xml.
    Delete any existing catalog data | If you are importing a catalog that already exists in your Commerce Server database, select this check box to delete the data from the existing catalog before importing the new version.

  4. Click OK.

Notes

  • You cannot import a catalog that contains a product definition with different properties than an existing product definition of the same name.

  • To determine the status of the import process, ask your system administrator to check the Event Viewer. If there was a problem with the import process, an error will be listed in the Application Log of the viewer. If the import process is successful, the catalog appears in the Catalog Editor list.

Now that you have imported a Commerce Server catalog XML file, you can publish the new catalog to your Web site. For information about publishing changes to your Web site, see Refreshing and Publishing a Catalog.

See Also

About Catalogs

Refreshing and Publishing a Catalog

Importing a CSV Catalog File


Importing a CSV Catalog File

A comma-separated values (CSV) catalog file contains product data, but does not contain catalog schema. The products are not organized into categories, and all the products in a CSV catalog file are mapped to a single product definition. The CSV catalog file must have a product identifier and a price column. CSV catalog files only contain stand-alone products, and do not support product variants. The string data type is the only data type supported by a CSV catalog file. For more information about string data types, contact your system administrator.

When a CSV catalog file is imported, a product definition is automatically created based on the columns listed in the file. Each product is imported as an instance of the product definition that was automatically created. The product definition is given the same name as the catalog being imported.

After importing a CSV catalog file, you can use the Catalog Editor to create categories and add products to the categories.

To import a CSV catalog file

  1. In Catalogs, click Catalog Editor.

  2. In the Catalogs screen, click Import on the toolbar, and then select Import CSV from the drop-down list.

  3. In the Import CSV Catalog dialog box, do the following:
    Use this | To do this
    File name | Type the complete path and file name for the catalog you want to import or, if the file is in the CommerceCatalogs share on your server, type only the name of the file. For example, type SportsCatalog.csv if this file is in the CommerceCatalogs share on your server. If the file is in any other folder, you must type the full file name and path to the catalog you want to import, for example, type C:\CatalogsforBusiness\SportsCatalogs.csv.
    Catalog name | Type a name for the imported catalog. This name will also be used for the product definition created during the import process.
    Product identifier | Type the name of the identifier column.
    Price column | Type the name of the price column.
    Delete any existing data in this catalog | If you are importing a catalog that already exists in your Commerce Server database, select this check box to delete the catalog data from the existing catalog before importing the new version.

  4. Click OK.

Notes

  • Importing a catalog with the same name as a product definition will overwrite the original product definition.

  • You cannot import a catalog that contains a product definition with different properties than an existing product definition of the same name.

  • To find the status of the import, ask your system administrator to check the Event Viewer. If there was a problem with the import process, an error will be listed in the Application Log of the viewer. If the import process is successful, the catalog appears in the Catalog Editor list.

See Also

About Catalogs

Importing an XML Catalog File

Adding a Category to a Catalog

Adding a Product to a Catalog


Creating a Catalog Schema

If you decide to create your own catalog instead of importing one, you must first create the catalog schema. After you create the catalog schema, you can add categories, products, and properties to the catalog. For an example of how to create both a catalog schema and a catalog, see Creating a Catalog in the Commerce Server Business Desk Tutorial.

This section contains:

  • Adding a Property Definition

  • Adding a Product Definition

  • Adding a Category Definition


Adding a Property Definition

A property definition specifies a single characteristic of a category definition or a product definition in your catalog. One property definition can be used by multiple category definitions and production definitions, and it can be shared across catalogs. For example, the property definition "Description" can be used in every product definition and category definition for adding descriptions to categories and products.

After you create the property definition, you can add it to a category definition or a product definition.

To add a property definition

  1. In Catalogs, click Catalog Designer.

  2. In the Catalog Designer: Category Definitions screen, click View on the toolbar, and then select Property Definitions from the drop-down list.

  3. In the Catalog Designer: Property Definitions screen, click Add on the toolbar, and then select the property type that you want to use to create a new property definition.

    The boxes that appear in the Catalog Designer: Property Definitions screen depend on the type of property definition you have selected.

  4. In the Property Definitions screen, do the following:
    Use this | For property type | To do this
    Name All Type a name for the property.

    Note

    After you save this property, you cannot change the property name.

    Display on site | All | Select this check box to display the specified property to users on your Web site. If you want to keep some properties private for internal use, do not select this check box.
    Display name | All | Type the name that is to be displayed on the Web site as a label for this property. For example, for a property named "ShirtColor," you may want the label to be "Color."
    Free text searchable Text, multiple choice Select this check box so that free text searching on your catalog will apply to values stored in this property.

    When you select the Free text searchable option, the property definition is added to the full index for the catalog. You must update the full text index after changing items in your catalogs that are marked as searchable. For information about updating the full text index, see Refreshing and Publishing a Catalog.
    Specification searchable | Text, number, decimal, money/currency, date/time, multiple choice | Select this check box in order for this property to be used in specification searches. A specification search enables users to select the values of interest to them that help them find particular products.
    Minimum length | Text | Type the number that defines the minimum length of the value for this property type. The default minimum length is zero (0) characters. If you specify a length other than zero, this property becomes a required property for a product or category definition.
    Maximum length | Text | Type the number that defines the maximum length of the value for this property type. The maximum allowed length is 3600 characters.
    Minimum value | Number, decimal, money/currency | Type the number that defines the minimum value for this property. The default minimum value is zero (0).
    Maximum value | Number, decimal, money/currency | Type the number that defines the maximum value for this property type. For example, to add a property for money, enter a number including the decimal point and any fractional amount that could accommodate the greatest monetary value to be applied to a product.
    Earliest date | Date/time | Type the date to indicate the earliest date that you want this property to be valid. For example, the earliest date users can order a new record.
    Earliest time | Date/time | Type the time in 00:00 format (for example, 13:00 is 1 P.M.) to indicate the earliest time that you want this property to be valid. For example, a start time.
    Latest date | Date/time | Type the date to indicate the latest date that you want this property to be valid. For example, the latest date users can order a promotional product.
    Latest time | Date/time | Type the time in 00:00 format (for example, 22:00 is 10 P.M.) to indicate the latest time that you want this property to be valid. For example, an expiration time.
    Default value | Text, number, decimal, money/currency, date/time, multiple choice | Type in the default value for the property type. The format varies depending on the property type you are adding.
    Assign to all product definitions | All | Select this check box to assign the property to all product types. Do this for generic product properties such as name, description, or weight.
    Export to Data Warehouse | All | Select this check box to export the property to the Data Warehouse. Exporting to Data Warehouse makes data available for reporting purposes.
    Display in products list | All | Select this check box to display this property in the products list.

  5. To save the property definition and return to the Catalog Designer: Property Definitions screen, click Save and go back on the toolbar.

You can now add the property definition to a category definition and/or a product definition.

Notes

  • If you select the Assign to all product definitions option, any future definitions you create will automatically inherit this property.

  • You cannot use the following special characters in the name of a property definition: arrows < >, ampersand &, or parentheses ().

  • A property name cannot start with a number.

See Also

About Catalogs

Adding a Product Definition

Adding a Category Definition


Adding a Product Definition

All products in your catalog are instances of product definitions. A product definition specifies the properties for a particular type of product. For example, an online music retailer may have a product definition for the product type, "Compact Disks" that contains the properties Artist, Title, and List Price.

After you create a product definition, you can add instances of this product definition to a catalog

The following instructions assume you have already created the property definitions that you want to add to your product definition. However, you can also create property definitions when you are adding a product definition. For more information about creating property definitions, see Adding a Property Definition.

To add a product definition

  1. In Catalogs, click Catalog Designer.

  2. In the Catalog Designer: Category Definitions screen, click View on the toolbar, and then select Product Definitions from the drop-down list.

  3. In the Catalog Designer: Product Definitions screen, click Add on the toolbar.

  4. In the Product Definitions: New screen, type a name for the new product definition in the Name box.

  5. In the Product Properties section, select, from the list of Available Properties, the property or properties you want for the new product definition and then click Add.

    The selected properties appear in the Assigned Properties box in the Product Properties section.

    Click the illustration to enlarge or reduce.

    Note

    • Some properties may have the assign to all attribute set. This means that each product definition automatically contains that property and it will be shown as already assigned and highlighted in yellow. If you try to remove one of these properties from the product definition it will automatically be added back to the Assigned properties box when you save the product properties. The list price property is a built-in property; all products have this property.
  6. If the new product has variants, in the Product Variant Properties section, select the property or properties you want from the Available Properties list, and then click Add.

    The selected properties appear in the Assigned Properties box.

    Note

    • The order in which the properties appear in the Assigned Properties box is also the order in which the properties are displayed in the catalog. You can adjust the order of the properties by selecting the property you want to move within the box, and then clicking either Move Up or Move Down until the property is in the position you want.
  7. To save the product definition and return to the Catalog Designer: Product Definition screen, click Save and go back on the toolbar.

After you have created your property definitions, product definitions, and category definitions, you can create a catalog and add categories and products to it. For instructions, see Creating a Catalog.

See Also

About Catalogs

Adding a Property Definition

Adding a Category Definition

Creating a Catalog


Adding a Category Definition

A category can have one or more properties, such as name, description, and image. These properties are defined in the category definition.

Commerce Server provides a category definition named Department that you can edit or use the way it is. You can also create other category definitions. The Department category definition includes description, image file name, image width, and image height properties. You can use the Department category definition exclusively, or you can tailor its properties to your business needs. You can also create different types of categories. For example, if you want to be able to store information about manufacturers and organize products by manufacturer, you can create a Manufacturer category definition, which would include different properties, such as Manufacturer Name, Country, Address, and Contact Person.

After you create a category definition, you can create categories based on that category definition.

The following instructions assume you have already created the property definitions that you want to add to your category definition. However, you can also create property definitions when you are adding a category definition. For more information about creating property definitions, see Adding a Property Definition.

To add a category definition

  1. In Catalogs, click Catalog Designer.

  2. In the Catalog Designer: Category Definitions screen, click View on the toolbar, and then select Category Definitions from the drop-down list.

  3. In the Catalog Designer: Category Definitions screen, click Add on the toolbar.

  4. In Category Definitions: New screen, type a name for the new category definition in the Name box.

  5. In the Category Properties section, select the property or properties you want for the new category definition from the list of Available Properties, and then click Add.

    The selected properties appear in the Assigned Properties box in the Category Properties section.

  6. To change the order of the properties, select the property you want to move, and then click either Move Up or Move Down until the property is in the position you want.

    Click the illustration to enlarge or reduce.

  7. To save the new category definition and return to the Catalog Designer: Category Definitions screen, click Save and go back on the toolbar.

After you have created your property definitions, product definitions, and category definitions, you can create a catalog and add categories and products to it. For instructions, see Creating a Catalog.

Note

  • The order in which the properties appear in the Assigned Properties box is also the order in which the properties will be displayed in your catalog.

See Also

About Catalogs

Creating a Catalog


Creating a Catalog

You use the Catalog Editor to create a catalog. If you do not have existing catalogs to import, you can create new catalogs. If the existing catalog schema is not sufficient, you can make the necessary changes to the existing property definitions, category definitions, and product definitions before, or after, creating new catalogs.

Caution

  • When you make changes to the catalog schema, those changes are reflected in the existing catalogs that also use the schema. If you do not want the changes carried over to your existing catalogs, you must create a new definition (property, category, or product) for the new catalog.

This section contains:

  • Creating a New Catalog

  • Creating a Custom Catalog

  • Creating a Catalog Set

  • Adding a Category to a Catalog

  • Adding a Product to a Catalog

  • Adding Product Variants to a Product


Creating a New Catalog

After you or your site developer creates the catalog schema (property definitions, product definitions, and category definitions), you use the catalog schema to create a new catalog.

When you create a new catalog, you specify the currency that will be used to price products (for example, USD), the unique ID that will be used to identify products in the catalog (for example, name of the product), and the unique ID used to identify product variants (for example, stockkeeping unit). The values for these properties depend on your catalog schema. For example, in the catalog schema, you would specify that unique ID is going to be the name of the product.

The following procedure assumes either you have or your site developer has already created your catalog schema. If you have not yet done so, see Creating a Catalog Schema.

Note

  • If you are exchanging this catalog with a vendor using Microsoft BizTalk Server, then you must specify the vendor ID for the catalog.

To create a new catalog

  1. In Catalogs, click Catalog Editor.

  2. In the Catalogs screen, click Add on the toolbar, and then select New Catalog from the drop-down list.

  3. In the Catalog: New screen, in the Catalog Properties section, do the following:
    Use this | To do this
    Name Type a name for the new catalog. This name must be unique; it cannot match the name of any existing catalog in the Commerce Server database. If you use a name that already exists in your database, you will receive an error message when you try to save the catalog name.

    Note

    • If you have two or more Commerce Server sites with separate databases in which catalog data is stored, and the sites are sharing the same Data Warehouse, do not give the same name to the different catalogs for the two different sites. If two catalogs have the same name, the Data Warehouse treats them as one catalog.
    Start date | Type the start date for the catalog. This date does not have any effect on your Web site. However, if you exchange catalogs with a trading partner, this date lets your trading partner know the first date the catalog is valid.
    End date | Type the end date for the catalog. Your trading partners use this date to determine the last date the catalog is valid. By default this will be current date plus three months. For example, if you are creating your catalog in December, the catalog end date will be March.
    Currency | Type the currency abbreviation, up to three characters, such as USD, DM, or FF. The default is USD.
    Unit of weight measure | Displays the unit of weight for the products in this catalog. Your system administrator specifies this value during Commerce Server configuration. Contact your system administrator if this value needs to be changed.
    Product unique ID | Select a unique identifier from the drop-down list. If your products do not have variants, this could be SKU. If your products have variants, this could be Name or Title, and the Product variant unique ID would be SKU. The maximum length of the Product unique ID box is 256 characters.
    Product variant unique ID | Select a unique identifier from the drop-down list for the product variants. For example, this could be SKU or another unique identifier. If your products do not have variants, select the same property here as you selected for the Product unique ID. The maximum length of the Product variant unique ID box is 256 characters.
    Vendor ID This property is only used in conjunction with BizTalk Server. Click the ellipsis button ( ... ) to display a list of vendors that have been identified within the BizDesk Server Messaging Manager. Select the appropriate vendor ID for the vendor who supplies the products for your catalog. If you are using BizTalk Server to send orders to trading partners, you must complete this box.

    Commerce Server updates the list of vendors automatically each time your system administrator creates another agreement with a vendor using BizTalk Server. If you do not see the vendor ID of the vendor you want to select, contact your system administrator to set up an agreement with the vendor.

    For more information about BizTalk Server and Biztalk Server Messaging Manager, contact your system administrator.

  4. To save the catalog and return to the Catalogs screen, click Save and go back on the toolbar.

Now that you have created a catalog, you can now add products and categories to your catalog. For more information, see Adding a Category to a Catalog and Adding a Product to a Catalog.

See Also

About Catalogs

Creating a Catalog Schema

Adding a Product to a Catalog

Adding a Category to a Catalog

Using BizTalk Server


Creating a Custom Catalog

You use the Catalog Editor module to create custom catalogs. You create a custom catalog when you want to assign custom prices to specific categories in the catalog. For example, if you want to discount items for a specific set of users (such as a premier members), but you want to leave the base catalog intact, you can create a custom catalog. By using custom catalogs you can maintain product and category information in one place and offer products at different prices to different users.

After you create a custom catalog, you use the Catalog Sets module to add the custom catalog you just created to one or more catalog sets, and then you use the Users module to associate the catalog set with those users or organizations whom you want to view the catalog.

Note

  • You cannot remove or add new categories and products from or to a custom catalog.

To create a new custom catalog

  1. In Catalogs, click Catalog Editor.

  2. In the Catalogs screen, click Add on the toolbar, and then select New Custom Catalog from the drop-down list.

  3. In the New Custom Catalog dialog box, select the catalog from the drop-down list from which you will create your custom catalog, and then click OK.

  4. In the Custom Catalog – New screen, in the Custom Catalog Properties section, do the following:
    Use this | To do this
    Name | Type a name for the custom catalog.
    Categories | Select the category to which you want apply a custom price.
    Use custom pricing | Select this check box to enable custom pricing.
    Pricing Method Select one of three pricing methods:

    Percentage Adjustment. The percentage of the list price that should be charged for a product.

    Fixed Adjustment. The amount by which the list price is increased or decreased.

    Set Price. The exact price for the product.

    For more information about these pricing methods, see Pricing Products.
    Value | Type the value. The value determines the percentage, the adjustment, or the set price that should be applied to the list price, depending on the Pricing Method you selected. For example, if you select Percentage Adjustment and want to set a 10 percent discount, you would type 90. Items in your custom catalog would then sell for 90 percent of the list price.

  5. To save the custom catalog and return to the Catalog screen, click Save and go back on the toolbar.

  6. In the Catalog Editor screen, the custom catalog is listed under the catalog you used as a base catalog. Click the arrow to the left of the base catalog to view the custom catalog.

Now that you have created a custom catalog, you can add it to one or more catalog sets. For more information about adding catalogs to catalog sets, see Creating a Catalog Set. For information about associating a user with a catalog set, see Adding a User.

See Also

About Catalogs

Creating a Catalog Set

Adding a User

Pricing Products

Pricing a Custom Catalog


Creating a Catalog Set

You use catalog sets to create groups of specific catalogs, and then give the group a unique name. For example, if you have a frequent buyers program and you give the members of this program discounts or incentives that you do not give the general public, you can create a catalog set with the custom catalogs in it, and then permit only the members of the program to access these catalogs. If you have some products in separate catalogs that you would like to give access to a few restricted users, you can make that catalog part of a special catalog set that only those users would have access to. You grant users access to the catalogs sets in the Users module.

You do not have to create catalog sets. Catalog sets do not change the individual catalogs.

To create a catalog set

  1. In Catalogs, click Catalog Sets, and then click Add on the toolbar.

  2. In the New Catalog Sets screen, do the following:
    Use this | To do this
    Name | Type a name for the catalog set.
    Description | Type a description for the catalog set.
    Add all catalogs | Select this check box to have this catalog set represent all catalogs, even as new catalogs are added. Do not check this check box if you want to specify individual catalogs for this catalog set.
    Available catalogs Select individual catalogs to add to the catalog set, and then click Add.

    The catalogs you selected move from the Available catalogs box to the Assigned catalogs boxt.
    Assigned catalogs | Display the catalogs added to this catalog set. If you remove a catalog from the Assigned catalogs box, it will automatically move to the Available catalogs box.

  3. To save the catalog set and return to the Catalog Sets screen, click Save and go back on the toolbar.

Now that you have created a catalog set, you can add users that will have access to the catalog set. For information about adding users, see Adding a User.

See Also

About Catalogs

Adding a User

Changing a Catalog Set

Deleting a Catalog Set


Adding a Category to a Catalog

You add a category to a catalog using the Catalog Editor module. When you add products to a catalog, you may discover you need to add a new category.

Category names must be unique in each catalog. If you imported a catalog in CSV file format, you need to create the categories for the catalog and assign products to them.

Note

  • You cannot add new categories to a custom catalog.

To add a new category

  1. In Catalogs, click Catalog Editor.

  2. In the Catalogs screen, select the catalog for which you want to create a new category, and then click Open on the toolbar.

  3. In the Catalog - <Catalog Name> screen, in the Categories section, click New.

  4. In the New Category dialog box, select the category definition you want to base the category on, and then click Continue.

  5. In the Catalog Editor – <Catalog Name> - new (category) screen, do the following:
    Use this | To do this
    Name Type a name for the new category. The maximum length is 100 characters.

    Note

    Do not use arrows < >, or parentheses () in the Name field.

    Price | Type a price for the category. Use this box to assign prices to all the products in this category. For information about assigning prices directly to the product or the product variant, see Pricing Products.
    Searchable | Select this check box to have this category be a starting point for a specification search. If this box is checked then this category will be listed on the Advanced Search page on the Web site.

    Note

    • Other boxes may appear on the screen depending on the category definition you select.
  6. To save the new category and create another new category, click Save and create new on the toolbar.

Note

  • You can also assign parent and child categories, and establish category relationships on this screen. For more information, see Creating Category and Product Relationships and Creating Category Hierarchies.

See Also

About Catalogs

Refreshing and Publishing a Catalog

Pricing Products

Adding a Category Definition


Adding a Product to a Catalog

You add new products to existing catalogs using the Catalog Editor. You cannot, however, add new products to a custom catalog.

These instructions assume you or your site developer has already created product definitions for the products you want to add to the catalog. In addition, they assume you have already created a catalog and added one or more categories. If you have not yet done so, see Adding a Product Definition, Creating a Catalog, and Adding a Category to a Catalog.

To add a new product to a catalog

  1. In Catalogs, click Catalog Editor.

  2. In the Catalogs screen, select the catalog to which you want to add a new product, and then click Open on the toolbar.

  3. In the Catalog - <Catalog Name> screen, in the Products section, click New.

  4. In the New Product dialog box, select the product definition you want for this product, and then click OK.

    Note

    • The options available for product properties and product variants depend on the criteria you establish and the type of product you are adding.
  5. In the Catalog Editor - <Catalog Name> new (product) screen, in the Product Properties section, enter the information for the available properties.

  6. In the Catalog Editor - <Catalog Name> new (product) screen, in the Product Variants section, click New, and then enter the information for the available properties.

  7. In the Catalog Editor - <Catalog Name> new (product) screen, in the Product Assigned Categories section, do the following:
    Use this To do this
    Available Categories Select the category you want to assign the product to, and then click Add.

    If you want to remove an assigned category, click Remove.
    Assigned Categories Select the assigned category, and then click Edit if you want to edit the category.

    Click New if you want to create a new category.
    Pricing Category Select the category whose pricing will be applied to the product, and the click Set Pricing.

    To clear the pricing for the selected category, click Clear Pricing.

  8. In the Product Family Relationships section, click New, and then do the following:

    Use this | To do this
    Relationship | Type a name for the relationship.
    Item | Click the ellipse button […] to display the Product Picker dialog box.

    Note

    • If you are creating a product that will have product variants, the price you specify here will be used as the default price for each variant as you add variants. When you create a product variant you can override this default with a different price. For information about adding product variants, see Adding Product Variants to a Product. For information about pricing products, see Pricing Products.
  9. To save the product and to add another product, click Save and create new on the toolbar.

See Also

About Catalogs

Creating Category and Product Relationships

Customizing Shipping Methods


Adding Product Variants to a Product

You can assign product variants to products in your catalog. For example, the product variants for a t-shirt might include color and size. A large, blue t-shirt would be one variant of the t-shirt product family. A small, blue t-shirt would be another variant.

Each product variant must have a unique ID. For more information about adding a unique ID to a product variant, see Creating a Catalog.

To add product variants to a product

  1. In Catalogs, click Catalog Editor.

  2. In the Catalogs screen, select the catalog to which you want to add product variants, and then click Open on the toolbar.

  3. In the Catalog Editor - <Catalog Name> screen, in the Products section, select the product to which you want to add product variants, and then click Edit.

  4. In the Catalog Editor - <Catalog Name> (product) screen, in the Product Variants section, click New.

  5. In the Product Variants section, type the price for the product in the Variant price box.

  6. Enter the properties in the boxes including a unique value for the unique identifier property, such as SKU, and then click Done.

    The product variant information appears in the Product Variants table.

  7. To save the changes and return to the Catalog screen, click Save and go back on the toolbar.

See Also

About Catalogs

To create a product relationship

Pricing Products


Pricing Products

You use the Catalog Editor module to price products in your catalog. You can set the price of a product in a catalog using one of three methods: direct pricing, indirect pricing, and custom pricing.

  • Direct pricing. You define the price for a product in the product itself. You can do this either when you create the product or when you edit it to change the price. For information about direct pricing products see Pricing a Product.

  • Indirect pricing. The price is determined by its association with a particular pricing category. When a product is associated with a pricing category, the price on the product is replaced by the price specified in that category. The original price of the product is restored when it is no longer associated with a that particular pricing category. Indirect pricing is typically used when you want to price a group of products the same way, for example, to create a special category where all products are $1.99. For pricing products indirectly, see Pricing at the Product Variant Level and Pricing a Products in a Category.

  • Custom pricing. In a custom catalog you can apply a price modifier to a category. There are three types of custom pricing that you can apply to categories in a custom catalog:
    • Percentage Adjustment. Specifies the percentage of the list price that should be charged for a product. For example, to apply a 10 percent discount, you would type 90, indicating that the product is selling for 90 percent of the list price.

    • Fixed Adjustment. Specifies the exact amount to either increase or discount the list price. For example, to take $2.00 off the price, you would type –2, indicating that the product is selling for $2.00 less; to increase the cost by $2.00, type 2, indicating that it is selling for $2.00 more.

    • Set Price. Specifies the exact price of the product. For example, the product is selling for exactly $10. This would override the price specified on the product itself.

    For information about custom pricing products in your catalog, see Pricing a Custom Catalog.

The price modifier specified on each category applies to all products in each category. If a product belongs to two categories with conflicting price modifiers, the price of the product will not be changed and a warning message will be written to the Application log in Windows Event Viewer to indicate this conflict.

To discount a product price, you create a discount campaign item. For information about discounting products, see Creating a Discount Campaign Item.

This section contains:

  • Pricing a Product

  • Pricing at the Product Variant Level

  • Pricing a Products in a Category

  • Pricing a Custom Catalog


Pricing a Product

You set prices of products while creating product properties. However, you can also change prices for your products whenever you receive a notification of a price change. For example, if the price of a black leather jacket increases from $399 to $429 you can make that change in the product properties.

Note

  • To temporarily change the price of a product for a special occasion, you can discount the product. A discount can be set for a specific time period and for a restricted set of users. For more information about setting up discounts, see Discounting Product Prices.

To price a product

  1. In Catalogs, click Catalog Editor.

  2. In the Catalogs screen, select the catalog that contains the product you want to price, and then click Open on the toolbar.

  3. In the Catalog - <Catalog Name> screen, in the Products section, select the product that you want to price from the products table, and then click Edit.

  4. In the Catalog Editor - <Catalog Name> (product) screen, in the Product Properties section, type a new price for the product in the Price box.

  5. To save your changes and return to the Catalog screen, click Save and go back on the toolbar.

See Also

Pricing at the Product Variant Level

Pricing Products in a Category

Pricing a Custom Catalog

Creating a Discount Campaign Item


Pricing at the Product Variant Level

You can set different prices for each product variant in a product family. You can also edit variant prices after setting them to reflect market trends. For example, assume you have a product family of Jackets that contains product variants for black jackets and brown jackets. You run a report to analyze sales, and you determine that black jackets are selling better than the brown jackets. You can use this information to lower the price of the brown jackets at the variant level to increase their sales, but keep the price of the black jackets the same.

To assign variant-level pricing

  1. In Catalogs, click Catalog Editor.

  2. In the Catalogs screen, select the catalog that contains the product you want to price, and then click Open on the toolbar.

  3. In the Catalog - <Catalog Name> screen, in the Products section, select the product that you want to price from the products table, and then click Edit.

  4. In the Catalog - <Catalog Name> (product) screen, in the Product Variants section, select the variant you want to edit and change the price in the Variant Price box.

  5. To save your changes and return to the Catalog Editor screen, click Save and go back on the toolbar.

See Also

Pricing a Product

Pricing Products in a Category

Pricing a Custom Catalog

Creating a Discount Campaign Item


Pricing Products in a Category

You can set a single price for all the products in the same category. This is useful, for example, when a range of products fall in the same pricing range. You can use this to change the price for the whole group of products in one place instead of changing each product price individually.

To assign a single price to a group of products

  1. In Catalogs, click Catalog Editor.

  2. In the Catalogs screen, select the catalog that contains the product you want to price, and then click Open on the toolbar.

  3. In the Catalog - <Catalog Name> screen, in the Categories section, select the category that you want to price, and then click Edit.

  4. In the Catalog Editor - <Catalog Name> - <Category Name> screen, Category Properties section, type the price in the Price box.

  5. Click Save and go back to save your change to the category and return to the Catalog - <Catalog Name> screen.

  6. In the Catalog - <Catalog Name> screen, in the Products section, select a product from the category you just priced, and then click Edit.

  7. In the Catalog Editor - <Catalog Name> (product) screen, in the Assigned Categories section, select the category that defines the price for this product from the list of categories in the Assigned Categories box, and then click Set Pricing.

    The category name you selected appears in the Pricing category box, as shown in the following figure.

    Setting the Category Price for a product

    Click the illustration to enlarge or reduce.

    To save the pricing and return to the Catalog screen, click Save and go back on the toolbar.

Notes

  • You must assign a pricing category for each item in the category that was assigned a price at the product level (steps 6 through 8). For example, if you assigned the product a price of $24.99 to an audio CD when you created it, and you want that CD to be in budget category of $20, you must assign that audio CD to the budget category in order for the new price to take effect.

  • Assigning a price at the category level will override prices of all the products and product variants in that category.

See Also

Pricing a Product

Pricing a Custom Catalog

Creating a Discount Campaign Item


Pricing a Custom Catalog

You can add custom pricing to your custom catalogs. You can offer a set price, fixed adjustment, or percentage adjustment in you custom pricing for selected users. For example, you can offer discounts to frequent customers or offer discounts on seasonal merchandise. You can only change the price at the category level. You cannot change the price at the product level or product variant level for a custom catalog.

This procedure assumes you have already created a custom catalog. If you have not yet done so, see Creating a Custom Catalog.

To assign custom catalog pricing

  1. In Catalogs, click Catalog Editor.

  2. In the Catalogs screen, select the custom catalog that you want to price, and then click Open on the toolbar.

  3. In the Catalog Editor - <Catalog Name> screen, in the Custom Pricing section, do the following:
    Use this | To do this
    Categories | Select the category to which you want to apply a custom price.
    Use Custom Pricing | Select this check box to enable custom pricing. Clearing this box will remove custom pricing if the selected category already has custom pricing.
    Pricing Method Select one of three pricing methods:

    Percentage Adjustment. The percentage of the list price that should be charged for a product.

    Fixed Adjustment. The amount by which the list price is increased or decreased.

    Set Price. The exact price for the product.
    Value | Type the value. The value determines the percentage, the adjustment, or the set price that should be applied to the list price, depending on the Pricing Method you selected. For example, if you select Percentage Adjustment and want to set a 10 percent discount, you would type 90. Items in your custom catalog would then sell for 90 percent of the list price.

  4. To save your changes return to the Catalogs screen, click Save and go back on the toolbar.

The updated pricing will not be applied to your Web site until the custom catalog is published. For information about publishing your catalog, see Refreshing and Publishing a Catalog. For information about adding users, see Adding a User.

See Also

About Catalogs

Creating a Custom Catalog

Pricing at the Product Variant Level

Pricing a Product

Pricing Products in a Category

Creating a Discount Campaign Item


Discounting Product Prices

You can apply discounts to individual products, all the products in a category, or you can create an expression to discount products that meet specific criteria. For example, you can create discounts to apply in the following situations:

  • Price of product is greater than $20.00. This is a discount condition expression. Discount condition expressions are based on a product property.

  • User buys 2. This is part of a required discount condition criteria.

  • User clicks a discount ad on the Sports page. This is the click-required part of a discount.

  • User is registered. This is a discount eligibility expression. Discount eligibility expressions are based on user profiles and context profiles.

You cannot apply multiple discounts to one product simultaneously. A customer can enjoy

To discount a product price, you create a discount campaign item. For information about discounting products, see Creating a Discount Campaign Item.


Creating Category Hierarchies

You use the Catalog Editor module to create category hierarchies. Creating category hierarchies helps organize products in your catalog and makes navigation on your Web site easier for your users. You can assign parent categories and child categories, as well as arrange products in a hierarchical manner. For example, the category CDs can have the child categories Rock, Rhythm and Blues, and Classical. The child categories can also contain child categories of their own. For example, the category Rock can contain the child categories Pop and Alternative.

To assign parent and child categories

  1. In Catalogs, click Catalog Editor.

  2. In the Catalogs screen, select the catalog containing the categories that you want to assign parents or child categories to, and then click Open on the toolbar.

  3. In the Catalog - <Catalog Name> screen, in the Categories section, select the category to which you want to assign parents or child categories, and then click Edit.

  4. In the Assigned Categories section, select the category you want to assign as a child from the list in the Available Child Categories box, and then click Add.

    The category moves from the list in the Available box to the list in the Assigned Child Categories box.

  5. To save the parent and child assignments and return to the Catalog screen, click Save and go back on the toolbar.

    Note

    • You can also assign child categories to a child category; this creates multiple levels of nesting.

See Also

About Catalogs

Creating Category and Product Relationships


Creating Category and Product Relationships

You use the Catalog Editor module to create category and product relationships. Categories and products can be related to other categories and products. For example, in a product-to-product relationship, if you have a user who buys a movie, you may want to offer them the soundtrack to the movie. This is an explicit relationship.

In a category-to-category relationship, you can have a relationship between categories. For example, you may have categories for CDs and Biographies. If you have CDs by classical composers, you may have biographies of classical composers as well.

The steps for creating a product family relationship are the same as those for creating a product relationship; however, a product family relationship is created for products with variants.

Note

  • Commerce Server Solution Sites do not display relationships. If your site developer used a Solution Site to build your site, you may not be able to create category and product relationships. For information about displaying relationships on your Web site, contact your site developer.

To create a category relationship

To create a product relationship

To create a category relationship

  1. In Catalogs, click Catalog Editor.

  2. In the Catalogs screen, select the catalog in which you want to create a relationship, and then click Open on the toolbar.

  3. In the Catalog - <Catalog Name> screen, in the Categories section, select the category to which you want to add a relationship, and then click Edit.

  4. In the Catalog Editor - <Catalog Name> (category) screen, in the Category Relationships section, click New, and then do the following:
    Use this | To do this
    Relationship | Type the name of the relationship.
    Item | Click the ellipsis button ( ... ) to open the Product Picker dialog box.

  5. In the Product Picker dialog box, select the category from the Categories list to which you want to create a relationship, and then click OK.

    The category you chose appears in the Item box of the Category Relationships section. In the following figure, "Category" appears in theItem Type box indicating that it is a category relationship.

    Establishing Category Relationships

    Click the illustration to enlarge or reduce.

  6. Click Accept to save the category relationship.

  7. To save the changes and return to the Catalog screen, click Save and go back on the toolbar.

To create a product relationship

  1. In Catalogs, click Catalog Editor.

  2. In the Catalogs screen, select the catalog that contains the product for which you want to create a relationship, and then click Open on the toolbar.

  3. In the Catalog - <Catalog Name> screen, in the Products section, select the product to which you want to add a relationship, and then click Edit.

  4. In the Catalog Editor - <Catalog Name> (product) screen, in the Product Relationships section, do the following:
    Use this | To do this
    Relationship | Type the name of the relationship.
    Item | Click the ellipsis button ( ... ) to open the Product Picker dialog box.

  5. In the Product Picker dialog box, select a category from the Categories list, select a product from the Products in Category list, and then click OK.

    The category you chose appears in the Item box in the Product Relationships section. Product appears in theItem Type box indicating that it is a product relationship.

  6. Click Accept to save the product relationship.

  7. To save your changes and return to the Catalog Editor - <Catalog Name> screen, click Save and go back on the toolbar.


Refreshing and Publishing a Catalog

You use the Catalog Editor module to update your site with new information that you have added to your Web site. In most e-commerce businesses, these changes are first made to a test site, and then at a scheduled times, the changes are published to a production site. Contact your system administrator for information about when and how changes are made to your production site.

Use the Catalog Editor module to refresh and publish a catalog on your Web site. You will have to refresh and publish your catalog whenever you make any change in order to ensure that changes are reflected on your Web site.

To refresh and publish your catalogs

  1. In Catalogs, click Catalog Editor.

  2. In the Catalogs screen, click Publish a catalog on the toolbar.

Your updated catalogs are published on your Web site, and then all catalog caches are refreshed.


Sending a Catalog to a Trading Partner

You use the Catalog Editor module to send a catalog to a trading partner. Trading partners are set up using BizTalk Messaging Manager; they must be set up before you can send them a catalog. For information about setting up your site to send catalogs to trading partners, contact your system administrator.

To send a catalog to a trading partner

  1. In Catalogs, click Catalog Editor.

  2. In the Catalogs screen, select the catalog you want to send, and then click Send on the toolbar.

  3. In the Select Vendor dialog box, select the trading partner(s) the catalog is going to, and then click OK.

See Also

Using BizTalk Server

Exporting a Catalog


Exporting a Catalog

You can export a catalog to a known path or a shared folder called CommerceCatalogs on the computer on which Commerce Server is installed. Exporting a catalog can make your catalog portable. For example, you can share your catalog with your business partner, or outsource development and maintenance of your catalogs.

To export a catalog you must have a shared folder on the Commerce Server computer available to you. Contact your system administrator to set up a shared folder for you.

Catalogs can be exported in either Extensible Markup Language (XML) or comma-separated values (CSV) file format.

To export a catalog

  1. In Catalogs, click Catalog Editor.

  2. In the Catalogs screen, select the catalog you want to export, and then click Export on the toolbar.

  3. Select whether you want to export the catalog in XML or CSV file format from the drop-down list.

  4. In the Export Catalog dialog box, type the complete path and file name of a catalog that can be written to by the server in the Export File box (such as, C:\CatalogsforBusiness\SportsCatalog.xml), and then click Continue.

    If you are exporting to the CommerceCatalogs shared folder on which you have Commerce Server installed, you do not need to specify the complete path. For example, you can type, SportsCatalogs.xml.

The catalog is exported to the specified location, from which you can copy it and use it elsewhere.

See Also

About Catalogs

Sending a Catalog to a Trading Partner

Importing a Catalog


Managing Catalog Schema

As your business needs change, you may also need to change your catalog schema. You can add new property definitions, edit existing property definitions, or delete property definitions that you no longer need. You can also change or add new product and catalog definitions.

When you make changes to the catalog schema, these changes can affect existing categories and products that are associated with the property definitions you are changing or deleting. For example, if you need to add a vendor ID to your CD product definition, all product instances that use the CD product definition will include a box for vendor ID.

This section contains:

  • Finding and Viewing Catalog Schema

  • Changing Catalog Schema

  • Copying Catalog Schema

  • Deleting Catalog Schema


Finding and Viewing Catalog Schema

You use the Catalog Designer module to find and view property definitions, category definitions, and product definitions.

To find a property definition

To view a list of property definitions

To view a list of category definitions

To view a list of product definitions

To find a property definition

  1. In Catalogs, click Catalog Designer.

  2. In the Catalog Designer: Category Definitions screen, click View on the toolbar, and then select Property Definitions from the drop-down list.

  3. In the Catalog Designer: Property Definitions screen, click Find to display the Find box.

  4. In the Look for box, select the property definition characteristics from the drop-down list and do the following:
    Use this | To do this
    Name | Type the name (or part of the name) of the property.
    Type | Select the property type from the drop-down list.
    Assigned to All Product Types | Select Yes or No from the drop-down list. Selecting Yes indicates to search only those properties that are common to all product types.
    All Definitions | Search all existing definitions.

    Note

    • If you select All Definitions, the Search only the list below box option is made unavailable, all the filters are removed, and all the definitions are verified.
  5. Click Find Now.

    The results of your search appear in a list box below the Find box.

To view a list of property definitions

  1. In Catalogs, click Catalog Designer.

  2. In the Catalog Designer: Category Definitions screen, click View on the toolbar, and then select Property Definitions to display the Catalog Designer: Property Definitions screen.

    This screen displays a list of all the property definitions (in alphabetical order) and their data type in your catalog.

To view a list of category definitions

  • In Catalogs, click Catalog Designer to display the Catalog Designer: Category Definitions screen.

    This screen displays a list of all the category definitions in your catalog.

To view a list of product definitions

  1. In Catalogs, click Catalog Designer.

  2. In the Catalog Designer: Category Definitions screen, click View on the toolbar, and then select Product Definitions to display the Catalog Designer: Product Definitions screen.

    This screen displays a list of all the product definitions in your catalog.


Changing Catalog Schema

You use the Catalog Designer module to change your catalog schema. You can change your catalog schema if you create a new catalog or update an existing catalog. When you make changes to the schema for a new catalog, you should make your changes before adding products and categories to the catalog.

You can make changes to the schema after you have populated the catalog with products and categories, but these changes can affect the catalog that users see on your Web site. In many organizations, a person who understands the database concepts creates the catalog schema.

To change a category definition

To change a product definition

To change a property definition

Note

  • You cannot change the name or type of property in a catalog schema. You can delete the property, and then add it again using a new name and type.

To change a category definition

  1. In Catalogs, click Catalog Designer.

  2. In the Catalog Designer: Category Definitions screen, click View on the toolbar, and then select Category Definitions from the drop-down list.

  3. Select the category you want to change, and then click Open on the toolbar.

  4. In the Category Definitions screen, in the Category Properties section, select the property you want to change in the Assigned Properties box, and then do one of the following:
    • To add a property to a category definition, select the property you want to add from the Available Properties box, and then click Add. You can create a property by clicking New if the property does not exist.

    • To remove a property from a category definition, select the property you want to remove from the Assigned Properties box, and then click Remove.

    • To change the order of the properties assigned to a category, select the property you want to move in the Assigned Properties box, and then click either Move Up or Move Down to change the property order.
  5. To save your changes and return to the Catalog Designer: Category Definitions screen, click Save and go back on the toolbar.

To change a product definition

  1. In Catalogs, click Catalog Designer.

  2. In the Catalog Designer: Category Definitions screen, click View on the toolbar, and then select Product Definitions from the drop-down list.

  3. Select the product definition you want to change, and then click Open on the toolbar.

  4. In the Catalog Designer: Product Definition screen, in the Product Properties section, select the property you want to change in the Assigned Properties box, and then do one of the following:
    • To add a property to a product definition, select the property you want to add from the Available Properties box, and then click Add. You can create a property by clicking New if the property does not exist.

    • To remove a property from a product definition, select the property you want to remove from the Assigned Properties box, and then click Remove.

    • To change the order of the properties assigned to a product, select the property you want to move in the Assigned Properties box, and then click either Move Up or Move Down to change the property order.
  5. To save your changes and return to the Catalog Designer screen, click Save and go back on the toolbar.

To change a property definition

  1. In Catalogs, click Catalog Designer.

  2. In the Catalog Designer screen, click View on the toolbar, and then select Property Definition from the drop-down list.

  3. In the Property Definitions screen, select the property you want to change, and then click Open on the toolbar.

  4. In the Property Definitions - <Property Name> screen, do the following:
    Use this | For property type | To do this
    Name | All | You cannot change this property.
    Display on site | All | Select this check box to display the specified property to users on your Web site.
    Display name | All | Type the name that is to be displayed on the Web site as a label for this property. For example, for a property named "ShirtColor," you may want the label to be "Color."
    Free text searchable Text, multiple choice, file Select this check box so that free text searching on your catalog will apply to values stored in this property.

    When you select the Free text searchable option, the property definition is added to the full index for the catalog. You must update the full text index after changing items in your catalogs that are marked as searchable. For information about updating the full text index, see Refreshing and Publishing a Catalog.
    Specification searchable | All | Select this check box in order for this property to be used in specification searches. A specification search enables users to select the values of interest to them that help them find particular products.
    Minimum length | Text | Type the number that defines the minimum length of the value for this property type. The default minimum length is zero (0) character. If you specify a length other than zero, this property becomes a required property for product or category definition.
    Maximum length | Text | Type the number that defines the maximum length of the value for this property type. The maximum allowed length is 3600 characters.
    Minimum value | Number, decimal, money/currency | Type the number that defines the minimum value for this property. The default minimum value is zero (0).
    Maximum value | Number, decimal, money/currency | Type the number that defines the maximum value for this property type. For example, to add a property for money, enter a number including the decimal point or a comma and any fractional amount that could accommodate the greatest monetary value to be applied to a product.
    Earliest date | Date/time | Type the date for the earliest date that is to be associated with the property. For example, the earliest date users can order a new record.
    Earliest time | Date/time | Type the time in 00:00 format for the earliest time that is to be associated with the property. For example, a start time.
    Latest date | Date/time | Type the date for the latest date that is to be associated with the property. For example, the latest date users can order a promotional product.
    Latest time | Date/time | Type the time in 00:00 format that is to be associated with the latest time for the property. For example, an expiration time.
    Default value | Text, number, decimal, money/currency, date/time, multiple choice | Type in the default value for the property type. This value varies depending on the property type you are adding.
    Assign to all product types | All | Select this check box to assign the property to all product types. Do this for generic product properties such as name, description, or weight.
    Export to Data Warehouse | All | Select this check box to export the property to the Data Warehouse. Exporting to the Data Warehouse makes data available for reporting purposes.
    Display in products list | All | Select this check box to display this property in the products list.

  5. To save your changes and return to the Catalog Designer screen, click Save and go back on the toolbar.


Copying Catalog Schema

You use the Catalog Designer module to copy an existing property definition, product definition, or category definition. For example, you may want to copy a definition to create a new definition that is similar to it.

To copy a category definition

To copy a product definition

To copy a property definition

To copy a category definition

  1. In Catalogs, click Catalog Designer.

  2. In the Catalog Designer: Category Definitions screen, click View on the toolbar, and then select Category Definitions from the drop-down list.

  3. In the Catalog Designer: Category Definitions screen, select the category you want to copy, and then click Copy on the toolbar.

  4. In Category Definition: New screen, in the Name box, type a name for the new category definition. The maximum length 128 characters.

  5. Edit the properties in the Assigned properties box if you need to change the current category properties for the new category definition.

  6. To save the new category definition and return to the Catalog Designer: Category Definitions screen, click Save and go back on the toolbar.

To copy a product definition

  1. In Catalogs, click Catalog Designer.

  2. In the Catalog Designer: Category Definitions screen, click View on the toolbar, and then select Product Definitions from the drop-down list.

  3. In the Catalog Designer: Product Definitions screen, select the product definition you want to copy, and then click Copy on the toolbar.

  4. In the Product Definition Properties section, in the Name box, type a name for the new product definition. The maximum length is 128 characters.

  5. Edit the Assigned properties box if any changes are needed to the current product properties for the new product definition.

  6. To save the new product definition and return to the Catalog Designer: Product Definitions screen, click Save and go back on the toolbar.

To copy a property definition

  1. In Catalogs, click Catalog Designer.

  2. In the Catalog Designer: Category Definitions screen, click View on the toolbar, and then select Property Definitions from the drop-down list.

  3. In the Catalog Designer: Property Definitions screen, select the property you want to copy, and then click Copy on the toolbar.

  4. In the Property Definitions: New screen, do the following:
    Use this | For property type | To do this
    Name All Type a name for the property.

    Note

    After you save this property, you cannot change the property name.
    Display on site | All | Select this check box to display the specified property to users on your Web site. If you want to keep some properties private for internal use, do not select this check box.
    Display name | All | Type the name that is to be displayed on the Web site as a label for this property. For example, for a property named "ShirtColor," you may want the label to be "Color."
    Free text searchable Text, multiple choice, file Select this check box so that free text searching on your catalog will apply to values stored in this property.

    When you select the Free text searchable option, the property definition is added to the full index for the catalog. You must update the full text index after changing items in your catalogs that are marked as searchable. For information about updating the full text index, see Refreshing and Publishing a Catalog.
    Specification searchable | All | Select this check box in order for this property to be used in specification searches. A specification search enables users to select the values of interest to them that help them find particular products.
    Minimum length | Text | Type the number that defines the minimum length of the value for this property type. The default minimum length is zero (0) characters. If you specify a length other than zero, it becomes a required property for the property definition.
    Maximum length | Text | Type the number that defines the maximum length of the value for this property type. The maximum allowedlength is 3600 characters.
    Minimum value | Number, decimal, money/currency | Type the number that defines the minimum value for this property type. The default minimum value is zero (0).
    Maximum value | Number, decimal, money/currency | Type the number that defines the maximum value for this property type. For example, to add a property for money, enter a number including the decimal point or a comma and any fractional amount that could accommodate the greatest monetary value that could be applied to a product.
    Earliest date | Date/time | Type the date to indicate the earliest date that you want this property to be valid. For example, the earliest date users can order a new record.
    Earliest time | Date/time | Type the time in 00:00 format to indicate the earliest time that you want this property to be valid. For example, a start time.
    Latest date | Date/time | Type the date to indicate the latest date that you want this property to be valid. . For example, the latest date users can order a promotional product.
    Latest time | Date/time | Type the time in 00:00 format to indicate the latest time that you want this property to be valid. For example, an expiration time.
    Default value | Text, number, decimal, money/currency, date/time, multiple choice | Type in the default value for the property type. This value varies depending on the property type you are adding.
    Assign to all product types | All | Select this check box to assign this property to all product types.
    Export to data warehouse | All | Select this check box to export this property to the Data Warehouse. Exporting to the Data Warehouse makes data available for reporting purposes.
    Display in products list | All | Select this check box to display this property in the products list.

  5. To save your changes and return to the Catalog Designer: Category Definitions screen, click Save and go back on the toolbar.


Deleting Catalog Schema

You use the Catalog Designer module to delete property definitions, product definitions, and category definitions. Before you delete a definition, verify that the definition is not used by any existing property, product, or category in your catalogs. If you do delete a product or category definition that has products or categories based on it, you will receive a warning message.

To delete a category definition

To delete a product definition

To delete a property definition

To delete a category definition

  1. In Catalogs, click Catalog Designer.

  2. In the Catalog Designer: Category Definitions screen, click View on the toolbar, and then select Category Definitions from the drop-down list.

  3. In the Catalog Designer: Category Definitions screen, select the category definition you want to delete, and then click Delete on the toolbar.

  4. In the Confirm Category Definitions Delete dialog box, click Yes to delete the definition.

To delete a product definition

  1. In Catalogs, click Catalog Designer.

  2. In the Catalog Designer: Category Definitions screen, click View on the toolbar, and then select Product Definitions from the drop-down list.

  3. In the Catalog Designer: Product Definitions screen, select the product definition you want to delete, and then click Delete on the toolbar.

  4. In the Confirm Product Definitions Delete dialog box, click Yes to delete the definition.

To delete a property definition

  1. In Catalogs, click Catalog Designer.

  2. In the Catalog Designer: Category Definitions screen, click View on the toolbar, and then select Property Definitions from the drop-down list.

  3. In the Catalog Designer: Property Definitions screen, select the property definition you want to delete, and then click Delete on the toolbar.

  4. In the Confirm Property Definitions Delete dialog box, click Yes to delete the definition.


Managing Products, Categories, Catalogs, and Catalog Sets

You use the Catalog Editor module to view, find, edit, and delete existing products, categories, catalogs, and catalog sets.

This section contains:

  • Viewing a List of Catalogs

  • Viewing a List of Categories in a Catalog

  • Finding Items in a Catalog

  • Editing Catalog Properties

  • Editing a Category

  • Editing a Product

  • Editing Category Hierarchies

  • Editing Product Variants

  • Changing a Catalog Set

  • Deleting a Category from a Catalog

  • Deleting a Product from a Catalog

  • Deleting a Catalog

  • Deleting a Catalog Set

  • Deleting Product Variants


Viewing a List of Catalogs

You use the Catalog Editor module to view a list of all existing catalogs. By selecting a catalog and clicking the arrow to the left of the catalog name, you can display any custom catalogs that were created using the selected catalog as its base.

To view a list of existing catalogs

  • In Catalogs, click Catalog Editor.

    The Catalogs screen appears containing a list of all existing catalogs.


Viewing a List of Categories in a Catalog

You can view the categories and the category hierarchy for a selected catalog. By viewing the parent and child associations between categories, you can determine where additional categories may be needed, and where some existing categories need to be either changed or deleted. For example, if you want to add a category for music-related videotapes, you can review the list of categories to determine whether or not the new category would be a parent category or if it should be associated with an existing category.

To view a list of categories assigned to a catalog

  1. In Catalogs, click Catalog Editor.

  2. In the Catalogs screen, select the catalog that contains categories you want to view, and then click Open on the toolbar.

    The Catalog - <Catalog Name> screen appears. All categories assigned to the catalog appear in the Categories section.


Finding Items in a Catalog

You use the Catalog Editor module to search a catalog. You can perform the following searches:

  • Property search. You can search for properties that have specific values. For example, Price < $10 and Color = Red. By default, all properties can be used in property searches.

  • Free-text search. When you add property definitions to your catalog, you select the Free text searchable box to specify that they are available for free text search. A free text search is one that retrieves all instances of the property in your catalog. These property definitions are logged into an index. You must update the full text index after changes are made to your catalogs that are marked as searchable. For information about updating the full text index, see Refreshing and Publishing a Catalog.

To find products in a catalog by keyword

To find products in a catalog by property

To find products in a catalog by keyword

  1. In Catalogs, click Catalog Editor.

  2. In the Catalogs screen, select the catalog you want to search, and then click Open on the toolbar.

  3. In the Catalog - <Catalog Name> screen, in the Products section, select Keyword Search from the Search Method drop-down list.

  4. In the Keywords box, type the keyword on which to conduct the search, and then click Find Now.

    The keyword search results appear in the Products table.

To find products in a catalog by property

  1. In Catalogs, click Catalog Editor.

  2. In the Catalogs screen, select the catalog you want to search, and then click Open on the toolbar.

  3. In the Catalog - <Catalog Name> screen, in the Products section, select Search by properties from the Search Method drop-down list, and then click New.

  4. In the Target based upon following conditions table, do the following:
    Use this | To do this
    Select a property here | Select the property type.
    Select an operator here | Select a search operator.

  5. Type the value you want to search on in the last text box.

  6. Click Find Now.

    The search results appear in the Products table.

    Click the illustration to enlarge or reduce.

See Also

Refreshing and Publishing a Catalog


Editing Catalog Properties

You use the Catalog Editor module to edit catalog properties. For example, you can edit the category and property information for a catalog or start and end dates for a specific catalog.

Note

  • You cannot edit the name of a catalog.

To edit catalog properties

  1. In Catalogs, click Catalog Editor.

  2. In the Catalogs screen, select the catalog you want to edit, and then click Open on the toolbar.

    The Catalog - <Catalog Name> screen appears. You can edit any of the properties on this screen that are not assigned by Commerce Server. To save your edits and return to the Catalogs screen, click Save and go back on the toolbar.

After you make your edits, you must refresh and publish your Web site in order for your edits to appear on your site. For information about refreshing and publishing your edits, see Refreshing and Publishing a Catalog.


Editing a Category

You use the Catalog Editor module to edit an existing category in a catalog. For example, you can edit the price assigned to a specific category. This affects the pricing for all products that are associated with this categoryg.

Note

  • You cannot change the name of a category.

To edit a category property

  1. In Catalogs, click Catalog Editor.

  2. In the Catalogs screen, select the catalog from which you want to edit a category, and then click Open on the toolbar.

  3. In the Catalog Editor - <Catalog Name> screen, in the Categories section, select the category you want to edit from the Categories list, and then click Edit.

  4. In the Catalog Editor - <Catalog Name> (category) screen, in the Category Properties section, do the following:
    Use this | To do this
    Description | Type a description of the category property.
    Image_filename | Type the file name of the image used on the Web site for the category.
    Image_width | Type the numeric width (in pixels) of the image.
    Image_height | Type the numeric height (in pixels) of the image.
    Price | Type the category price.
    Searchable | Select this check box to enable users visiting your site to perform searches on your catalog.

  5. If you need to change any of the current category properties, edit the property values in the Assigned properties box.

  6. To save your edits and return to the Catalog - <Catalog Name> screen, click Save and go back on the toolbar.

After you make your edits, you must refresh and publish your Web site in order for your edits to appear on your site. For information about refreshing and publishing your edits, see Refreshing and Publishing a Catalog.


Editing a Product

You use the Catalog Editor module to edit an existing product in a catalog. For example, if you want to edit the picture illustrating a product on your Web site, you can edit the image file name to reflect the new image.

Note

  • You cannot edit the name of a product.

To edit a product

  1. In Catalogs, click Catalog Editor.

  2. In the Catalogs screen, select the catalog you want to edit, and then click Open on the toolbar.

  3. In the Catalog - <Catalog Name> screen, in the Products section, select the product you want to edit from the Products list, and then click Edit.

  4. In the Catalog Editor - <Catalog Name> (product) screen, do the following:
    Use this | To do this
    Description | Type a description for the product property.
    Image_filename | Type the file name of the image used on the Web site for the product.
    Image_width | Type the numeric width (in pixels) of the image.
    Image_height | Type the numeric height (in pixels) of the image.
    Price | Type the product price (if applicable).

    Note

    • The property boxes on the screen can vary depending on the type of product you selected. You can edit the properties on this screen that are not read-only and are not assigned by Commerce Server 2000.
  5. To save the changes and return to the Catalog - <Catalog Name> screen, click on the toolbar. Save and go back

After you make your edits, you must refresh and publish your Web site in order for your edits to appear on your site. For information about refreshing and publishing your edits, see Refreshing and Publishing a Catalog.


Editing Category Hierarchies

You can edit an existing category hierarchy for a selected catalog. If you have two parent categories that are closely related, and one category could logically be subordinate to the other, you can edit the category assignment. For example, if you have parent categories, one named Classical and the other Composers, you can make Composers a child category of Classical.

To edit a category hierarchy

  1. In Catalogs, click Catalog Editor.

  2. In the Catalogs screen, select the catalog containing the category hierarchy you want to edit, and then click Open on the toolbar.

  3. In the Catalog - <Catalog Name> screen, in the Categories section, select the category whose hierarchy you want to edit, and then click Edit.

  4. In the Catalog Editor - <Catalog Name> (category) screen, in the Assigned Categories section, select the category you want to associate this subcategory with from the Categories list.

  5. To save the edited category and return to the Catalog - <Catalog Name> screen, click Save and go back on the toolbar.

After you make your edits, you must refresh and publish your Web site in order for your edits to appear on your site. For information about refreshing and publishing your edits, see Refreshing and Publishing a Catalog.


Editing Product Variants

You use the Catalog Editor module to edit existing product variants. For example, if you are selling t-shirts and you need to change the stockkeeping unit (SKU) number, you can make edit the existing variant for the selected t-shirt.

To edit a product variant

  1. In Catalogs, click Catalog Editor.

  2. In the Catalogs screen, select the catalog from which you want to edit a product variant, and then click Open on the toolbar.

  3. In the Catalog - <Catalog Name> screen, in the Products section, select the product from which you want to edit a product variant, and then click Edit.

  4. In the Catalog Editor: <Catalog Name> (product) screen, in the Product Variants section, select the product variant you want to edit in the Product Variants box.

    Depending on the type of product variant you are editing, different property boxes are available in the Product Variants section.

  5. Edit the properties in the boxes, and then click Done.

  6. To save your edits and return to the Catalog - <Catalog Name> screen, click Save and go back on the toolbar.

After you make your edits, you must refresh and publish your Web site in order for your edits to appear on your site. For information about refreshing and publishing your edits, see Refreshing and Publishing a Catalog.

See Also

Deleting Product Variants

Pricing Products


Changing a Catalog Set

You can make changes to existing catalog sets. By removing or adding catalogs to existing sets, you change the catalogs that are viewable by your users. Changes to the catalog sets do not affect the contents of the individual catalogs.

To change a catalog set

  1. In Catalogs, click Catalog Sets,

  2. In the Catalog Sets screen, select the catalog set you want to change, and then click Open on the toolbar.

  3. In the Catalog Sets screen, change the catalog set properties as needed.

  4. If you need to remove a catalog from the Assigned Catalogs list, click Remove.

    The catalog is moved back to the Available Catalogs list.

  5. To save your changes and return to the Catalogs Sets screen, click Save and go back on the toolbar.

After you make your changes, you must refresh and publish your Web site in order for your changes to appear on your site. For information about refreshing and publishing your changes, see Refreshing and Publishing a Catalog.


Deleting a Category from a Catalog

You use the Catalog Editor module to delete a category from a catalog. When you delete a category from a catalog, any category that is associated with it, by either relationship or hierarchy, is affected. If this category is associated with products through category pricing, those products will be affected when you delete the category. For example, if you want to remove a category called "Just $5" and you have 15 CDs that use this category as their pricing category, these CDs will revert to the price that you assigned to them at the product level once the category is deleted.

To delete a category from a catalog

  1. In Catalogs, click Catalog Editor.

  2. In the Catalogs screen, select the catalog from which you want to delete a category, and then click Open on the toolbar.

  3. In the Catalog - <Catalog Name> screen, in the Categories section, select the category you want to delete, and then click Delete.

    Caution

    • When you delete a category, you are not asked for confirmation before the delete takes place. If you delete a category by mistake you will have to add that category to the catalog again.
  4. To return to the Catalogs screen, click Back on the toolbar.

After you make your changes, you must refresh and publish your Web site in order for your changes to appear on your site. For information about refreshing and publishing your changes, see Refreshing and Publishing a Catalog.

See Also

Adding a Category to a Catalog

Editing a Category


Deleting a Product from a Catalog

You use the Catalog Editor module to delete a product from a catalog. For example, if you have a product in your catalog that you do not have in stock and do not intend to sell any longer, you can remove the product from your catalog.

Note

  • When you delete a product that is part of a product relationship, the relationship is affected.

To delete a product

  1. In Catalogs, click Catalog Editor.

  2. In the Catalogs screen, select the catalog from which you want to delete a product, and then click Open on the toolbar.

  3. In the Catalog - <Catalog Name> screen, in the Products section, select the product you want to delete from the Products list, and then click Delete.

    Caution

    • When you delete a product you are not asked for confirmation before the delete takes place. If you delete a product by mistake you will have to add that product to the catalog again.
  4. To return to the Catalogs screen, click Back on the toolbar.

After you make your changes, you must refresh and publish your Web site in order for your changes to appear on your site. For information about refreshing and publishing your changes, see Refreshing and Publishing a Catalog.

See Also

Adding a Product to a Catalog

Editing a Product


Deleting a Catalog

You use the Catalog Editor module to delete obsolete catalogs.

Caution

  • If you have a custom catalog that uses the catalog you want to delete as a base, the custom catalog will be deleted along with the base catalog it is attached to. If you want to keep the custom catalog, you must export the custom catalog, delete the base catalog, and then import the custom catalog back into your Commerce Server database.

To delete a catalog

  1. In Catalogs, click Catalog Editor.

  2. In the Catalogs screen, select the catalog you want to delete, and then click Delete on the toolbar.

  3. In the Confirm Catalog Delete dialog box, click Yes to delete the catalog.

After you make your changes, you must refresh and publish your Web site in order for your changes to appear on your site. For information about refreshing and publishing your changes, see Refreshing and Publishing a Catalog.

Caution

  • After you delete a catalog you cannot recover it.

  • The catalog will continue to appear on the Web site until you update the site.

See Also

Exporting a Catalog

Creating a New Catalog

Editing Catalog Properties

Changing a Catalog Set

Changing Catalog Schema


Deleting a Catalog Set

If you no longer need an established catalog set, you can delete it. Deleting a catalog set does not affect the catalogs contained in the set; it only deletes the grouping. When you delete a catalog set associated with existing users, the catalog set is no longer associated with those users.

To delete a catalog set

  1. In Catalogs, click Catalog Sets.

  2. In the Catalog Sets screen, select the catalog set you want to delete, and then click Delete on the toolbar.

  3. In the Confirm Catalog Set Delete dialog box, click Yes to delete the set.

After you make your changes, you must refresh and publish your Web site in order for your changes to appear on your site. For information about refreshing and publishing your changes, see Refreshing and Publishing a Catalog.


Deleting Product Variants

You can delete product variants from a product at any time.

To delete a product variant from a product

  1. In Catalogs, click Catalog Editor.

  2. In the Catalogs screen, select the catalog from which you want to remove a product variant, and then click Open on the toolbar.

  3. In the Catalog - <Catalog Name> screen, in the Products section, select the product from which you want to remove a product variant, and then click Edit.

  4. In the Catalog Editor - <Catalog Name> (product) screen, in the Product Variants section, select the product variant you want to remove in the Product Variants table, and then click Remove.

    The product variant is removed from the Product Variant table.

    Caution

    • When you remove a product variant from a catalog you are not asked for confirmation before the removal takes place. If you remove a product variant by mistake you have to add that product variant to the catalog again.
  5. To save the removal and return to the Catalog - <Catalog Name> screen, click Save and go back on the toolbar.

After you make your changes, you must refresh and publish your Web site in order for your changes to appear on your site. For information about refreshing and publishing your changes, see Refreshing and Publishing a Catalog.


Managing Category and Product Relationships

Categories and products can be related to other categories and products. For example, in a product-to-product relationship, if you have a user who buys a movie, they may want to buy the movie soundtrack as well. In a category-to-category relationship, you can have a relationship between categories for CDs and Biographies. If you have CDs by classical composers, you may have biographies of classical composers as well.

You can edit or delete existing product or category relationships. If you want to add a new version of a movie soundtrack, you can edit the product relationship for the existing soundtrack in order to offer users another release of the soundtrack. If you want to re-arrange the products on your Web site, you can delete several product relationships.

This section contains:

  • Editing a Category Relationship

  • Editing a Product Relationship

  • Deleting a Category Relationship

  • Deleting a Product Relationship


Editing a Category Relationship

You can edit category relationships whenever there is a change the relationship. For example, if you have a category relationship between classical music and biographies of classical composers, you may want to change the relationship to classical music and documentaries if you start keeping documentaries on classical composers and stop keeping biographies.

To edit a category relationship

  1. In Catalogs, click Catalog Editor.

  2. In the Catalogs screen, select the catalog in which you want to edit a relationship, and then click Open on the toolbar.

  3. In the Catalog - <Catalog Name> screen, in the Categories section, select the category to which you want to edit a relationship, and then click Edit.

  4. In the Catalog Editor - <Catalog Name> (category) screen, enter the necessary changes for the category relationship in the Category Relationships section, and then click Accept to save the relationship.

  5. To save your edits and return to the Catalog - <Catalog Name> screen, click Save and go back on the toolbar.

After you make your edits, you must refresh and publish your Web site in order for your edits to appear on your site. For information about refreshing and publishing your edits, see Refreshing and Publishing a Catalog.


Editing a Product Relationship

You can edit product relationships whenever there is a change in the relationship. For example, if you have created a product relationship between a movie and the sound track of the same movie, and you want to add a new remix release of the soundtrack, you do this by editing the product relationship.

To edit a product relationship

  1. In Catalogs, click Catalog Editor.

  2. In the Catalogs screen, select the catalog in which you want to edit a product relationship, and then click Open on the toolbar.

  3. In the Catalog - <Catalog Name> screen, in the Product section, select the product to which you want to edit a relationship, and then click Edit.

  4. In the Catalog Editor - <Catalog Name> (product) screen, enter the necessary edits for the product relationship in the Product Relationships section, and then click Accept to save the relationship.

  5. To save your edits and return to the Catalog - <Catalog Name> screen, click Save and go back on the toolbar.

After you make your edits, you must refresh and publish your Web site in order for your edits to appear on your site. For information about refreshing and publishing your edits, see Refreshing and Publishing a Catalog.


Deleting a Category Relationship

You can delete category relationships at any time, for example, if you no longer sell a category of products, or if you want to re-arrange the products on your Web site.

To delete a category relationship

  1. In Catalogs, click Catalog Editor.

  2. In the Catalogs screen, select the catalog from which you want to delete a category relationship, and then click Open on the toolbar.

  3. In the Catalog - <Catalog Name> screen, in the Categories section, select the category from which you want to delete a relationship, and then click Edit.

  4. In the Catalog Editor - <Catalog Name> (category) screen, in the Category Relationships section, select the relationship you want to delete, and then click Delete.

    Caution

    • When you delete a category relationship you are not asked for confirmation. If you delete a relationship by mistake you will have to add that relationship to the catalog again.

After you make your changes, you must refresh and publish your Web site in order for your changes to appear on your site. For information about refreshing and publishing your changes, see Refreshing and Publishing a Catalog.


Deleting a Product Relationship

You can delete a product from a product relationship at any time. For example, if you want to re-arrange the products on your Web site, you might delete several product relationships.

To delete a product relationship

  1. In Catalogs, click Catalog Editor.

  2. In the Catalogs screen, select the catalog from which you want to delete a product relationship, and then click Open on the toolbar.

  3. In the Catalog - <Catalog Name> screen, in the Products section, select the property from which you want to delete a relationship, and then click Edit.

  4. In the Catalog Editor - <Catalog Name> (product) screen, in the Product Relationships section, select the product relationship you want to delete, and then click Delete.

    Caution

    • When you delete a product relationship, you are not prompted for additional confirmation. If you delete a relationship by mistake, you will have to add that relationship to the catalog again.

After you make your changes, you must refresh and publish your Web site in order for your changes to appear on your site. For information about refreshing and publishing your changes, see Refreshing and Publishing a Catalog.


Business Desk Orders

You use the Orders modules to search your Commerce Server database for existing order information and to delete saved baskets that are no longer in use. For example, you can track the location of an order in the order process using order status codes, enabling you to find where an order might be blocked or have unresolved problems. You can also add tax rates and shipping methods, and then update the information on your Web site.

This section contains:

  • Workflow for Order Management. Illustrates the workflow for managing orders.

  • About Orders. Describes the components of an order.

  • Adding Order Status Codes. Explains how to add order status codes.

  • Adding Country Codes. Explains how to add country or region codes.

  • Adding State/Province Codes. Explains how to add state or province codes.

  • Customizing Shipping Methods. Explains the three shipping methods included with Microsoft Commerce Server 2000 and how to customize them for your Web site.

  • Adding Tax Rates. Explains how to add a table, and provides examples of how to customize regional, state/province, and federal taxes.

  • Publishing Transactions on Your Web Site. Explains how to publish to your Web site new and changed transaction information, such as changed orders, new tax rates, and new shipping methods.

  • Editing Data Code Properties. Explains how to change data code properties.

  • Finding Baskets. Explains how to view and sort saved baskets.

  • Deleting Baskets. Explains how to delete saved baskets that are no longer in use.

  • Finding and Sorting Orders. Explains how to find and sort orders.

  • Deleting Orders. Explains how to delete orders from your Commerce Server database.

  • Managing Data Codes and Tax Rates. Explains how to edit and delete data codes and tax rates.


Workflow for Order Management

The following figure illustrates a sample scenario for adding order status codes, country/region codes, and state/province codes, customizing shipping methods, and adding tax rates.

Workflow diagram for order management
Order Status
Customizing Shipping Methods
Order Status
Adding Order Status Codes
Adding Country Codes
Adding Tax Rates
Publishing Transactions on Your Web Site
Adding State Codes
New Orders
Saved Orders
Baskets
Charge By Weight
Charge By Quantity
Charge By Subtotal
Order Status
Shipping Methods
Tax Rates
Publish Transactions

  1. In the Order Status module, you add order status codes to keep track of orders placed by users on your Web site. Perform this step only if the default order status codes do not meet your business needs.

  2. In the Order Status module, you add country/region codes to be displayed on the Web site as a shipping option for users.

  3. In the Order Status module, you add state/province codes to be displayed on the Web site as a shipping option for users.

  4. In the Shipping Methods module, you customize a shipping method available to users on your Web site.

  5. In the Tax Rates module, you add tax rates.

  6. In the Publish Transactions module, you publish changes to the Web site.

See Also

About Orders

Adding Order Status Codes

Adding Country Codes

Adding State/Province Codes

Customizing Shipping Methods


About Orders

You use the Orders modules in Commerce Server Business Desk to view order status information, maintain the data codes used with orders, and manage orders that users place from your Web site. For example, you use the Basket Manager module to delete baskets that users have abandoned. You use the Orders module to add tax rates and to customize your shipping methods.

Data Codes

Shipping Methods

Orders

Abandoned Baskets

Data Codes

You use the Data Codes module to add codes that will appear on the Web site and help you track orders placed by users.

Order Status Codes

You use order status codes to track the location of an order in the order process and where an order might be blocked or have unresolved problems. You have three default order status codes: 4 (New Order), 2 (Saved Order), and 1 (Basket).

After users add items to their baskets or after users submit orders from your Web site, the orders are assigned order status codes. For example, a new order that has not been processed is assigned the status code 4 (New Order). Order status codes help you track where an individual order is in the ordering process.

In some cases, such as with order status codes, you can use the existing default codes included with Commerce Server; however, if the default codes are insufficient and you need new codes, you can add order status codes directly through the Data Codes module in Business Desk. For information about adding order status codes, see Adding Order Status Codes.

Country/Region Codes and State/Province Codes

You can use country/region codes and state/province codes to display geographical information for shipping and billing purposes. Country and region codes identify the countries or regions where users who order items from your site will have those items sent. State and province codes identify the states and provinces where you ship your orders.

When you add data codes, you must enter the codes in a specific order:

  1. Add a country or region code before you can add a new state or province code.

  2. Add a state or province code.

  3. Set up tax rates.

When users order items from your site, they complete a profile form that includes their shipping address. The profile forms on your Web site include the state/province and country/region codes you specified.

Shipping Methods

Before users can place orders on your Web site, you must have at least one shipping method available. Commerce Server 2000 provides three default shipping methods: charge by weight, charge by quantity, and charge by subtotal. If you need additional shipping methods, or you use a delivery service (such as UPS or DHL) that offers a third-party application, you will need to contact your site developer for help. If you need to use a third-party application provided by a delivery service, you should contact that delivery service to find out the standard country codes they use (such as DE for Germany and FR for France) before adding country codes to your Commerce Server database. For more information about shipping methods, see Customizing Shipping Methods.

For information about adding a custom shipping method or a third-party application, see your site developer.

Orders

After a user submits an order to your Web site, it is processed by the Commerce Server Order Processing pipeline. The Order Processing pipeline (OPP) divides order processing into stages that describe a category of work. A typical OPP may include a shopper information stage, a payment stage, and a shipping stage to be processed appropriately. For example, the product description and the shipping address for the user are retrieved from the Commerce Server database, and the amount of tax is computed. This information and the total price are stored in the Commerce Server database for the order.

You use the Order Status module to view order status information and to display all the details associated with an order, including the order header and line-item information. You can search for specific orders placed by users visiting your site. For example, you can search for an order by the item description, the product ID, or the order number. You can also sort orders to display the information you are looking for more clearly. For example, you can sort orders by the order status or by the last name of the user.

You can use Microsoft BizTalk Server 2000 and Business Desk Orders together to process orders that users place on your Commerce Server Web site. For example, assume you are selling computer hardware on your site. Some of this hardware is manufactured by your company, and some of it is supplied to you by trading partners. Using BizTalk Server, you can create a trading agreement for each trading partner who supplies the hardware that you sell on your site. When a user visits your site and places an order for one of the products supplied by a trading partner, Commerce Server processes the order, sends it to BizTalk Server, and then BizTalk Server sends the order to the trading partner to be filled. For more information about integrating BizTalk Server with Business Desk Orders, contact your system administrator.

Abandoned Baskets

When users shop your site, they place the items that they want to buy in a virtual "basket." All the items users intend to buy are listed in their baskets when they check out. Users can log off your site without checking out or emptying their baskets. These abandoned baskets remain in your Commerce Server database, until you delete them or until the users return and empty the baskets themselves. Users can also save their baskets and leave them in your Commerce Server database indefinitely.

To prevent a large number of abandoned or saved baskets from cluttering your Commerce Server database, on a regular basis you must delete baskets that have been abandoned or saved for a certain period of time. You can use the Find pane in the Basket Manager module to search for baskets you want to delete using filter criteria. For example, you can search for baskets that have been abandoned or saved for more than two weeks, and then delete those baskets. For more information about deleting baskets, see Deleting Baskets.

See Also

Customizing Shipping Methods

Editing Data Code Properties

Adding Order Status Codes

Adding Country Codes

Adding State/Province Codes

Finding Baskets

Finding and Sorting Orders


Adding Order Status Codes

You use order status codes to track the location of an order in the order process and to determine where an order might be blocked or have unresolved problems. An order status code identifies a name with a code for a specific area of the order process. For example, if a user ordered two CDs and two t-shirts eight weeks ago, you can view the order status codes for the order so you can track where in the ordering process the order is. You have three default order status codes: 4 (New Order), 2 (Saved Order), and 1 (Basket).

To add an order status code

  1. In Orders, click Data Codes.

  2. In the Order Status Codes screen, click View on the toolbar, select Order Status Codes from the drop-down list, and then click Add on the toolbar.

  3. In the Data Codes – Order Status Codes screen, do the following:
    Use this | To do this
    Code | Type the numeric order status code you want to create.
    Name | Type the name for the order status code.
    Description | Type the description for the order status code.

  4. To save the order status code and continue entering new order status codes, click Save and create new on the toolbar.

You can enter the next new order status code.

To save the order status codes and return to the Order Status Codes screen, click Save and go back on the toolbar.

Note

  • After you add an order status code, your system administrator must unload the Commerce Server application from memory on each Web server in order for the change to take effect. For more information, see "Unloading an Application from Memory" in Commerce Server 2000 Help.

See Also

Workflow for Order Management

About Orders

Adding Country Codes

Adding State/Province Codes

Managing Data Codes and Tax Rates


Adding Country Codes

You create country/region codes to identify the countries and regions where users who order items from your site will have those items sent. Country/region codes identify the countries that appear on your Web site. Commerce Server provides several country codes, including those for the United States, Japan, Germany and Canada.

Notes

  • Country or region codes must be added to your Commerce Server database before the state or province codes for that country or region can be added. If you try to add a state or province code for a country or region you have not yet added to your database, you will receive an error message.

  • If you need to use a plug-in application provided by a delivery service, you should contact that delivery service to find out the standard country codes they use (such as DE for Germany and FR for France) before adding country/region codes to your database.

To add a country/region code

  1. In Orders, click Data Codes.

  2. In the Order Status Codes screen, click View on the toolbar, select Country/Region Codes from the drop-down list, and then click Add on the toolbar.

  3. In the Country Codes screen, do the following:
    Use this | To do this
    Country/Region Code | Type an alphabetic code for the country or region.
    Display Name | Type the country or region name.
    Description | Type a description for the country or region code, if necessary.

  4. To save the country code and return to the Country/Region Codes screen, click Save and go back on the toolbar.

The new country code appears in the Country/Region Codes screen.

Note

  • After you add a country code, your system administrator must unload the Commerce Server application from memory on each Web server in order for the change to take effect. For more information, see "Unloading an Application from Memory" in Commerce Server 2000 Help.

See Also

Workflow for Order Management

About Orders

Adding State/Province Codes

Managing Data Codes and Tax Rates


Adding State/Province Codes

You add state and province codes in your Commerce Server database to identify the states and provinces where you ship your orders. The state/province codes identify the states and provinces that appear on your Web site.

Note

  • Country/region codes must be added to your Commerce Server database before the state and province codes for that country or region can be added. If you try to add a state/province code for a country or region you have not yet added to your database, you will receive an error message. For more information about adding country/region codes, see Adding Country Codes.

To add a state/province code

  1. In Orders, click Data Codes.

  2. In the Order Status Codes screen, click View on the toolbar, select State/Province Codes from the drop-down list, and then click Add on the toolbar.

  3. In the State/Province Codes screen, do the following:
    Use this | To do this
    State/Province Code | Type an alphabetic code for the state or province.
    Display Name | Type the state or province name.
    Description | Type a description for the state or province code, if necessary.

  4. To save the changes and return to the State/Province Codes screen, click Save and go back on the toolbar.

The new state/province code is saved in your Commerce Server database.

Note

  • After you add a state/province code, your system administrator must unload the Commerce Server application from memory on each Web server in order for the change to take effect. For more information, see "Unloading an Application from Memory" in Commerce Server 2000 Help.

See Also

Workflow for Order Management

About Orders

Adding Country Codes

Managing Data Codes and Tax Rates


Customizing Shipping Methods

Commerce Server Business Desk supports three shipping methods:

  • Charge by weight. Use this method to charge the user for shipping by the weight of an order. You use this method to specify the charges for a range of weights. For example, shipping an individual item whose weight falls between 2 and 3 pounds would cost $4.00. If you shipped an item whose weight was 10 pounds, shipping costs might be $8.00.

    Note

    • To charge by weight, all products in your catalog must support weight. If you have products that do not support weight, this option will not function properly on your Web site. For information about product definitions and adding products to a catalog, see Adding a Product to a Catalog.
  • Charge by quantity. Use this method to charge for shipping by the quantity of items in an order. You can specify the charges for either an exact number or a range of item quantities. For example, shipping an order that contains up to three items would cost $2.00. If the order consisted of four or more items, the shipping cost might be $4.00.

  • Charge by subtotal. Use this method to charge for shipping by the subtotaled amount of an order. For example, shipping an order consisting of four CDs with a price total of $70.00 would cost $3.00. If you shipped an order containing one CD that costs $17.99, the shipping cost might be only $2.00.

You can also change the shipping method properties of a selected shipping method. For example, as shipping costs change, you can change the cost per method accordingly.

If you are using delivery services (such as USPS or Federal Express) who offer a number of shipping options, or a delivery service whose rates are figured by weight and zone (such as UPS), you will need to use a third-party pipeline component from that delivery service. For information about installing a custom shipping method or a third-party shipping pipeline component, contact your system administrator.

To add a charge by weight shipping method

To add a charge by quantity shipping method

To add a charge by subtotal shipping method

To edit shipping method properties

To add a charge by weight shipping method

  1. In Orders, click Shipping Methods.

  2. In the Shipping Methods screen, click Add on the toolbar, and then select Charge by Weight from the drop-down list.

  3. In the Charge by Weight - New screen, in the Shipping Method Properties section, do the following:
    Use this | To do this
    Name | Type a name for your shipping method.
    Description | Type a description for your shipping method.
    Enabled | Select this check box to enable this shipping method. If you do not enable the shipping method, it will not appear on your Web site.

  4. In the Rates section, click New, and then do the following:
    Use this | To do this
    Weight, up to | Type a weight amount for the rate level.
    Shipping Rate | Type the amount of the rate.

  5. Click Accept.

  6. After you have entered all the rates, click the last row in the rates list, which reads over <highest weight entered>, and then click Edit.

    Important

    • You must edit the last line under Rates to save your shipping method.
  7. Enter the highest rate for this shipping method, and then click Accept.

  8. To save the shipping method and return to the Shipping Methods screen, click Save and go back on the toolbar.

The charge by weight shipping method is saved.

Notes

  • All the products in all the catalogs must support weight for the charge by weight shipping method to work. This means that the Weight property must be assigned to each product definition for the products. For more information about adding product definitions, see Adding a Product Definition.

  • You must use the Publish Transactions module to update your site. For more information about publishing transactions, see Publishing Transactions on Your Web Site.

To add a charge by quantity shipping method

  1. In Orders, click Shipping Methods.

  2. In the Shipping Methods screen, click Add on the toolbar, and then select Charge by Quantity from the drop-down list.

  3. In the Charge by Quantity-New screen, in the Shipping Method Properties section, do the following:
    Use this | To do this
    Name | Type a name for your shipping method.
    Description | Type a description for your shipping method.
    Enabled | Select this check box to enable this shipping method. If you do not enable the shipping method, it will not appear on your Web site.

  4. In the Rates section, click New, and then do the following:
    Use this | To do this
    Quantity, up to | Type the quantity for the rate level.
    Shipping Rate | Type the amount of the rate.

  5. Click Accept.

  6. After you have entered all the rates, click the last row in the rates list, which reads over <highest quantity entered>, and then click Edit.

    Important

    • You must edit the last line under Rates in order to save your shipping method.
  7. Enter the highest rate for this shipping method, and then click Accept.

  8. To save the shipping method and return to the Shipping Methods screen, click Save and go back on the toolbar.

The charge by quantity shipping method is saved.

Note

  • You must use the Publish Transactions module to update your site. For more information about publishing transactions, see Publishing Transactions on Your Web Site.

To add a charge by subtotal shipping method

  1. In Orders, click Shipping Methods.

  2. In the Shipping Methods screen, click Add on the toolbar, and then select Charge by Subtotal from the drop-down list.

  3. In the Charge by Subtotal - New screen, in the Shipping Method Properties section, do the following:
    Use this | To do this
    Name | Type the name of your shipping method.
    Description | Type the description of your shipping method.
    Enabled | Select this check box to enable this shipping method. If you do not enable the shipping method, it will not appear on your Web site.

  4. In the Rates section, click New, and then do the following:
    Use this | To do this
    Price, up to | Type the subtotal amount for the rate level.
    Shipping Rate | Type the amount of the rate.

  5. Click Accept.

  6. After you have entered all the rates, click the last row in the rates list, which reads over <highest subtotal entered>, and then click Edit.

    Important

    • You must edit the last line under Rates in order to save your shipping method.
  7. Enter the highest rate for this shipping method, and then click Accept.

  8. To save the shipping method and return to the Shipping Methods screen, click Save and go back on the toolbar.

The charge by subtotal shipping method is saved.

Note

  • You must use the Publish Transactions module to update your site. For more information about publishing transactions, see Publishing Transactions on Your Web Site.

To edit shipping method properties

  1. In Orders, click Shipping Methods.

  2. In the Shipping Methods screen, select the shipping method you want to edit, and then click Open on the toolbar.

  3. In the Charge by <method> - Open <method name> screen, edit the properties for the shipping method.

  4. To save your edits and return to the Shipping Methods screen, click Save and go back on the toolbar.

The edited shipping method is saved.

Note

  • You must use the Publish Transactions module to update your site. For more information about publishing transactions, see Publishing Transactions on Your Web Site.

See Also

Workflow for Order Management

About Orders

Publishing Transactions on Your Web Site

Managing Data Codes and Tax Rates


Adding Tax Rates

Different states/provinces and countries/regions charge different amounts for sales tax, and some do not charge tax at all. Use the Tax Rates module to add tax rates for different countries/regions and states/provinces.

Note

  • Country/region and state/province codes must be set up before you can add tax rates. For more information about adding country/region and state/province codes, see Adding Country Codes and Adding State/Province Codes.

To add a tax rate

  1. In Orders, click Tax Rates.

  2. In the Tax screen, click New, and then do the following:
    Use this | To do this
    Country/Region | Select a country or region from the drop-down list.
    State/Province | Select a state or province from the drop-down list.
    Tax rate | Type a tax rate in percentage format, using decimals. For example, a tax rate of 8.6 percent would be typed as 8.6.

    Note

    • Tax rates set for individual states/provinces override any tax rate set for all the states and provinces of that country or region.
  3. Click Accept.

  4. To save the tax rate and return to the Business Desk welcome screen, click Save and go back on the toolbar.

The tax rate is saved.

Note

  • You must use the Publish Transactions module to update your site. For more information about publishing transactions, see Publishing Transactions on Your Web Site.

See Also

Workflow for Order Management

About Orders

Managing Data Codes and Tax Rates

Publishing Transactions on Your Web Site


Publishing Transactions on Your Web Site

You use the Publish Transactions module to update your site immediately with new information that you have added, such as changed orders, and new tax rates and shipping methods.

To publish tax, shipping, and order information

  1. In Orders, click Publish Transactions.

Only the active caches are listed in the Publish Transactions screen. If there are no caches listed in the screen, there is nothing to publish.

  2. From the list of active cache(s), select the cache(s) you want to update on your site, and then click Publish a catalog on the toolbar.

All your order information, including new orders, changed orders, tax, and shipping information, is immediately updated on your site.

See Also

About Orders

Customizing Shipping Methods

Adding Tax Rates


Editing Data Code Properties

You can view the properties of a selected data code and edit those properties. However, you cannot edit the actual number for the code. For more information about deleting data codes, see Managing Data Codes and Tax Rates.

Caution

  • If you inadvertently change a data code, to fix your mistake, you need to assign the changed data code a number that is not being used by an existing data code, and then add the old data code number back, replacing the one you added by mistake.

To edit data code properties

  1. In Orders, click Data Codes.

  2. In the Order Status Codes screen, click View on the toolbar, and then select the type of data code you want to view from the drop-down list.

  3. Select the data code that you want to edit, and then click Open on the toolbar.

  4. In the <data code> screen, edit the data code properties, and then click Save and go back on the toolbar.

The edited data code is saved.

Notes

  • After you edit a data code, your system administrator must unload the Commerce Server application from memory on each Web server in order for the change to take effect. For more information, see "Unloading an Application from Memory" in Commerce Server 2000 Help.

  • You must also contact your system administrator to implement any changes to the data codes on to your Web site

See Also

About Orders


Finding Baskets

You can search for existing baskets by date or by organization, or you can list all baskets currently on your Web site. When you sort baskets by the last date accessed, you can determine which baskets have been abandoned and then delete them.

To sort baskets

  1. In Orders, click Basket Manager.

  2. In the Basket Manager screen, click the drop-down arrow in the Find By box, and then select one of the following from the drop-down list:
    Use this | To do this
    Date last accessed To find by date, either:
    • Select From in the drop-down list. Enter the range of dates or select the dates from the From and To drop-down calendars.

      -Or-

    • Select On or Before in the drop-down list. Enter the date or select the date from the drop-down calendar.
    Organization | To sort by organization, type the name of the organization or select the name of the organization from the drop-down list.
    All baskets | Lists all the baskets in the Commerce Server database by the last names of the users.

  3. Click Find Now.

You can now review the results in a list in the Basket Manager screen.

See Also

About Orders

Deleting Baskets


Deleting Baskets

After a user abandons a basket, you can delete that basket from your Commerce Server database. Generally, you delete baskets because a user either does not check out or does not empty the basket before leaving the site.

To delete a basket

  1. In Orders, click Basket Manager.

  2. To find abandoned baskets by Date last accessed, select On or Before as your date criterion, enter a date or select the date from the drop-down calendar, and then click Find Now.

  3. In the baskets list, select the basket(s) you want to delete, and then click Delete on the toolbar.

  4. In the Delete confirmation dialog box, click Yes.

The basket is deleted.

Caution

After a basket has been deleted, it cannot be recovered.

Note

  • You must use the Publish Transactions module to update your site. For more information about publishing transactions, see Publishing Transactions on Your Web Site.

See Also

About Orders

Finding Baskets

Managing Data Codes and Tax Rates


Finding and Sorting Orders

You can search for specific orders placed by users visiting your site. You have eight options on which to limit your search, or you can list all orders. By default, orders are listed in descending order by their number, but you can change the sort order. For example, you can sort orders by the order status or by the last name of the user.

To find an order

To sort orders in a list

To find an order

  1. In Orders, click Order Status.

  2. In the Order Status screen, in the Find By drop-down list, select one of the following:
    Use this | To do this
    Order date | Select to list all orders that were placed on or before a given date or from a given date forward. Type the date or select a date from the drop-down calendar.
    User name | Select to list all orders created by a specific user. You can type the first few characters of first name or last name of the user, or both, in the First Name and Last Name boxes.
    Order number | Select to list the orders with a specific order number. You must type the exact order number in the Order number box.
    Organization | Select to list all orders from a specific organization. You must type the organization name in the Organization box.
    PO number | Select to list all orders from a specific purchase order (PO) number. You must type the exact PO number in the PO number box.
    Product ID | Select to list all orders that contain a specific product ID number. You must type the exact product ID number in the Product ID box.
    Item description | Select to list all orders that have a specific description.
    Any information | Select to open all search criteria. You can enter some or all of the order details.
    All orders | Select to list all saved orders that have not been processed.

  3. Click Find Now.

You can now view your search results in the Order Status screen.

To sort orders in a list

  1. In Orders, click Order Status.

  2. In the orders list, click the column heading you want to use to sort the orders.

The column heading you click sorts the list dynamically.

See Also

About Orders

Deleting Orders


Deleting Orders

You can delete existing orders using the Order Status module. This is useful when, for example, an order needs to be cancelled, a user inadvertently creates a duplicate order, or the item the user wants is no longer available.

To delete an order

  1. In Orders, click Order Status.

  2. Select the order you want to delete from the order results list, and then click Delete on the toolbar.

  3. In the Delete confirmation dialog box, click OK to confirm the deletion.

The order is deleted from your site.

Caution

  • After an order has been deleted, it cannot be recovered.

Note

  • You must use the Publish Transactions module to update your site. For more information about publishing transactions, see Publishing Transactions on Your Web Site.

See Also

About Orders

Finding and Sorting Orders

Managing Data Codes and Tax Rates


Managing Data Codes and Tax Rates

You use the Data Codes and Tax Rates modules to manage data codes and tax rates.

This section contains:

  • Editing an Order Status Code

  • Deleting an Order Status Code

  • Editing a Country

  • Deleting a Country

  • Editing a State/Province Code

  • Deleting a State/Province Code

  • Editing a Tax Rate

  • Deleting a Tax Rate


Editing an Order Status Code

You can edit the name and description of existing order status codes using the Data Codes module.

To edit an order status code

  1. In Orders, click Data Codes.

  2. In the Order Status Codes screen, click on the toolbar, and then select Order Status Codes from the drop-down list.

  3. Select the order status code you want to edit, and then click Open on the toolbar.

  4. In the Order Status Codes - <order status code> screen, do the following:
    Use this | To do this
    Code Name | Type a new name for the order status code.
    Description | Type a new description for the order status code.

  5. To save your edits and return to the Order Status Code screen, click Save and go back on the toolbar.

The edited order status code is saved.

Notes

  • You cannot edit the actual code number in the Code box. If you want to change the code number, you must delete the order status code and add a new one with the required change in the Code box. For more information about deleting and adding order status codes, see Deleting an Order Status Code and Adding Order Status Codes.

  • After you edit an order status code, your system administrator must unload the Commerce Server application from memory on each Web server in order for the change to take effect. For more information, see "Unloading an Application from Memory" in Commerce Server 2000 Help.


Deleting an Order Status Code

You can delete existing order status codes using the Data Codes module. This is useful when, for example, you do not require order status code for identifying a particular object.

To delete an order status code

  1. In Orders, click Data Codes.

  2. In the Order Status Codes screen, click View on the toolbar, and then select Order Status Codes from the drop-down list.

  3. Select the order status code you want to delete, and then click Delete on the toolbar.

  4. In the Order Status Codes confirmation dialog box, click OK.

The order status code is deleted from your site.

Caution

  • After you delete an order status code, it cannot be recovered. If you need the order status code you deleted, you must recreate it.

Note

  • After you delete an order status code, your system administrator must unload the Commerce Server application from memory on each Web server in order for the change to take effect. For more information, see "Unloading an Application from Memory" in Commerce Server 2000 Help.


Editing a Country Code

You can edit the name and description of existing country codes using the Data Codes module.

To edit a country code

  1. In Orders, click Data Codes.

  2. In the Order Status Codes screen, click View on the toolbar, and then select Country/Region Codes from the drop-down list.

  3. Select the country code you want to edit, and then click Open on the toolbar.

  4. In the Country Codes - <country> screen, do the following:
    Use this | To do this
    Display name | Type the country or region name.
    Description | Type a description for the country code, if necessary.

  5. To save your edits and return to the Country/Region Codes screen, click Save and go back on the toolbar.

The edited country code is saved.

Notes

  • You cannot edit the actual code number in the Code box. If you want to change the code number, you must delete the entire country/region code and add a new one with the required change in the Code box. For more information about deleting and adding country codes, see Deleting a Country Code and Adding Country Codes.

  • After you edit a country code, your system administrator must unload the Commerce Server application from memory on each Web server in order for the change to take effect. For more information, see "Unloading an Application from Memory" in Commerce Server 2000 Help.


Deleting a Country Code

You can delete existing country codes using the Data Codes module. This is useful when, for example, you do not ship products to a particular country or region and do not want users to view it as an option.

To delete a country code

  1. In Orders, click Data Codes.

  2. In the Order Status Codes screen, click View on the toolbar, and then select Country/Region Codes from the drop-down list.

  3. Select the country code you want to delete, and then click Delete on the toolbar.

  4. In the Delete Related Codes dialog box, click OK.

  5. In the Country/Region Codes dialog box, click OK.

The country or region code is deleted from your site.

Caution

  • Deleting a country/region code will also delete all state/province codes associated with that country/region.

  • After you delete a country/region code, it cannot be recovered. If you need the country/region code you deleted, you must recreate it.

Note

  • After you delete a country/region code, your system administrator must unload the Commerce Server application from memory on each Web server in order for the change to take effect. For more information, see "Unloading an Application from Memory" in Commerce Server 2000 Help.


Editing a State/Province Code

You can edit the name and description of an existing state/province code using the Data Codes module.

To edit a state/province code

  1. In Orders, click Data Codes.

  2. In the Order Status Codes screen, click View on the toolbar, and then select State Codes from the drop-down list.

  3. Select the state code you want to edit, and then click Open on the toolbar.

  4. In the State/Province Codes - <state> screen, do the following:
    Use this | To do this
    Display name | Type the state or province name.
    Description | Type a description for the state/province code, if necessary.

  5. To save your edits and return to the State/Province Codes screen, click Save and go back on the toolbar.

The edited state/province code is saved.

Notes

  • You cannot edit the actual code number in the Code box. If you want to change the code number, you must delete the state or province code and add a new one with the required change in the Code box. For more information about deleting and adding state codes, see Deleting a State/Province Code and Adding State/Province Codes.

  • After you edit a state/province code, your system administrator must unload the Commerce Server application from memory on each Web server in order for the change to take effect. For more information, see "Unloading an Application from Memory" in Commerce Server 2000 Help.


Deleting a State/Province Code

You can delete existing state or province codes using the Data Codes module. This is useful when, for example, you do not ship products to a particular state/province and do not want users to view it as an option.

To delete a state/province code

  1. In Orders, click Data Codes.

  2. In the Order Status Codes screen, click View on the toolbar, and then select State/Province Codes from the drop-down list.

  3. In the State/Province Codes screen, select the code you want to delete, and then click Delete on the toolbar.

  4. In the State/Province Codes dialog box, click OK.

The state/province code is deleted from your site.

Caution

  • After you delete a state or province code, it cannot be recovered. If you need the state or province code you deleted, you must recreate it.

Note

  • After you delete a state/province code, your system administrator must unload the Commerce Server application from memory on each Web server in order for the change to take effect. For more information, see "Unloading an Application from Memory" in Commerce Server 2000 Help.


Editing a Tax Rate

You can edit an existing tax rate using the Tax Rates module. This is useful when, for example, the government changes a tax rate.

To edit tax a rate

  1. In Orders, click Tax Rates.

  2. Select the tax rate you want to edit, and then click Edit.

  3. Edit the tax rate, and then click Accept.

  4. To save your edits and return to the Business Desk welcome screen, click Save and go back on the toolbar.

The edited tax rate is saved.

Note

  • You must use the Publish Transactions module to update your site. For more information about publishing transactions, see Publishing Transactions on Your Web Site.


Deleting a Tax Rate

You can delete an existing tax rate using the Tax Rates module. This is useful when, for example, the government cancels a tax rate.

To delete a tax rate

  1. In Orders, click Tax Rates.

  2. Select the tax rate you want to delete, and then click Remove.

  3. To save your changes and return to the Business Desk welcome screen, click Save and go back on the toolbar.

The tax rate is deleted from your site.

Caution

  • After you delete a tax rate, it cannot be recovered. If you need the tax rate you deleted, you must recreate it.

Note

  • You must use the Publish Transactions module to update your site. For more information about publishing transactions, see Publishing Transactions on Your Web Site.


Business Desk Users

You use the Users modules to manage the collection of data on your Commerce Server 2000 Web site. For example, you can define what data is collected from users, and what data is exported to the Data Warehouse. You also use the Users modules to manage user and organization profiles, for example to change a user password or an organization administrative contact.

This section contains:

  • Workflow for Users Management. Illustrates the workflow for managing user and organization profiles, designing profile definitions, and editing site terms.

  • About Users. Describes user profiles, organization profiles, profile definitions, and site terms, and how you work with them in Commerce Server.

  • Adding a Site Term. Explains how to add new site terms.

  • Adding a Site Term Group. Explains how to add new site term groups.

  • Adding Properties to a Profile Definition. Explains how to add new properties to profile definitions.

  • Adding a Property Group to a Profile Definition. Explains how to organize your properties by adding a property group to a profile definition.

  • Publishing Profile Definition Changes on Your Web Site. Explains how to synchronize profile definition changes with your Web site.

  • Adding a User. Explains how to add new user profiles to your Web site.

  • Importing a List of User Profiles. Explains how to import a list of user profiles from the List Manager module into the Users module.

  • Adding an Organization. Explains how to add new organization profiles to your Web site.

  • Resetting a User Password. Explains how to reset a password for a registered user.

  • Managing Site Terms and Groups. Explains how to edit, organize, and delete site terms and site term groups. Also explains how to delete terms (values) from site terms.

  • Managing Profile Definitions. Explains how to find, copy, and edit profile definitions, and delete profile properties.

  • Managing Users. Explains how to edit, find, copy, and delete user profiles.

  • Managing Organizations. Explains how to find, copy, edit, and delete organization profiles.


Workflow for Users Management

The following figure illustrates a sample scenario for managing user and organization profiles, designing profile definitions, and editing site terms.

Workflow managing user and organization profiles
Publish Profile
Publishing Profile Definition Changes on Your Web Site
Profile Designer
Adding a Site Term
Adding Properties to a Profile Definition
Adding an Organization
Adding a User
Catalog Designer
Organizations
Adding a Property Definition
Campaign Expressions
Users
Creating a Target Expression
Site Terms Editor

  1. You use the Site Terms Editor module to add a new site term, which can be used in a profile definition to limit user entries for that property.

  2. You use the Profile Designer module to add a new property to a profile definition.

  3. You use the Publish Profiles module to publish profile definition changes to your site.

  4. You use the Users module to add a new user profile to your Web site.

  5. You use the Organizations module to add a new organization profile to your Web site.


About Users

You use the Users modules to manage profile definitions, user and organization profiles, and site terms. For example, you can use site terms to limit the colors users can choose from when choosing their favorite color. You can define where user profile data is stored when it is collected, and what user profile data is exported to the Data Warehouse. You can add properties to the User object profile definition that will collect data you can use to distinguish which users you want to deliver targeted ads or discounts to.

This section contains:

  • Users

  • Organizations

  • Profiles

  • Profile Designer

  • Site Terms Editor


Users

You use the Users module to enter and manage information about guest and registered users who visit your site. For example, you can change the password for registered users who have forgotten theirs. The User object profile definition is used in the Users module to collect information about users. You can use the Profile Designer to customize the User object profile definition to meet the needs of your site.

Commerce Server supports two types of users:

  • Guest users. Users who do not supply personal information when visiting your Web site.

  • Registered users. Users who sign up for an account on your site, and typically have a login name and password. Registered users may provide additional information in order to interact with your site in an easier, more responsive manner.

The system administrator can set Commerce Server to automatically issue cookies that identify distinct guest and registered users and associate them with user profiles in the Commerce Server database. If a user has set their system to refuse cookies, Commerce Server will assign them a globally unique identifier (GUID), which can be used to identify returning users.

The system administrator imports the user data that Commerce Server collects in its database and your Web server log files into the Data Warehouse. You can then run reports based on this information to analyze the characteristics and behavior of your users. For example, you can run reports to analyze their demographic information, their product preferences, and their purchase behavior.

You can export user reports to List Manager to use as mailing lists for direct mail campaigns, and you can import user reports from List Manager into the Users module to update user information. User reports can be imported into List Manager from the Reports module, and from ASCII-delimited lists containing an e-mail address and a GUID as the first two fields for each user.

The following figure illustrates flow of user data from running a report, to exporting user data to mailing list, to updating your Web site.

Importing user lists and modifying user profiles
Export a Static
(User) Report
Reports
List Manager
Users
Modified user
data available
on your Web site
ASCII-delimited
user list imported
into List Manager
Edit users in
user list
Import a user list
from List Manager
Exported user list
in List Manager

See Also

Importing and Exporting Lists

Importing a List of User Profiles

Editing a User

Editing Multiple Users


Organizations

You use the Organizations module to add organizations to your site, and to specify information about them. An organization is a division, department, or other business unit within a company, or an external company acting as a trading partner, that is designated within Business Desk as a source of or destination for the exchange of business information.

If you have integrated BizTalk Server into Commerce Server, you can use BizTalk Server and Commerce Server together to process orders that users place on your Commerce Server Web site. For example, you can sell both your inventory and that of your trading partners from your Commerce Server Web site. You can use BizTalk Server to create a trading agreement for each trading partner who supplies products that you sell on your site. When an order for one of the products supplied by a trading partner is placed, Commerce Server processes the order, sends it to BizTalk Server, and then BizTalk Server sends the order to the trading partner to be filled. For information about BizTalk Server, see Using BizTalk Server.

You can add, delete, and manage organization profiles through the Organizations module. When you add an organization, you can specify information about it such as the name of the primary contact, address, phone number, name of the purchasing manager, and the catalog set available to the organization. The Organization profile definition is used in the Organizations module to collect information about organizations. You can use the Profile Designer module to customize the Organization profile definition to meet the needs of your site.

Before you can designate a user as an administrative contact, as an authorized receiver of goods, or as a purchasing manager for the organization you must do the following:

  1. Create the organization, using the Organizations module.

  2. Create the user and assign that user to the organization in the Users module.

  3. Designate that user as an administrative contact, a receiver, or as a purchasing manager for the organization in the Organizations module.

See Also

Adding a User

Adding an Organization

Using BizTalk Server


Profiles

A profile is a set of characteristics that define any business-related item, such as a user, a company, or a context (date and time). For example, a user profile may include characteristics such as first name, last name, city, gender, age, and e-mail address. A company profile may include different characteristics, such as the company name, contact, city, and e-mail address. A context profile may include characteristics such as the date and time when a page is displayed, and the path the user takes to get to that page.

The following figure shows different types of profiles.

A figure showing different types of profiles
Click history
Length of session
Company Name
Contact
City
E-mail address
Click history
Length of session
First Name
Last Name
City
Gender
Age
E-mail address
Click history
Length of session

Company Profile

Anonymous User Profile

Registered User Profile

In the Commerce Server, you use profiles to store information about business-related items. For example, you use profiles to collect data from users on your Web site. You can also enter data directly into user and organization profiles by using Business Desk.

  • Using Profiles in Web Site Management

  • Collecting and Storing Profiles

  • Analyzing User Data

Using Profiles in Web Site Management

Profiles are essential to Web site management because they provide information about the users who visit your site and how they use it. You use profiles to analyze user data, and you use them to target content to users.

Using Commerce Server Business Desk, you can:

  • Determine what information to collect about users visiting your site.

  • Analyze profile information.

  • Create target expressions to match content to users.

  • Create advertising, discount, and direct mail campaigns to target specific user groups.

  • Deliver personalized direct mail messages to users.

For example, assume you have a site that sells sporting goods. The following workflow provides an example of how you can use Business Desk to analyze user activity and target content to users.

  1. Your system administrator creates profile definitions for registered users and guest users.

  2. After your site has been running for a period of time, you can analyze profile data to determine who is visiting your site:
    • Run reports to analyze who is visiting your site.

    • Run reports to analyze which products in your catalog are selling well, and which ones are not selling well.
  3. Use the results of your analysis to create a campaign to target content to users:
    • Use the profiles to create target expressions and target groups.

    • Create a discount campaign to offer these specific users a discount.
  4. After the discount has been in production for a period of time, analyze the results of the campaign.
    • Run reports to analyze the success of the campaign.

    • Run reports to find out whether this group of users increased their purchases of discounted items.
  5. If your users did not increase their purchases of discounted items, create a direct mail campaign to deliver personalized messages offering the users a discount on a certain product.

For information about creating expressions and targeting content to users, see Targeting and Personalization.

Collecting and Storing Profiles

Profile data is collected at a Commerce site in two ways. Users visiting your site provide profile data about themselves; this is called explicit profiling. For example, when users purchase products from your site, they typically provide their name, mailing address, phone number, and e-mail address. This information is used to populate their user profile.

You can also collect data through implicit profiling. In implicit profiling, the actions of all users (anonymous and registered) are recorded in Web log files as the users interact with your Web site. For example, Web log files record the links that anonymous users click, what products they search for, the length of their sessions, and how long they visit a given Web page. Even though the users are anonymous — you do not know their names, e-mail addresses, or other information — how they use your site is still important information. For example, a click history provides a path through the Web pages visited; you can use this information to determine a particular set of interests.

Another form of implicit profiling is performed by the Commerce Server Predictor resource. If some information about a user is missing—for example, the Music Preference associated with a user—this information can be guessed by the Predictor resource based on the aggregate properties of the user population who visits your site and the CDs they purchase.

All the information that is collected during a specific user session is collected in a single profile, that is, one instance of a profile definition.

When profile data is initially collected, it is first stored in the Commerce Server database and the Web server logs. The system administrator imports the profile data into the Data Warehouse on a regular basis. After the profiles are imported into the Data Warehouse, you can use Business Desk to analyze user data, and then use the results of your analysis to update your Web site or apply values to user profile properties.

Analyzing User Data

You can analyze user data in reports, or in segment models. For information about analyzing segment models, see Analyzing Population Segments.

The following table lists the reports included with Commerce Server that you use to analyze user data.

Report | Description
Distinct Users and Visits by Week | Determine whether a few people are visiting your site many times, or if many people are visiting your site at the same time.
Distinct Users by Day | Determine how many unique users visit your site on a particular day.
New Registered Users | Identify new registered users. This data can be used to create special promotional campaigns. For example, you can export the report to List Manager, and then send these users a direct mail promotion.
Registered User Properties | Review information provided by registered users. This data can be used to create special promotional campaigns. For example, you target advertisements or discounts to users who have certain properties.
Registered Users by Date Registered | Review the registration behavior of your users.
User Days to Register | Track the average number of days it takes guest users to register on your site.
User Registration Rate | Determine how successful you have been in convincing guest users to register on your site.
User Trends | Determine how successful you have been in attracting repeat visitors.

See Also

Targeting and Personalization

Analyzing Population Segments

Running Reports


Profile Designer

You use the Profile Designer module to edit and manage profile definitions. A profile definition is a set of characteristics that define any business-related item, such as a user, a company, or a business process. A profile is a single instance of a profile definition containing the data that the profile definition collects. For example, you can design a profile definition to collect user data. You can then use the Users module to edit a user profile for a particular user who entered their data on your Web site.

Profile Structure

Profile Definitions

Profile Properties

Attributes

Sample Profile Definitions

Profile Structure

A Commerce Server profile consists of the following parts:

  • Profile definition. A description of the data to be collected for a given type of profile. You can have multiple profiles based on a single profile definition. For example, "User" is a profile definition, and "Address" is a profile definition. System administrators create profile definitions by using the Profiles resource in Commerce Server Manager.

  • Profile property. A characteristic that specifies the profile data to be collected when a user visits your Web site. For example, the First Name property specifies that the first name of the user should be collected. Use the Business Desk Profile Designer module to create profile properties and add them to profile definitions.

  • Attribute. A characteristic that specifies information about the property such as the data type of the property (for example, number, string, decimal, and site term).

  • Profile. A single instance of a profile definition that contains data. Every profile is based on a single profile definition.

The following table shows a sample User profile definition, and then a single instance of the sample User profile definition with data for Sean Chai.

Profile definition: User | Profile: Sean Chai
First name | Sean
Last name | Chai
City | Seattle
Gender | M
Age | 52
E-mail address | seanchai@microsoft.com

Profile Definitions

Work with your system administrator to create profile definitions for your site. The system administrator determines where the profile data will be stored in the Commerce Server database. This process is known as mapping the profile definition to the database. For example, assume you request a new profile definition named "Music," and you want to store the following profile properties: First Concert, Last Concert, Favorite CD, and two more properties that are not yet determined.

The system administrator creates the new profile definition, Music, including the three known properties and two placeholders for the properties you will add in the future, and then maps it to the Commerce Server database where it will be stored. After the system administrator creates the profile definition and the new properties, you can then use the Profile Designer module to add all three properties to the definition. (The system administrator can also do this for you using Commerce Server Manager.) At a later date, when you determine other information you want to collect using the Music profile definition, you can use Profile Designer to create two new properties and map them to the placeholders created by your system administrator.

The Commerce Server Solution Sites include the following sample profile definitions: Addresses, BlanketPOs (purchase orders), Organization, User Object, and Targeting Context. In the User Object, five unnamed properties are included so you can add properties to the User profile definition without contacting your system administrator to extend your database. For a list of properties included with each profile definition, see Sample Profile Definitions.

Profile Properties

After the system administrator creates the profile definition, you can add profile properties to it by using the Business Desk Profile Designer module. Profile properties determine what information is collected in a profile. For example, the User profile definition could contain the following properties: first name, last name, city, gender, age, and e-mail address. You can organize related profile properties into groups.

The following figure shows the parts of a sample User profile definition.

A figure showing the parts of a profile definition
Profile property
Profile attributes
User Profile Definition
First Name
Single valued Required Indexed
Last Name
Single valued Required Indexed
City
(Site Term: City)
(String)
(String)
(Site Term: City)
Mexico City Montreal
New York
Gender
(Site Term: Gender)
Gender
Male
Female
Unknown
Age
(Number)
E-mail Address
(String)
E-mail Address
E-mail Address
Data type

You can create profile properties as the following types:

Property Type | Description
String | A property of type string stores up to a maximum of 4,000 characters. String properties map to string data members.
Long String | A property of type long string stores up to a maximum of 2 to the power of 17 (2^17) characters. Long string properties map to string data members.
Number | A property of type number stores integers. The maximum length of a number property is determined by the data store. Number properties map to number data members.
Decimal | A property of type decimal stores floating point numbers. The maximum length of a decimal property is determined by the data store. Decimal properties map to number data members.
Boolean | A property of type Boolean stores one of two values (true/false, yes/no, or 1/0). Boolean properties map to Boolean data members.
Binary | A property of type binary stores binary data with a maximum size of 4 KB. Binary properties map to binary data members.
Long Binary | A property of type long binary stores content, such as spreadsheets, documents, graphics, and sound up to a maximum size of 128 KB. Long binary properties map to binary data members.
Date/Time | A property of type date/time is a composite date and time value. The format used and the maximum length are determined by the data store. Date/time properties map to date/time data members.
Date | A property of type date contains date values that are in the range of 1/1/1950 to 12/31/2049. The format used and the maximum length are determined by the data store. Date properties map to date/time data members.
Time | A property of type time contains values for hour, minute, second, and millisecond. The format used and the maximum length are determined by the data store. Time properties map to date/time data members.
Currency | A property of type currency accepts numbers in currency format. The currency format used and the maximum length are determined by data store. Currency properties map to currency data members.
Password | A property of type password accepts text, and is treated like a string by the Profiles resource. Commerce Server Business Desk displays the value stored in a password property as asterisks (*). Password properties map to string data members and have a maximum length of 255 Unicode characters.
Site Term | A property of type site term is associated with a site term. The value that is stored in this property should be a valid value from the list of term names associated with that site term. Site term properties map to string data members and have a maximum length of 255 Unicode characters.
Profile | A property of type profile is associated with a profile definition. The value that is stored in this property should be a value that corresponds to the value of the primary key of a specific instance of that associated profile. Profile properties map to string data members and have a maximum length of 255 Unicode characters.

Attributes

Each profile property has attributes. Attributes provide information about the property. For example, the First Name property has the following attributes: Name, Display Name, Description, and Type.

Attributes include information such as the data type of the profile property (for example, number, text, decimal, or site term), and whether the property is single-valued (for example, only one First Name entry is allowed per user) or multi-valued. You can also designate that the data can be exported. For example, data can be exported into the Data Warehouse.

There are two special types of attributes: custom attributes and advanced attributes.

  • Custom attributes. Application-specific attributes. You can define custom attributes for properties. For example, you can create a custom attribute that controls how a property is displayed on a Web site page.

  • Advanced attributes. You use the advanced attributes to change how your applications use a profile property. For example, the Exported attribute determines whether the property will be imported into the Data Warehouse.

The following table lists the advance attributes and the purpose of each one.

Attribute | Purpose
Active | Indicates whether this property is available through the Profile Service. Inactive properties are not displayed in Business Desk.
Map to data | The data member the property maps to.
Key type There are four key types you can assign:
  • Unique Key. Indicates that the value of this property is unique for all members. You map an attribute that is specified as a unique key to a unique field in a SQL Server database or to a unique attribute in a Lightweight Directory Access Protocol (LDAP) source.

  • Primary Key. Indicates that the value of this property is unique for all members. You map an attribute that is specified as a primary key to a primary field in a SQL Server database or to a unique attribute in a LDAP source.

  • Join Key. Relates multiple data stores through a common property in the Profile Service.

  • Dual (Primary and Join) Key. Indicates that the value of this property is unique, and relates this property to a property in another data store.
Required | Indicates that the property is required.
Exported | Specifies that the property will be imported into the Data Warehouse.
Defer cache load | Indicates that this property will not be loaded initially when the profile is retrieved, but will be loaded when this particular property is accessed.
Multi-valued | Enables the capturing of a collection of values that are associated with the property.
Searchable | Indicates that this property is indexed in the underlying data store and is available for searching through the Find By function. You map a searchable attribute to an indexed field in the SQL Server database or LDAP source.
RDN | Type the Relative Distinguished Name (RDN) for a directory store. If this attribute is set for a property, this member maps to the RDN attribute of a LDAP class in the underlying store. This does not apply to OLE DB Provider for Microsoft Commerce Server (OLE DB) sources, or any other data source type.
Hashing key | Indicates that this property will be used to distribute profile instances across multiple partitions. To retrieve this profile you must query on this key.

Sample Profile Definitions

Commerce Server Solution Sites include sample profile definitions. If your site developer used a Solution Site to build your site, you should have the five profile definitions listed in the following table.

Profile Definition | Properties (data type) | Description
Address | Address ID (string) | Address identifier
 | ID (string) | Organization/User Identifier
 | Last Name (string) | User last name
 | First Name (string) | User first name
 | Address Name (string) | Name for this address
 | Address Type (number) | Address/Ship to address/Bill to address
 | Description (string) | Description for this address
 | Address Line 1 (string) | First line of address
 | Address Line 2 (string) | Second line of address
 | City (string) | City name
 | Region Code (string) | State, region, or province code
 | State Name (string) | State, region, or province name
 | Postal Code (string) | Postal code
 | Country Code (string) | Country International Standards Organization (ISO) code
 | Country Name (string) | Country name
 | Telephone Number (string) | Telephone number at this address
 | Telephone Extension (string) | Telephone number extension at this address
 | Locale ID (number) | Locale in which to render the address form
 | Changed by (string) | Name of person who last changed this profile
 | Date last changed (date/time) | Date this profile was last changed
 | Date created (date/time) | Date this profile was created
BlanketPOs | Purchase Order ID (string) | Globally unique identifier (GUID) referring to the Blanket Purchase Order
 | Organization ID (string) | Organization ID
 | PO Number (string) | Blanket purchase order number
 | Description (string) | Description of purchase order
 | Changed by (string) | Name of person who last changed this profile
 | Date last changed (date/time) | Date this profile was last changed
 | Date created (date/time) | Date this profile was created
Organization | Organization ID (string) | Organization ID
 | Name (string) | Name of the organization
 | Trading partner number (string) | Trading partner number
 | Administrative contact (string) | GUID for the administrative contact
 | Receiver (string) | User ID of the person to receive products shipped from the supplier
 | Organization catalog set (string) | Organization catalog set
 | Changed by (string) | Name of person who last changed this profile
 | Purchasing manager (string) | User ID of the purchasing manager of the buying organization
 | Date last changed (date/time) | Date this profile was last changed
 | Date created (date/time) | Date this profile was created
User Object | User ID (string) | User ID
 | Logon name (string) | Logon name
 | User password (password) | User password
 | E-mail (string) | User e-mail address
 | User type (number) | User type
 | User title (string) | User title
 | Last name (string) | Last name of user
 | First name (string) | First name of user
 | Telephone number (string) | Telephone number for user
 | Telephone extension (string) | Telephone number extension for user
 | Fax number (string) | Fax number for user
 | Fax extension (string) | Fax number extension for user
 | Changed by (string) | Name of person who last changed this profile
 | Organization ID (string) | Organization ID
 | Account status (number) | Account status
 | User catalog set (string) | User catalog set
 | Date registered (date/time) | Date the user registered
 | Campaign History (string) | Campaign history
 | Partner service role flags (number) | Partner service role
 | Date last changed (date/time) | Date this profile was last changed
 | Date created (date/time) | Date this profile was created
Targeting Context | Page Group (string) | Name of the page group (for example, Sports pages)

See Also

Adding Properties to a Profile Definition

Adding a Site Term to a Profile Definition


Site Terms Editor

You use the Site Terms Editor module to create and manage site terms. A site term is a data type that you create. It is a list of specific values, called terms, that are pertinent to your site. You use a site term to assign this list of values to a property as an attribute.

For example, if you create a site term for favorite color, you provide a list of the colors from which users can select their favorite color. The "Favorite Color" site term restricts color choice to the colors you include. This requires users who favor variations of purple, such as mauve, violet, or lavender, to choose purple.

You use site terms to:

  • Standardize and restrict choices when you request user input on your site.

  • Avoid spelling variations in user input

  • Match values, such as a product color and the favorite color of a user, so you can target content to users. For example, if the color property of a product is "purple" you can match it to the favorite color site term, and then deliver ads to the user for the purple product.

In a form on your Web site, site terms are presented to users as list boxes.

Site Term Groups

You use site term groups to organize site terms in the Site Terms Editor. For example, if you have 50 site terms, and you use 10 to collect information about what products a user likes, 20 to collect information about what kind of lifestyle a user has, and 20 more to collect information about the opinions a user has about current events; you could then create a site term group called Products for the product preference site terms, a site term group called Lifestyle for the lifestyle site terms, and a site term group called Opinions for the opinion site terms.

Sample Site Terms

Commerce Server Solutions Sites include sample site terms. If your site developer used a Solution Site to build your Web site, then you should have the following site terms.

Site Terms | Terms
Account Status | Active Account Inactive Account
User Role | Normal User Administrator
User Type | Guest User Registered User
Days | Sunday Monday Tuesday Wednesday Thursday Friday Saturday
Months | January February March April May June July August September October November December

See Also

Adding a Site Term


Adding a Site Term

You use the Site Terms Editor module to create site terms and then add terms (values) to your site terms.

To add a site term

  1. In Users, click Site Terms Editor.

  2. In the Site Terms Editor screen, select the group to which you want to add the site term, and then click Add.

  3. In the Add dialog box, select the Add a new site term option, and then click OK.

  4. In the Site Terms Editor screen, in the Site Term Attributes section, do the following:
    Use this | To do this
    Name | Type a programmatic name for the new site term, for example, Favorite_Color. The name can contain a maximum of 128 alphanumeric characters and the underscore (_) symbol. The name cannot contain spaces.
    Display Name | Type a display name for the new site term. For example, Favorite Color. The display name can contain a maximum of 128 characters.
    Description | Type an identifying description for the new site term.

  5. In the Terms section, do the following:
    Use this | To do this
    Term Name | Click New and then type a programmatic name for the new term. A term is a value of the site term. For example, you might type Red, Blue, Green, and Yellow as terms for the Favorite_Color site term. The name can contain a maximum of 128 alphanumeric characters and the underscore (_) symbol. The name cannot contain spaces.
    Display Name | Type a display name for the new term. The display name can contain a maximum of 128 characters.

  6. Click Accept.

    Note

    • You can add as many terms for the new site term as you need. Click New to add another term.
  7. To save the new site term and return to the Business Desk screen, click Apply and then click Save and go back on the toolbar.

The site term is saved. You can now use the site term as the value of a profile property by adding the site term to a profile property. For example, you create a Favorite_Color site term, and then add the Favorite_Color site term as the value for the Favorite Color property in the User object profile definition. When the user answers the Favorite Color question on your Web site, they will select their favorite color from a drop-down list containing the terms you typed in the Favorite_Color site term.

See Also

About Users

Adding a Site Term Group

Adding a Site Term to a Profile Definition


Adding a Site Term Group

You use the Site Terms Editor module to create site term groups, which organize related site terms in the Site Terms Editor. For example, if you are creating postal code site terms, you could create a site term group for each state or region, and within each state or region group, create a site term for each city containing the postal codes for that city. Site term groups appear in the Site term structure list in the Site Terms Editor screen with a directional arrow to the left of the group name. You click the directional arrow to expand the list of site terms.

To create a site term group

  1. In Users, click Site Terms Editor.

  2. In the Site Terms Editor screen, click Add.

  3. In the Add dialog box, select Add a new group, and then click OK.

  4. In the Site Terms Editor screen, in the Attributes section, do the following:
    Use this | To do this
    Name | Type a programmatic name for the new term group. The name can contain a maximum of 128 alphanumeric characters, and the underscore (_) symbol. The name cannot contain spaces.
    Display name | Type a display name for the new term group. The display name can contain a maximum of 128 characters.
    Description | Type a description for the new site term group.

  5. To save the new site term group and return to the main Business Desk screen, click Apply, and then click Save and go back on the toolbar.

The site term group is saved. You can now use the site terms group to organize your site terms.

See Also

About Users

Adding a Site Term

Editing Site Terms


Adding Properties to a Profile Definition

You use the Profile Designer module to add properties to profile definitions, and define the attributes of the new property. Profile properties specify the data that is to be collected when a user visits your Web site. For example, the profile property First Name specifies that the first name of the user should be collected.

Each profile property has attributes that define the characteristics of the information the property collects. For example, you can use the attributes of the profile property First Name to define the property as a single-valued string that can be exported to the Data Warehouse. You can also use the Profile Designer to add custom attributes to a profile property. You use custom attributes to define profile property characteristics that are not available in the existing attributes. For information about profile property attributes, see Profile Designer.

To add a new property

To add a custom attribute

To add a new property

  1. In Users, click Profile Designer.

  2. In the Profiles screen, select the profile definition you want to add a property to, and then click [image] on the toolbar.

  3. In the Profile screen, in the Properties list, select the group you want to add a property to, and then click Add.

  4. In the Add dialog box, select the Add a new property option, and then click OK.

  5. In the Attributes section, do the following:
    Use this | To do this
    Name | Type a programmatic name for the property. The name can contain a maximum of 128 alphanumeric characters and the underscore (_) symbol. The name cannot contain spaces.
    Display name | Type a display name for the property. The display name can contain a maximum of 128 characters.
    Description | Type a description for the property.
    Type Select the property type from the drop-down list. Properties can be of the following types:
    • String

    • Long String

    • Number

    • Decimal

    • Boolean

    • Binary

    • Long Binary

    • Date/Time

    • Currency

    • Password

    • Site Term

    • Profile

    For information about adding a property of the type site term to a profile definition, see Adding a Site Term to a Profile Definition.

    For information about adding a property of the type profile to a profile definition, see Adding a Profile Definition to a Profile Definition.

  6. In the Advanced Attributes section, do the following:
    Use this | To do this
    Active | Select whether the new property is Active or Inactive.
    Map to data Click the ellipsis […] button to open the Data Source Picker dialog box.

    In the Data Source Picker dialog box, select the data member for the property. The data members available for the property are the data members that are not already used in the profile definition you are editing. Properties that are being used by the profile definition are unavailable.

    If you do not map the property to a data member, the property will not be persisted, but will be available in memory, for example to store state information while a user is visiting your Web site.

    Key type Select a key type from the drop-down list:

    Unique Key. Indicates that the value of this property is unique for all members. You map an attribute that is specified as a unique key to a unique field in a SQL Server database or to a unique attribute in a Lightweight Directory Access Protocol (LDAP) source.

    Primary Key. Indicates that the value of this property is unique for all members You map an attribute that is specified as a primary key to a primary field in a SQL Server database or to a unique attribute in a LDAP source.

    Join Key. Relates this property to another property in another data store in the Profile Service.

    Dual (Primary and Join) Key. Indicates that the value of this property is unique, and relates this property to a property in another data store.
    Required | Specify that the property requires user input.
    Exported | Specify that this property is to be imported into the Data Warehouse.
    Defer cache load | Specify that the property will not be returned until explicitly requested.
    Multi-valued | Specify that the property accepts multi-valued attributes.
    Searchable | Specify that the property will be available to the search function of the Web site.
    RDN | Mark this property as the Relative Distinguished Name (RDN) for all profiles to be mapped to Lightweight Directory Access Protocol (LDAP) sources. This does not apply to OLE DB Provider for Microsoft Commerce Server (OLE DB) sources, or any other data source type.
    Hashing key | Indicate that this property value will be hashed and used to determine which data source partition the profile data will be stored in.

  7. To save the property, click Apply, and then click Save on the toolbar to save the profile.

The profile definition is saved with the new property. After you add a property to a profile definition, you must publish the changes on your Web site. For information about publishing your changes, see Publishing Profile Definition Changes on Your Web Site.

To add a custom attribute

  1. In Users, click Profile Designer.

  2. In the Profiles screen, select the profile definition that contains the property to which you want to add a custom attribute, and then click [image] on the toolbar.

  3. In the Profile screen, in the Properties list, expand the group that contains the property you want to add a custom attribute to, and then select the property.

  4. In the Custom Attributes section, click New, and then do the following:
    Use this | To do this
    Name | Type a programmatic name for the attribute. The name can contain a maximum of 128 alphanumeric characters and the underscore (_) symbol. The name cannot contain spaces.
    Display name | Type a display name for the attribute. The display name can contain a maximum of 128 characters.
    Description | Type a description of the attribute.
    Value | Type the value of the attribute.

  5. Click Accept.

    Note

    • Repeat steps 4 and 5 to add as many custom attributes as you need for this property.
  6. To save the profile definition with the new custom attribute and return to the Profiles screen, click Apply and then click Save and go back on the toolbar.

The profile definition is saved with the new custom attribute. After you add a custom attribute to a profile definition, you must publish the changes on your Web site. For information about publishing your changes, see Publishing Profile Definition Changes on Your Web Site.

See Also

About Users

Adding a Property Group to a Profile Definition

Adding a Site Term to a Profile Definition


Adding a Property Group to a Profile Definition

You use the Profile Designer module to add property groups to profile definitions. You use property groups to organize profile properties in the Profile Designer. For example, you add 50 properties to the User object profile definition to gather data about the product preferences, lifestyles, and current event opinions of the users who visit your Web site. You can create property groups, such as Product, Lifestyle, and Opinions to organize the properties so that they are easy to find in the Properties list in the Profile Designer screen.

Property groups appear in the Properties list in the Profile Designer screen with a directional arrow to the left of the group name. You click the directional arrow to expand the list of properties.

To add a new property group

  1. In Users, click Profile Designer.

  2. In the Profiles screen, select the profile definition to which you want to add a new property group, and then click Open on the toolbar.

  3. In the Profile screen, in the Properties list, select the group to which you want to add a new property group, and then click Add.

    Note

    • If you want to create a property group that does not belong to an existing group, do not select an existing group before you click Add.
  4. In the Add dialog box, select the Add a new group option, and then click Yes.

  5. In the Attributes section, do the following:
    Use this | To do this
    Name | Type a programmatic name for the new property group. The name can contain a maximum of 128 alphanumeric characters and the underscore (_) symbol. The name cannot contain spaces
    Display name | Type a display name for the new property group. The display name can contain a maximum of 128 characters.
    Description | Type a description for the new property group.

  6. To save the profile defintion and return to the Profiles screen, click Apply and then click Save and go back on the toolbar.

The profile definition is saved with the new property group. You can now move existing properties into the new group, or create new properties inside the new group. After you add a profile definition to a group, you must publish the changes on your Web site. For information about publishing your changes, see Publishing Profile Definition Changes on Your Web Site.

See Also

About Users

Adding Properties to a Profile Definition

Editing Profile Properties


Publishing Profile Definition Changes on Your Web Site

You must publish profile definition changes before you can add data to new profile properties. You use the Publish Profiles module to update your Web site with your latest changes. In most e-commerce businesses, these changes are first made to a test site, and then at a scheduled times, the changes are published to your production site. Contact your system administrator for information about when and how changes are made to your production site.

To publish profile changes

  1. In Users, click Publish Profiles.

  2. In the Publish Profiles screen, select the site that you want to publish profile definition changes to, and then click Publish profile changes to production and refresh the cache on the toolbar.

    Notes

    • If multiple Web servers serve your site, you will need to publish profile definition changes to each Web server.

    • You can reset the refresh status by clicking Reset refresh status on the toolbar. Resetting the refresh status does not reset or roll-back changes that have been previously published.

Profile definition changes are published to your Web site.

See Also

Profile Designer

Managing Profile Definitions


Adding a User

You use the Users module to add a profile for a new user to your site. If you want to associate the user with an organization, you must create the organization profile in the Organizations module before you can associate a user profile with the profile of that organization.

Note

  • Your New User screen may not contain the same properties that are included in this procedure. The properties in the New User screen are controlled by the User object profile definition. If you have changed the properties in the User object profile definition, those changes will be reflected in the New User screen. For information about changing the properties of a profile definition, see Managing Profile Definitions.

To add a new user

  1. In Users, click Users.

  2. In the Users screen, click Add on the toolbar.

  3. In the New User screen, in the General information section, do the following:
    Use this | To do this
    Logon name | Type a logon name for the new user.
    User password | Type a password for the new user.
    E-mail | Type an e-mail address for the new user.
    User type | Select whether the new user is a Registered or a Guest user from the drop-down list. Typically, you will only create registered users.
    User title | Type a title for the new user, such as Mr. or Mrs.
    Last name | Type a last name for the new user.
    First name | Type a first name for the new user.
    Telephone number | Type a telephone number for the new user.
    Telephone extension | Type a telephone number extension for the new user.
    Fax number | Type a facsimile machine telephone number for the new user.
    Fax extension | Type a facsimile machine telephone number extension for the new user.

  4. In the Account Info section, do the following:
    Use this | To do this
    Account status | From the drop-down list, select if the user has an Active Account or an Inactive Account. The default status is Active Account. Users with inactive accounts will not be able to login on your site.
    User catalog set | From the drop-down list, select the catalog set you want the user to have access to.

    Note

    • If you want to set up the Organization ID for the user, you must create the organization first, in the Organizations module, before you can associate the user with that organization.
  5. In the Business Desk section, do the following:
    Use this | To do this
    Partner service role flags | From the drop-down list, select if the user is a Normal User or an Administrator. The default role flag is Normal User. Administrator users are delegated administrators, and have extended access for their organization (for example, reviewing orders and creating user profiles) in a site that supports delegated administrators.

  6. To save the new user profile and return to the Users screen, click Save and go back on the toolbar.

The new user profile is saved.

See Also

About Users

Deleting Users

Finding a User

Adding an Organization


Importing a List of User Profiles

You use the Users module to import a list of user profiles from the List Manager module. You create a users list by exporting a static user report from the Reports module to the List Manager module. For example, you might export the New Registered Users report or the Registered User Properties report as a list to List Manager. You can also import an ASCII-delimited users list into the List Manager module. After a user list is in the List Manager module, you use the Find function in the Users module to bring the list of users into the Users module.

To import a list of user profiles into List Manager

  1. In Users, click Users. If the Find pane is not open on the Users screen, click Find on the toolbar.

  2. In the Find By drop-down box, select User lists.

  3. A list of user lists from List Manager appears in the Find pane.

  4. Select the user list you want to open in the Users module.

  5. Click Find Now.

The user profiles from the List Manager list are available in the Users module. You can edit the profiles individually or in groups. After you save the changes to the user profiles, the modified data is available on your Web site.

See Also

Editing a User

Editing Multiple Users

Exporting a Static Report


Adding an Organization

You use the Organizations module to add organization profiles to your site and specify information for them, such as their identification and contact information, and the catalog set that you are making available to them. If you want to add an administrative contact or a receiver to an organization profile, you must first create the organization profile, and then create a user profile for the user who belongs to the organization. After you create a user profile for the user who belongs to the organization, you can add that user profile as an administrative contact or receiver to that organization profile.

To add an organization profile

To associate a user profile with an existing organization profile

To associate an organization profile with an existing user profile

To add an organization profile

  1. In Users, click Organizations.

  2. In the Organizations screen, click Add on the toolbar.

  3. In the New Organization screen, in the General information section, do the following:
    Use this | To do this
    Name | Type the name of the organization. Organization names can be up to 53 alphanumeric characters long. The name can contain spaces.
    Trading partner number | Type the number of the organization or trading partner.
    Organization catalog set | From the drop-down list, select the catalog set you want the organization to have access to.

  4. To save the organization profile and return to the Organizations screen, click Save and go back on the toolbar.

The new organization profile is saved. You can now associate a user profile with this organization profile.

To associate a user profile with an existing organization profile

  1. In Users, click Users.

  2. In the Users screen, select the user profile you want to edit, and then click Open on the toolbar.

  3. In the Update User: <user> screen, in the Account Info section, in the Organization Id box, click the ellipsis […] button to display the Select Organization dialog box.

  4. In the Select Organization dialog box, do the following:
    Use this | To do this
    Choose the organization this user belongs to | Select the organization the user belongs to from the list.
    Name Type the name of the organization (if it does not appear in the Choose the organization this user belongs to list), and then click Find Now.

    When the organization appears in the Choose the organization this user belongs to list, select the organization.

  5. Click OK.

  6. To save the new user profile and return to the Users screen, click Save and go back on the toolbar.

The user profile is saved. You can now add this user profile to the organization profile as an administrative contact, receiver, or purchasing manager. You can only add user profiles to an organization profile that has been saved.

To associate an organization profile with an existing user profile

  1. In Users, click Organizations.

  2. In the Organizations screen, select the organization profile you want to associate user profiles with, and then click Open on the toolbar.

    Note

    • You can use the Find pane to find organization profiles by Name, Date last changed, or Date created. For information about finding an organization profile, see Finding an Organization.
  3. In the Update Organization: <organization> screen, in the General information section, in the Administrative Contact box, click the ellipsis […] button to open the Select User dialog box.

  4. In the Select User dialog box, do the following:
    Use this | To do this
    Choose an existing user | Select the name of the user you want to add as the administrative contact, and then click OK.
    Logon name Type the name of the user you want to add as the administrative contact (if it does not appear in the Choose an existing user list), and then click Find Now.

    When the user appears in the Choose an existing user list, select the user.

  5. Click OK.

  6. In the General information section, in the Receiver box, click the ellipsis […] button to opent the Select User dialog box.

  7. In the Select User dialog box, do the following:
    Use this | To do this
    Choose an existing user | Select the name of the user you want to add as the receiver, and then click OK.
    Logon name Type the name of the user you want to add as the receiver (if it does not appear in the Choose an existing user list), and then click Find Now.

    When the user appears in the Choose an existing user list, select the user.

  8. Click OK.

  9. In the Purchasing section, in the Purchasing manager box, click the ellipsis […] button to open the Select User dialog box.

  10. In the Select User dialog box, do the following:
    Use this | To do this
    Choose an existing user | Select the name of the user you want to add as the purchasing manager, and then click OK.
    Logon name Type the name of the user you want to add as the purchasing manager (if it does not appear in the Choose an existing user list), and then click Find Now.

    When the user appears in the Choose an existing user list, select the user.

  11. Click OK.

  12. To save the organization and return to the Organizations screen, click Save and go back on the toolbar.

The organization profile is saved with the administrative contact, receiver, and purchasing manager.

See Also

About Users

Editing an Organization

Finding an Organization


Resetting a User Password

You use the Users module to reset passwords for registered users who have forgotten theirs. After you reset the password for the user, you must inform the user of the new password.

To reset a user password

  1. In Users, click Users.

  2. In the Users screen, select the profile for the user whose password you want to reset, and then click Open on the toolbar.

    Note

    • To display the profile for a particular user, use the Find pane at the top of the Users screen. For information about finding a user profile, see Finding a User.
  3. In the Update user screen, in the General information section, in the User Password box, select the current password, which appears as a row of asterisks.

  4. Type the new password.

    Note

    • Passwords must contain 7 to 14 alphanumeric characters. Passwords cannot contain spaces.
  5. To save the new password and return to the Users screen, click Save and go back on the toolbar.

The user profile is saved with the new password. You must advise the user what the new password is.


Managing Site Terms and Groups

You use the Site Terms Editor module to create and update site terms. You use site terms to standardize and restrict choices when you request user input, and you use them to target content to users. For example, you can limit the colors users can select when choosing their favorite color.

This section contains:

  • Adding a Site Term to a Profile Definition

  • Editing Site Terms

  • Deleting a Term from a Site Term

  • Rearranging Site Terms

  • Deleting Site Terms


Adding a Site Term to a Profile Definition

After you create a site term, you can add it to a profile definition.

To add a site term to a profile definition

  1. In Users, click Profile Designer.

  2. In the Profiles screen, select the profile definition that contains the property you want to edit, and then click Open on the toolbar.

  3. In the Profile screen, in the Properties list, select the property that you want to add the site term to.

    Note

    • If the property is not visible in the Properties list, expand the property group that contains the property you want to add the site term to, and then select the property.
  4. In the Attributes screen, in the Attributes section, select Site Term from the Type drop-down list.

  5. In the Type Reference box, click the ellipse [...] button to open the Site Term Selection dialog box.

  6. In the Site Term Selection dialog box, in the Select a Site Term list, expand the site term group that contains the site term you want to add to the property definition, and then select the site term.

  7. Click OK.

  8. To save the edited profile definition and return to the Profiles screen, click Apply and then click Save and go back on the toolbar.

The profile definition is saved. You must publish profile definition changes on your Web site. For information about publishing your changes, see Publishing Profile Definition Changes on Your Web Site.

See Also

Adding a Site Term

Adding Properties to a Profile Definition

Editing Profile Properties

Editing Site Terms


Editing Site Terms

You use the Site Terms Editor module to edit existing site terms and site term groups.

To edit a site term

  1. In Users, click Site Terms Editor.

  2. In the Site Terms Editor screen, select the site term that you want to edit.

  3. In the Site Terms Attributes section, do the following:
    Use this | To do this
    Display name | Edit the display name of the site term. The display name can contain a maximum of 128 characters.
    Description | Edit the description of the site term.

    Note

    • You can change the display name of a site term; however, you cannot change the programmatic name of a site term. If you want to change the programmatic name of a site term, you must delete the site term, and then create a new site term with the name that you want to use.
  4. In the Terms section, select the term you want to edit, and then click Edit.

  5. Edit the term as needed, and then click Accept.

    Note

    • You can edit as many terms as you need. Click Edit to edit another term. You can also add and delete terms. Click New to add a new term. Click Remove to delete a selected term.
  6. To save the site term and return to the Business Desk screen, click Apply, and then click Save and go back on the toolbar.

The site term is saved.

See Also

About Users

Adding a Site Term

Adding a Site Term Group

Adding a Site Term to a Profile Definition


Deleting a Term from a Site Term

You use the Site Terms Editor module to delete terms. For example, you might delete "purple" from the Color site term.

To delete a term

  1. In Users, click Site Terms Editor.

  2. In the Site Terms Editor screen, select the site term from which you want to delete a term.

  3. In the Terms section select the term you want to delete from the terms list, and then click Remove.

    The term is deleted from the Terms list.

  4. Click Apply to save the change to the site term attributes.

  5. To save the edited site term and return to the Business Desk screen, click Save and go back on the toolbar.

The edited site term is saved.

See Also

About Users

Adding a Site Term

Adding a Site Term Group


Rearranging Site Terms

You use the Site Terms Editor module to organize site terms and site term groups. You can move site terms and groups up and down in the Site term structure list. You can change which group a site term belongs to by moving the site term between groups.

To move a site term

  1. In Users, click Site Terms Editor.

  2. In the Site Terms Editor screen, select the site term or group you want to move.

  3. Click the up and down arrows below the Site term structure list to move the site term or group to a new location.

  4. To save your changes and return to the Business Desk screen, click Save and go back on the toolbar.

The site term is saved.

See Also

About Users

Adding a Site Term

Adding a Site Term Group


Deleting Site Terms

You use the Site Terms Editor module to delete site terms and site term groups.

To delete a site term

  1. In Users, click Site Terms Editor.

  2. In the Site Terms Editor screen, select the term or group you want to delete and click Remove.

  3. In the Delete dialog box, click OK to delete the site term.

    Caution

    • If you delete a site term group, all site terms within that group are also deleted.
  4. To save your changes and return to the Business Desk screen, click Save and go back on the toolbar.

See Also

About Users

Adding a Site Term

Adding a Site Term Group


Managing Profile Definitions

You use the Profile Designer module to add, edit, and remove profile properties. As your need for user and organization information changes, you can edit the existing profile definitions to meet your new requirements.

This section contains:

  • Adding a Profile Definition to a Profile Definition

  • Editing Profile Properties

  • Deleting Properties from a Profile Definition


Adding a Profile Definition to a Profile Definition

You can add a profile definition to a profile definition. You can define a property in a profile definition as a profile, and then reference a profile definition to the property. For example, you can connect address information to the User object profile definition by adding a property to the User object profile definition called "Address," defining the Address property as a profile with the Type attribute, and then selecting the Address profile definition as the Type Reference of the Address property. You map the new Address property to a data member of type string, which will store the name of the instance of the profile containing the address of the user. You can use this procedure to connect several addresses to the User object profile definition. For example, you can create a billing address property and a shipping address property, both of which use the Address profile definition to gather address information for the user.

In this example, the value of the address property in the user profile is the name of the address profile containing the address for the user. The system administrator can use the address property in the user profile to present the address for the user with the profile information for the user.

To add a profile definition to a profile definition

  1. In Users, click Profile Designer.

  2. In the Profiles screen, select the profile definition that you want to add a profile definition to, and then click Open on the toolbar.

  3. In the Profile screen, in the Properties list, select the property that you want to add the profile definition to.

    Note

    • If the property is not visible in the Properties list, expand the property group that contains the property you want to add the profile definition to, and then select the property.
  4. In the Attributes section, select Profile from the Type drop-down list.

  5. In the Type Reference box, click the ellipse button [...] to open the Profile Selection dialog box.

  6. In the Profile Selection dialog box, in the Select a Profile list, expand the Profile Catalog, and then select the profile definition you want to add to the property.

  7. Click OK.

  8. To save the edited property and return to the Profiles screen, click Apply, and then click Save and go back on the toolbar.

The edited profile definition is saved.

See Also

Profile Designer

Adding Properties to a Profile Definition

Editing Profile Properties


Editing Profile Properties

You use the Profile Designer module to edit profile properties and property groups which are used in profile definitions.

To edit a profile property

  1. In Users, click Profile Designer.

  2. In the Profiles screen, select the profile that contains the property you want to edit, and then click Open on the toolbar.

  3. In the Profile screen, in the Properties list, select the property or property group that you want to edit.

    Note

    • If the property is not visible in the Properties list, expand the property group that contains the property you want to edit, and then select the property.
  4. Edit the attributes of the property.

    Note

    • You cannot edit the name of a property after it has been created. You can edit the display name, but the actual programmatic name remains static. If you want to change the programmatic name, you must delete the property and add it again with the new programmatic name.
  5. To save the edited property and return to the Profiles screen, click Apply, and then click Save and go back on the toolbar.

The edited profile definition is saved. After you edit a property in a profile definition, you must publish the changes on your Web site. For information about publishing your changes, see Publishing Profile Definition Changes on Your Web Site.

See Also

About Users

Adding Properties to a Profile Definition

Adding a Property Group to a Profile Definition

Deleting Properties from a Profile Definition

Adding a Site Term to a Profile Definition


Deleting Properties from a Profile Definition

You use the Profile Designer module to delete properties and property groups from a profile definition.

To delete a profile property

  1. In Users, click Profile Designer.

  2. In the Profiles screen, select the profile definition you want to delete a property from, and then click Open on the toolbar.

  3. In the Profile screen, in the Properties list, select the property that you want to delete.

    Note

    • If the property is not visible in the Properties list, expand the property group that contains the property you want to delete, and then select the property.
  4. Click Remove.

  5. In the Delete dialog box, click OK to delete the property.

  6. To save your changes and return to the Profiles screen, click Save and go back on the toolbar.

The edited profile definition is saved. After you delete property in a profile definition, you must publish the changes on your Web site. For information about publishing your changes, see Publishing Profile Definition Changes on Your Web Site.

See Also

About Users

Adding Properties to a Profile Definition

Adding a Property Group to a Profile Definition

Editing Profile Properties

Managing Site Terms and Groups


Managing Users

You use the Users module to find, edit, and manage user information.

This section contains:

  • Finding a User

  • Editing a User

  • Editing Multiple Users

  • Copying Users

  • Deleting Users


Finding a User

You use the Users module to search your Web site for a user profile or a group of user profiles. You can use the Find dialog box to narrow your search using the properties of the User object profile definition and the values of the user profile you are searching for. For example, you can search for a user profile that contains the value "Mike," in the profile property "First Name." The resulting list in the Find pane contains all the user profiles that match your search criteria.

To find a user profile

To create an expression to find a user profile

To find a user profile

  1. In Users, click Users. If the Find pane is not open on the Users screen, click Find on the toolbar.

  2. In the Find By drop-down box, do the following:
    Use this | To do this
    Logon name | Search for a user profile by logon name.
    E-mail | Search for a user profile by e-mail address.
    Last name | Search for a user profile by last name.
    First name | Search for a user profile by first name.
    Account status | Search for a user profile with an active or inactive account.
    Date registered | Search for a user profile by the date the user registered.
    Partner service role flags | Search for a user profile for a user who is a Normal User or Administrator.
    Date last changed | Search for a user profile that was edited on a particular date.
    Date created | Search for a user profile that was created on a particular date.
    User lists | Open a user list from the List Manager module.

  3. In the property value box that appears next, type or select from the list the specific value for the properties that you selected (for example, the last name or e-mail address of the user profile you are searching for).

  4. If you need a more elaborate search, select Find By Property from the Find By drop-down list, and create an expression to search on.

    Note

    • You may include a wildcard entry (*) to match any number of characters in your search. For example, t* matches any user whose name begins with the letter "t".
  5. Click Find Now.

Caution

  • When searching for user profiles, it is important to restrict your search criteria to control the number of user profiles matching your search parameters. If a large number of user profiles match your search criteria, the results could cause a significant decrease in your Commerce Server Business Desk performance.

The search is performed. If your search is successful, the user profiles you searched for will appear in the users list. If your search is not successful, the phrase, "No items match this search," will appear in the users list.

To create an expression to find a user profile

  1. In Users, click Users. If the Find pane is not open at the top of the users list, click Find on the toolbar.

  2. Select Find by property from the Find by drop-down list.

  3. Click New in the Find pane.

  4. In the first drop-down list, click the arrow to the right of the profile definition, double-click the property group, and then select the property you want to use in the search.

    Note

    • The property type of the property you select determines the conditions that are available for your search. For example, if the property you select is of type string, you will be able to set the condition of your search to is equal to, contains, or begins with. If the property you select is of type site term, you will be able to set the condition of your search to is equal to, or is not equal to.
  5. In the second drop-down list, select the condition for your search.

    Note

    • The property type of the property you select determines the way that you will enter the criteria for your search. For example, if the property you select is of type string, you will type the string you are searching for in the third box. If the property you select is of type site term, you will click the ellipsis [...] button to open the Choose a Site Term dialog box, and then select the term you are searching for.
  6. In the third box, type or select the criteria for your search.

  7. Click Apply, and then click Find Now.

The search is performed. If your search is successful, the user profiles you searched for will appear in the users list. If your search is not successful, the phrase, "No items match this search," will appear in the users list.

See Also

About Users

Adding a User

Editing a User

Copying Users

Deleting Users


Editing a User

You use the Users module to edit an existing user profile.

To edit a user

  1. In Users, click Users.

  2. In the Users screen, select the user profile you want to edit, and then click Open on the toolbar.

    Note

    • To display a particular user profile, you use the Find pane at the top of the Users screen. For information about finding a user profile, see Finding a User.
  3. In the Update User: <user> screen, edit the user profile.

  4. To save the user profile and return to the Users screen, click Save and go back on the toolbar.

The edited user profile is saved.

See Also

About Users

Adding a User

Copying Users

Deleting Users

Finding a User


Editing Multiple Users

You use the Users module to edit multiple user profiles. When you edit multiple user profiles, you make the same changes to all of the user profiles that you are editing.

To edit multiple users

  1. In Users, click Users.

  2. In the Users screen, select the user profiles you want to edit, and then click Open on the toolbar.

  3. In the Update <number> Users screen, do the following:
    Use this | To do this
    New | Form a new Update Query. You use an update query to change the value of a property in multiple user profiles.
    First drop-down list (left) | Select the property you want to update from the drop-down list.
    Second drop-down list (center) | Select the condition for the update.
    Third drop-down list (right) | Type or select the new value for the property. The property type of the property you selected in the first box determines the way that you will enter the change for that property. For example, if the property you select is of type string, you will type the string you are searching for in the third box. If the property you select is of type site term, you will click the ellipsis [...] button to open the Choose a Site Term dialog box, and then select the term you assigning to the property.

  4. Click Apply, and then click Save and go back on the toolbar.

The user profiles are saved with the new information.

See Also

Adding a Users

Importing a List of User Profiles

Editing a User


Copying Users

You use the Users module to copy an existing user profile. If you need to add a new user profile for a user whose profile closely resembles an existing user profile, you can copy the existing user profile, make the necessary changes to the profile information, and save the profile as the profile for a new user.

To copy a user

  1. In Users, click Users.

  2. In the Users screen, select the user profile you want to copy, and then click Copy on the toolbar.

  3. In the New User: Copy <user> properties screen, in the General information section, do the following:
    Use this | To do this
    Logon name | Type a logon name for the new user profile.
    User password | Type a password for the new user profile. Passwords must contain 7 to 14 alphanumeric characters. Passwords cannot contain spaces.

  4. Change the existing information in the copied user profile as appropriate for the new user profile.

  5. To save the new user profile and return to the Users screen, click Save and go back on the toolbar.

The new user profile is saved.

See Also

About Users

Adding a User

Editing a User

Deleting Users

Finding a User


Deleting Users

You use the Users module to remove existing user profiles from the Commerce Server database.

Caution

  • A user profile that has been deleted cannot be recovered.

To delete a user from the Commerce Server database

  1. In Users, click Users.

  2. In the Users screen, select the user profile you want to delete, and then click Delete on the toolbar.

  3. In the Delete User dialog box, click OK to delete the user profile.

    The user profile is deleted.

See Also

About Users

Adding a User

Editing a User

Copying Users

Finding a User


Managing Organizations

You use the Organizations module to maintain and update organization profiles.

This section contains:

  • Finding an Organization

  • Editing an Organization

  • Editing Multiple Organizations

  • Copying an Organization

  • Deleting an Organization


Finding an Organization

You use the Organizations module to search for a particular organization profile. You can use the Find dialog box to narrow your search using the properties of the organization profile. The resulting list contains all the organization profiles that match your search criteria.

To find an organization profile

To create an expression to find an organization profile

To find an organization profile

  1. In Users, click Organizations. If the Find dialog box is not open at the top of the organizations list, click Find on the toolbar.

  2. In the Find By drop-down list, do the following:
    Use this | To do this
    Name | Search for an organization profile by its name.
    Date last changed | Search for organization profiles edited on a particular date.
    Date created | Search for organization profiles created on a particular date.

  3. In the property value box that appears next, type or select from the list the specific value for the properties that you selected (for example, the name of the organization you are looking for).

    Note

    • You may include a wildcard entry (*) to match any number of characters in your search. For example, t* matches all organizations whose name begins with the letter "t".
  4. If you need a more elaborate search, in the Find By drop-down list, select Find By Property and create an expression to search on.

  5. Click Find Now.

The search is performed. If your search is successful, the organization profile you searched for will appear in the organizations list. If your search is not successful, the phrase, "No items match this search," will appear in the organizations list.

To create an expression to find an organization

  1. In Users, click Organizations. If the Find pane is not open at the top of the organizations list, click Find on the toolbar.

  2. Select Find by property from the Find by drop-down list.

  3. Click New in the Find pane.

  4. In the first drop-down list, click the arrow to the right of Organization, double-click the property group, and then select the property you want to use in the search.

    Note

    • The property type of the property you select determines the conditions that are available for your search. For example, if the property you select is of type string, you will be able to set the condition of your search to is equal to, contains, or begins with. If the property you select is of type site term, you will be able to set the condition of your search to is equal to or is not equal to.
  5. In the second drop-down list, select the condition for your search.

    Note

    • The property type of the property you select determines the way that you will enter the criteria for your search. For example, if the property you select is of type string, you will type the string you are searching for in the third box. If the property you select is of type site term, click the ellipsis [...] button to open the Choose a Site Term dialog box, and then select the term you are searching for.
  6. In the third box, type or select the criteria for your search.

  7. Click Apply, and then click Find Now.

The search is performed. If your search is successful, the organization you searched for will appear in the organizations list. If your search is not successful, the phrase, "No items match this search," will appear in the organizations list.

See Also

About Users

Adding an Organization

Editing an Organization

Editing Multiple Organizations

Deleting an Organization


Editing an Organization

You use the Organizations module to edit and update existing organization profiles. You can also associate existing users as administrative contacts and as receivers with an organization.

To edit an organization profile

  1. In Users, click Organizations.

  2. In the Organizations screen, select the organization profile you want to edit, and then click [image] on the toolbar.

  3. In the Update Organization screen, in the General information section, do the following:
    Use this | To do this
    Name | Edit the name of the organization.
    Trading partner number | Edit the trading partner number of the organization.
    Administrative contact | Click the ellipsis [...] button to change the administrative contact. For information about selecting an administrative contact, see To associate an organization profile with an existing user profile.
    Receiver | Click the ellipsis [...] button to change the receiver. For information about selecting a receiver, see To associate an organization profile with an existing user profile.
    Organization catalog set | Select a catalog set for this organization from the drop-down list.

  4. In the Purchasing section, in the Purchasing Manager box, click the ellipsis [...] button to open the Select User dialog box.

  5. In the Select User dialog box, do the following:
    Use this | To do this
    Choose an existing user | Select the name of the user you want to add as the purchasing manager, and then click OK.
    Logon name Type the name of the user you want to add as the purchasing manager (if it does not appear in the Choose an existing user list), and then click Find Now.

    When the user appears in the Choose an existing user list, select the user, and then click OK.

  6. To save your edits and add additional organization profiles, click Save and create new on the toolbar.

The organization profile is saved, and a new organization profile is created.

See Also

About Users

Adding a User

Adding an Organization

Copying an Organization

Finding an Organization


Editing Multiple Organizations

You use the Organizations module to edit the profiles of multiple organizations. When you edit multiple organization profiles, you make the same edits to all of the organization profiles that you are editing.

To edit multiple organization profiles

  1. In Users, click Organizations.

  2. In the Organizations screen, select the organization profiles you want to edit, and then click [image] on the toolbar.

  3. In the Update <number> Organizations screen, do the following:
    Use this | To do this
    New | Form a new Update Query. You use an update query to change the value of a property in multiple user profiles.
    First drop-down list (left) | Select the property that contains the information you want to edit, from the drop-down list.
    Second drop-down list (center) | Select the condition for the edit.
    Third drop-down list (right) | Type or select the new value for the property. The property type of the property you selected in the first box determines the way that you will enter the change for that property. For example, if the property you select is of type string, you will type the string you are searching for in the third box.

  4. To save your edits and return to the Organizations screen, click Save and go back on the toolbar.

The organization profiles are saved with the new data.


Copying an Organization

You use the Organizations module to make copies of existing organization profiles. If you need to create a profile for an organization that shares properties with an existing organization profile, you can make a copy of the existing organization profile and then change that copy to make a new organization profile.

To copy an existing organization profile

  1. In Users, click Organizations.

  2. In the Organizations screen, select the organization profile you want to copy, and then and click Copy on the toolbar.

  3. In the New Organization: Copy <organization> properties screen, in the General information section, in the Name box, type a name for the new organization.

  4. To save the new organization profile and return to the Organizations screen, click Save and go back on the toolbar.

The new organization profile is saved. If you want to add a user as an administrative contact, receiver, or purchasing manager to this organization profile, you must first create the profile of the user who will be added to this organization, associate the user profile with this organization, and then edit the profile for this organization to add the user profile for the user who will be the administrative contact, receiver, or purchasing manager.

See Also

About Users

Adding an Organization

Editing an Organization

Deleting an Organization

Finding an Organization


Deleting an Organization

You use the Organizations module to delete organization profiles from the Organizations list.

To delete an organization

  1. In Users, click Organizations.

  2. In the Organizations screen, select the organization profile you want to delete, and then click Delete on the toolbar.

  3. In the Delete Organization dialog box, click OK to delete the organization profile.

The organization profile is deleted.

Caution

  • After you delete an organization profile you cannot recover it.

See Also

About Users

Adding an Organization

Editing an Organization

Copying an Organization

Finding an Organization


Troubleshooting Business Desk

This section addresses common problems you may encounter while using Commerce Server Business Desk. Locate a brief description of the problem in the feature area you are working in, and follow the link for more detailed information.

Your first contact for technical support is typically your system administrator or your site developer. In addition, you can access Microsoft online newsgroups. For more information about Commerce Server 2000 newsgroups go to: www.microsoft.com/commerceserver.

The following table lists the feature areas and problems that you may encounter while using Business Desk.

Area Problem
Installation
  • Business Desk does not install
Analysis
  • Cannot run reports

  • Cannot view Segment models

  • Exporting static SQL Server report fails

  • Report appears without data

  • Buyer Browse to Purchase report error

  • Static report fails to run

  • Missing member name for key number

  • SQL Server-based Dynamic reports use large amounts of memory
Campaigns
  • Cannot run Direct Mailer job

  • Direct Mailer job fails without error

  • Campaign items do not appear as expected on the Web site

  • Data does not appear in List Manager
Catalogs
  • Cannot import a catalog

  • Cannot send a catalog to a trading partner
Business Desk
  • Library not registered

  • Business Desk does not run

  • Business Desk Access Error

  • User not authorized to view page re-authentication request

  • Changes do not appear on the Web site

  • Cannot open two instances of same Business Desk

  • Full Text search in Help does not return search results


Business Desk Does Not Install

Description

When you attempt to connect to the Business Desk Web site to install the Business Desk client, the following message may appear.

Business Desk Install Error

Solution

To install Business Desk, you must enable the Microsoft ActiveX controls.

To continue the Business Desk Setup

  1. In Internet Explorer, click Tools, and then click Internet Options.

  2. In the Security tab, click Custom Level.

  3. Select Local intranet zone and click Custom level.

  4. In the ActiveX controls and plug-ins box, enable Download signed Active X controls.

  5. Click OK, click Apply, and then click OK again.

  6. Click Refresh on the toolbar, and then continue installing the Business Desk by typing the URL for Business Desk into the browser window. For example, http://<servername>/myretailbizdesk.


Cannot run reports

Description

You have attempted to run reports from the Reports module and nothing happens. If you are trying to run a static report, you receive either a failed status error or the report contains no data.

Note

  • If you are running a dynamic report, the following error message appears:

"Either EOF or BOF is true, or the current record has been deleted."

Solution

Contact your system administrator. Your system administrator must import data into the data warehouse before the report can be run successfully.


Cannot view Segment models

Description

When you open the Segment Viewer in Business Desk, the screen is blank.

Solution

Contact your system administrator. Your system administrator must build Segment models before you can view them.


Exporting static SQL Server report fails

Description

If you are using Microsoft SQL Server 7.0 with Commerce Server and you export a static SQL Server report as a list to the List Manager module, and the export fails, the problem may be that the SQL Server column names contain characters that are not valid, such as ~`!@#$%^&*()-_+={}[]|\:;<,>.?/'.

Solution

Ask your system administrator to verify that all the characters in your SQL Server column names are valid. Rerun the report.


Report appears without data

Description

Your dynamic report appears in the browser window without any data. Business Desk supports up to 250,000 members per dimension in dynamic reports. If you run a dynamic report against a data set that contains more than 250,000 members per dimension, Office 2000 Web Components (OWC) times out, and the report appears in the browser window without any data.

Solution

If your data contains dimensions larger than 250,000 members, contact your system administrator to request a custom static report to analyze the data.


Buyer Browse to Purchase report error

Description

You have attempted to run the Buyer Browse to Purchase report and an error message appears.

Solution

Contact your system administrator. Your system administrator can access the solution to this error in Commerce Server 2000 Help.


Static report fails to run

Description

When you attempt to run a static report, no report is generated and all the task bar buttons are disabled. An error message appears stating that an Internet Information Services (IIS) Com failure has occurred when IIS is Reset.

Solution

Contact your system administrator and make certain that Internet Information Services (IIS) 5.0 has not been reset while you were running static reports. If IIS has been reset, close Business Desk and then reopen it. Then run the static report again.


Missing member name for key number

Description

If you are running the Ad Placement – PageGroup dimension report or the Product Sales – Customer dimension report you may see "Missing Member Name for Key#" in the report. This error is caused because data imported into the data warehouse is missing required unique values.

Solution

Ad Placement report: Contact your system administrator to run the Campaign data import Data Transformation Services (DTS) task and then rerun the Report preparation DTS task. If the problem still persists, contact your system administrator. This case happens when the data has been deleted from the source database.

Products Sales Report: Run the User profile data import DTS task and then rerun the Report preparation DTS task. If the problem persists, contact your system administrator. This happens when the data has been deleted from the source database.


SQL Server-based dynamic reports use large amounts of memory

Description

When you run a SQL Server-based dynamic report, the PivotControl will try to load all data into memory before displaying the report. For example, running the Ad Reach and Frequency per Campaign Item report, with 400,000 rows in one of the primary tables, results in the system memory jumping to about 700MB.

Solution

Be aware of memory use when you run SQL Server-based dynamic reports and plan accordingly.

See also

Creating a New Dynamic Report


Cannot run Direct Mailer job

Description

You have a Direct Mailer job that has not run, and you have not received any error messages.

Solution

Contact your system administrator. If the Direct Mailer job is a personalized direct mail campaign, the system administrator may have blocked the direct mail job for performance reasons. If you do not have a dedicated Web server for direct mail, the system administrator may have set the campaign item to start at a low traffic time since it will be hitting the Web server just like users. Depending on the volume of the direct mail list, this could affect Web server performance.


Direct Mailer job fails without error message

Description

If you have a Direct Mailer job that has failed to start, and you have not received an error message informing you of the reason for the failure.

Solution

Contact your system administrator. This failure may be caused by one of several conditions. For example, if SQL Server Agent is stopped when a scheduled Direct Mail job is scheduled to run, the job will not run, and the failure is not logged. There is no indication that the job did not run. Your system administrator must start the job manually from the SQL Server Agent control in SQL Server Enterprise Manager.


Campaign items do not appear as expected on the Web site

Description

Ad campaign items and discount campaign items that have been created do not appear on the Web site.

Solution

When you create new ads using the Campaign Manager module, the ad is inactive until you publish the ad or it is detected in the regular refresh cycle. By default ads are automatically published every five minutes. Discounts, however, must be published and are not automatic. Also, if you have created an ad or discount in advance and left it inactive, you need to reopen the ad or discount and activate it.

Note

  • Before you update an ad campaign on a new site, you must first visit the Web site. Each server in the Web farm must be updated before a campaign item can be sent to production.

The following table lists additional situations to check for if your ad or discount is not appearing on the Web site.

Description | Solution
Has the campaign item been published? | Use the Publish Campaigns module to publish your campaign.
Is the ad or campaign item status inactive? | Open the ad or campaign item and change the status to active.
Have you defined a quantity or weight? | For paid ads, you need to specify a quantity or weight for the ad campaign.
Are there conflicting targeting, industry code, or exposure limits? | Check to see if any targeting, industry code, or exposure limits relating to this ad might be preventing it from running.
Is the ad or campaign date out of range? | Check to see if the ad or campaign date is too far into the future.
Is another ad appearing in place of the ad you expect to see? | Check to see if there is another ad with a higher need of delivery that is overriding your ad.
Is the ad set to run on old page groups? | If you have redesigned your Web site, the ad might be scheduled to run on previous page groups. You must set up new ads if you have a new Web site.
Is the ad a house ad? | If the ad is set up as a house ad it will not appear on the Web site until all paid ads are meeting their Need of Delivery.
Is a targeting expression preventing the ad from appearing? | If site visitor properties do not meet the definition of the targeting expression, the ad will not appear.
Is the ad space limited by size? | If the Web site ad space is limited to a specific content size and your ad is not of that size, your ad will not appear.


Data does not appear in List Manager

Description

Performing update operations or find by operations against large user data sets through the Users module may result in the process timing out.

The operation may time out depending upon a variety of factors and you may be unable to view the data. One factor could be the large number of entities being retrieved.

Solution

Contact your system administrator for assistance. Your system administrator can find the solution to this error in Commerce Server 2000 Help.


Cannot import a catalog

Description

When you attempt to import a catalog, the import fails. If, for example, the catalog file is located in C:\Documents and Settings\<UserName>\Desktop, the import fails because of the location. The message "Catalog import process has been started successfully" appears but when you click Catalog Editor to reload the page, the catalog is not imported.

Solution

Contact your system administrator. When you run Business Desk in Internet Information Services (IIS) Medium Isolation mode, you do not have access to system folders like Desktop. To import the file from the desktop, your system administrator will need to switch Business Desk into Low Isolation mode.

The following table lists additional situations to check for if the Catalog import does not complete.

Description | Solution
You have imported a catalog and you get a message stating that the import is in progress. However, when you click on Catalog Editor to reload the page, the catalog does not appear. | If you import a catalog that contains a product definition with properties that differ from an existing product definition of the same name, the import fails. Make certain that product definition properties are consistent throughout all catalogs.
Using Catalog Editor, you have attempted to import an XML catalog, but the import fails. | Make certain you are using the complete file path and name for the catalog or that the catalog is in the CommerceCatalogs share on the server running the Business Desk application. Your system administrator can assist you by getting the catalog onto the server.


Cannot send a catalog to a trading partner

Description

You have created a trading partner catalog and cannot send it to a trading partner.

Solution

Verify that your system administrator has set up Microsoft BizTalk Server 2000 and has properly configured Commerce Server for document exchange.


Library not registered

Description

You receive the message "Library not registered" while using Business Desk.

Solution

You may need to re-register the Vbscript.dll found in the \winnt\system32 directory. Contact your system administrator for assistance.


Business Desk does not run

Description

Although you have been running Business Desk without incident, you receive one of the following error messages when you attempt to start it:

  • Errors occurred while loading part of the Business Desk.

  • Errors while loading Business Desk application.

Solution

If the system administrator password has changed on the Web server hosting the Business Desk application that change might result in the above error. Your system administrator can find the solution to this error in Commerce Server 2000 Help.


User not authorized to view page - reauthentication request

User not authorized to view page – reauthentication request

Description

Business Desk unexpectedly displays a request for your user name and password, or you receive an error message stating that the user is not authorized to view the page, or the Enter Network Password dialog box reappears even after you have entered the correct logon information.

Solution

If your Business Desk is running on a different Web server than your Commerce Server, the one running Commerce Server may be out of memory. Contact your system administrator for assistance.


Business Desk Access Error

Description

Although you have been running Business Desk without incident, you are unable to start Business Desk. When you attempt to open a particular module, you receive the message "Business Desk Access Error".

Solution

The module you are attempting to open requires user rights that you do not have. Contact your system administrator to have these access rights granted.


Changes do not appear on the Web site

Description

You have made changes in Business Desk, but when you view your Web site, these changes do not appear.

Solution

You may need to refresh Commerce Server caches. To do so, use the Publish Campaigns module, Publish Transactions module, or Publish Profiles module to update your site. You may also need to publish catalogs using the Publish Custom Catalogs toolbar button in the Catalog Editor module.


Cannot open two instances of the same Business Desk

Description

You attempt to open two instances of the same Business Desk client for the same site on your computer, but Business Desk does not open.

Solution

You cannot open two instances of the same Business Desk client for the same site on your computer. However, you can run two Business Desk clients for different sites at the same time.


Full Text search in Help does not return search results

Description

When you do a search in Business Desk Help, the search does not return any results.

Solution

Contact your system administrator to start the Indexing Service on the Web server hosting the Business Desk application. Indexing Service should always be set to Autostart as there may be significant lag time between when the Indexing Service starts and when the folder holding the help content is available.


Extending Commerce Server

Microsoft Commerce Server 2000 can be extended in many ways. For example:

  • Custom resources and custom Commerce Server Business Desk modules can be written and integrated into Commerce Server Manager and Business Desk, respectively.

  • The pipeline processing used for order processing, content selection, and direct mailing can be extended by writing and integrating new pipeline components.

  • New types of data can be stored in the Data Warehouse, and new reports can be created to allow analysis of that data.

These extensions, and others, are described in this section.

This section contains:

  • Integrating Custom Resources. Explains how to integrate a custom resource into Commerce Server.

  • Building Business Desk Modules. Explains how to build a new Business Desk module. This includes general architectural information, information about integrating new modules, and reference material about the HTML Components available for use in new modules.

  • Building Pipeline Components. Explains how to build new pipeline components in both C++ and Microsoft Visual Basic.

  • Integrating a Third-Party Product Catalog. Describes the various catalog integration points within Commerce Server so that third-party developers can more easily integrate a different catalog system.

  • Extending the Content Selection Framework. Describes how the Content Selection Framework can be customized to alter the algorithms used to select personalized content.

  • Creating Custom Reports. Explains how to create new analysis reports to supplement the standard reports that are available with Commerce Server.

  • Working with the Data Warehouse. Describes how to work with the Data Warehouse. This includes descriptions of its logical schema and its physical data store.

  • Integrating with Passport. Describes how to integrate Microsoft Passport into a Commerce Server Web site, including its Single Sign-In and Wallet technologies.


Integrating Custom Resources

A Microsoft Commerce Server 2000 resource is a software package that provides functionality to the applications in a Commerce Server site, and that needs to expose one or more configuration options to a system administrator. Given the latter requirement, the most obvious choice for how to expose the configuration options is through Commerce Server Manager. This section describes how to integrate a custom resource that you develop into Commerce Server Manager so that it can be administered in the same way that other Commerce Server resources are administered.

Another important aspect of the integration process is the enabling of easy deployment of the particular configuration settings using Commerce Server Site Packager. Depending on the complexity of the configuration data, and on decisions regarding where this configuration data is maintained, the deployment aspects of integration range from effortless to the implementation of a particular Component Object Model (COM) interface.

This section contains:

  • Administration Database Tables. Discusses the Administration database and a subset of its tables, in which resource configuration data is defined and stored.

  • Adding a Resource. Describes the steps required to configure the Administration database so that the configuration data associated with a custom resource can be maintained within it.

  • Levels of Integration. Describes the different levels of integration that are available to developers of custom resources.

  • Other Sources of Information About MMC. Provides information about where to learn more about the Microsoft Management Console (MMC), including more information about how to build MMC snap-in extensions.


Administration Database Tables

The configuration data for the Microsoft Commerce Server 2000 resources that are supplied with Commerce Server is stored in a Microsoft SQL Server database named "MSCS_Admin". There are seven tables in this database that are important to an understanding of how the configuration data associated with custom resources can be maintained in this database, exposed through Commerce Server Manager, and deployed with Commerce Server Site Packager. The topics in this section provide detailed information about these tables.

Table Name | Description
ExtendedProps | Stores the characteristics of resource properties (resource property schema).
PupDBScripts | Involved in configuring the use of the GenericPuP object.
ResourceProps | Stores actual resource property values, as defined in the ExtendedProps table.
Resources | Defines actual resource instances, as defined in the SystemProps table.
SiteResources | Serves as a lookup mechanism for all resources installed in a site.
Sites | The starting point for retrieving data about a site.
SystemProps | Stores the characteristics for resources (resource schema).

Retrieving the value of a resource property is a multi-step process. Start by looking up the site name in the Sites table. The Sites table leads to the SiteResources table, which leads to the Resources table, which leads to the ResourceProps table, where actual resource property values are stored.

You use the administration objects shown in the following table to access these tables, performing value retrievals, and setting new values.

Object | Description
GlobalConfig | Provides methods for management of global resources.
SiteConfig | Provides methods for management of site resources.
SiteConfigReadOnly | Provides methods for faster retrieval of global and site resource property values.


ExtendedProps Table

The ExtendedProps table stores the characteristics of resource properties. Together with the SystemProps table, this table defines the schema of the Administration database.

The columns of the ExtendedProps table are described in the following table.

ExtendedProps Columns | Description
s_ResourceType | A string used to map a single row in the SystemProps table, representing a single resource type, with the associated resource properties in this table. The corresponding column in the SystemProps table is also named s_ResourceType.
s_PropertyName | Set to an arbitrary string that serves as the internal name of the property, and used when accessing the property programmatically with the GlobalConfig, SiteConfig, and SiteConfigReadOnly objects. Typically, this name is descriptive and begins with a letter indicating the data type of the property and an underscore. For example, "i_AuctionOptions" indicates an integer data type.
f_IsConnStr | When set to "1", indicates that the property is an OLE DB connection string. If set, Commerce Server Manager uses a Universal Data Link (UDL) dialog box to set the value, and Commerce Server Site Packager will prompt for connect information for a specific database when unpacking. For additional information about this flag and its relationship to connection string configuration values, see the note in ResourceProps Table.
f_IsHidden | When set to "1", the Generic Resource dialog box will not display the property. Set this flag to "1" for properties for which there is a custom MMC snap-in.
f_IsSimpleList | When set to "1", indicates that the new property is a SimpleList object. This feature allows the storage of multi-valued properties.
s_Description | An arbitrary descriptive string that is displayed in the Generic Resource dialog box.
i_Vartype | An integer indicating the Variant type of the data being stored. For example, 8 indicates a string and 8200 indicates an array of strings. All Variant types except SafeArray, IUnknown, and IDispatch are allowed. Set to an integer value indicating the data type of the new property. The value 8200 indicates a Variant array of strings.
s_Value | The default value for this resource property, if any.
s_DisplayName | A user-friendly display name for the property that is shown in the Generic Resource dialog box.


PupDBScripts Table

The PupDBScripts table is involved in the configuration of the use of the GenericPuP object.

The columns of the PupDBScript table are described in the following table.

PupDBScripts Columns | Description
i_SiteID | An integer that identifies a particular resource as being associated with a particular site. This column corresponds to the i_SiteID columns in the SiteResources and Sites tables.
i_ResourceID | An integer that identifies the resource with which this GenericPuP object entry is associated. Values in this column correspond to the values in the i_ResourceID columns in the ResourceProps, Resources, and SiteResources tables.
u_scriptname | The name of the script with which this GenericPuP object entry is associated. This name will appear in the comma-separated list in either the s_PupParam2 column or the s_PupParam3 column in the Resources table.
txt_script | The SQL script associated with this GenericPuP object entry, if any. Use the GetSQLScript, PutSQLScript, and DeleteSQLScript methods of the SiteConfig object to manage script entries in this column. For more information, see SiteConfig Object.


ResourceProps Table

The ResourceProps table stores the actual resource property values. Together with the Resources, SiteResources, and Sites tables, this table stores the data for the Administration database.

The columns of the ResourceProps table are described in the following table.

ResourceProps Columns | Description
i_ResourceID | An integer that identifies the resource with which this property is associated. Values in this column correspond to the values in the i_ResourceID columns in the PupDBScript, Resources, and SiteResources tables.
s_PropertyName | Set to an arbitrary string that serves as the internal name of the property, and is used when accessing the property programmatically with the GlobalConfig, SiteConfig, and SiteConfigReadOnly objects. Typically, this name is descriptive and begins with a letter indicating the data type of the property and an underscore. For example, "i_AuctionOptions" indicates an integer data type.
f_IsConnStr | When set to "1", indicates that the property is an OLE DB connection string. If set, Commerce Server Manager uses a Universal Data Link (UDL) dialog box to set the value, and Commerce Server Site Packager will prompt for connect information for a specific database when unpacking. See note below for additional information about this flag and its relationship to connection string configuration values.
f_IsHidden | When set to "1", the Generic Resource dialog will not display the property. Set this flag to "1" for properties for which there is a custom MMC snap-in.
f_IsSimpleList | When set to "1", indicates that the new property is a SimpleList object. This feature allows the storage of multi-valued properties.
s_Description | This column is not used.
i_Vartype | An integer indicating the Variant type of the data being stored. For example, 8 indicates a string and 8200 indicates an array of strings. All Variant types except SafeArray, IUnknown, and IDispatch are allowed. Set to an integer value indicating the data type of the new property. The value 8200 indicates a Variant array of strings.
s_Value | The value of the property.
s_DisplayName | A user-friendly display name for the property that is shown in the Generic Resource dialog box.

Notes

  • Commerce Server Site Packager performs special processing for resource properties that have names beginning with "connstr_db". The values associated with these properties are packaged, but when they are unpacked, the packaged value is ignored and they are provided with default connection string values. If you choose to perform quick unpacking, these defaults are automatically accepted. If you choose custom unpacking, the defaults are displayed and you have the opportunity to change them. Even though they are ignored during unpacking, these connection strings are packaged in clear text, exposing them as a potential security risk.

  • The packaging of connection string values presents a potential security risk because the value, including any password, is stored as clear text in the site package. The following mechanism has been developed to avoid this security risk.

    The f_connstr attribute provides a mechanism for suppressing the packaging of connection string values (or potentially, any sensitive configuration property). When this attribute is set to one (1), the associated property value is not packaged.

  • If you want a connection string to be packaged and unpacked without any user interaction, and you are willing to assume the potential security risk, do not begin your connection string property name with "connstr_db" and do not set the associated f_connstr attribute to one (1). Alternatively, you could create a Component Object Model (COM) object that implements the IPuP interface, and let that object handle the packaging and unpacking of your connection string.


Resources Table

The Resources table defines actual instances of resources. Together with the ResourceProps, SiteResources, and Sites tables, this table stores the data for the Administration database.

Entries in the Resources table have a one-to-many relationship with entries in the ResourceProps table. For more information about one-to-many relations, see One-To-Many Relation.

The columns of the Resources table are described in the following table.

Resources Columns | Description
i_ResourceID | An integer that identifies a resource in this table. Values in this column correspond to the values in the i_ResourceID columns in the PupDBScript, ResourceProps, and SiteResources tables.
s_DisplayName | A string that stores the programmatic name for the resource, as used when accessing the resource through the Fields property of the GlobalConfig, SiteConfig, and SiteConfigReadOnly objects. For more information, see GlobalConfig.Fields, SiteConfig.Fields, and SiteConfigReadOnly.Fields, respectively.
s_Description | A string that stores the user-friendly name for the resource.
s_Type | A string that indicates the type of this resource. This column maps to the s_ResourceType columns in the SystemProps and ExtendedProps tables.
f_IsGlobal | A flag that indicates whether a resource is global (1) or site-specific (0).
f_ResourceFlags The values in this column are bit fields that store information about a number of Boolean characteristics of resources. Commerce Server Manager and Commerce Server Site Packager examine these characteristics to determine how each resource should be treated. The bits are defined as follows:
  • 0x00000001 – Set when this row is a reference to a global resource.

    Constant: IS_REFTOGROUPRES

  • 0x00000002 – Set when this resource can be displayed in MMC.

    Constant: IS_SNAPINITEM

  • 0x00000004 – Set when this resource has its own snap-in. The ProgID of the snap-in extension must be in the s_ProgIDSnapIn column when this bit is set.

    Constant: IS_SNAPINAVAILABLE

  • 0x00000008 – Set when this resource is an application in a site. Not used externally.

    Constant: IS_ADDRESS

  • 0x00000010 – Set when this resource is a physical resource. Affects delete functionality. Defaults to the first global resource like it. During custom unpacking, requires user to select existing global resource. Used in combination with IS_REFTOGROUPRES.

    Constant: IS_PHYSICAL

  • 0x00000020 – Not used.

    Constant: IS_ALWAYSPACK

  • 0x00000040 – Set for Addresses and AddressItems, which may not be related to Commerce Server.

    Constant: IS_NONCOMMERCE

  • 0x00000080 – Set for resources that use a non-standard snap-in extension (currently only used by our Data Warehouse resource). The use of this flag is not recommended because of the special programming considerations that are required.

    Constant: IS_SNAPIN_NNSE

  • 0x00000100 – Set for resources that are never to be packaged by Commerce Server Site Packager. Set this bit when you do not want to transfer resources from one machine to another.

    Constant: IS_NOTPACKED

The constants are defined in the ConfigFlags enumeration in the file cssnapin.h.
s_ProgIDSnapIn | A string that provides the ProgID of a snap-in extension for this resource. The snap-in extension must implement the IDispatch interface. The IS_SNAPINAVAILABLE bit of the f_ResourceFlags column should be set when this column has a value.
s_Computer | A string that optionally shows the name of the computer where Commerce Server is installed.
i_Status | This column is not currently used.
f_PupFlags | When set to zero (0), tells Commerce Server Site Packager that the name passed when packaging and unpacking is a file name. When set to one (1), tells Commerce Server Site Packager that the name passed when packaging and unpacking is a folder name.
s_ProgIDPUP | A string that provides the ProgID of a COM component that implements the Commerce Server Site Packager (IPuP) interface. For more information, see Site Packager Interface.
s_PupParam1 | A string that contains a comma-delimited list of names of the database tables to be packaged and unpacked for the resource.
s_PupParam2 | A string that contains a comma-delimited list of the names of the SQL schema scripts to execute when importing the resource.
s_PupParam3 | A string that contains a comma-delimited list of the names of the SQL scripts to execute when deleting the resource.


SiteResources Table

The SiteResources table serves as a lookup mechanism for all resources installed in a site. Together with the ResourceProps, Resources, and Sites tables, this table stores the data for the Administration database.

Entries in the SiteResources table have a many-to-many relationship with entries in the Resources table. For more information about many-to-many relations, see Many-To-Many Relation.

The columns of the SiteResources table are described in the following table.

SiteResources Columns | Description
i_SiteID | An integer that identifies the particular site associated with the corresponding resource. This column corresponds to the i_SiteID columns in the PupDBScripts and Sites tables.
i_ResourceID | An integer that associates the identified resource with its corresponding site. Values in this column correspond to the values in the i_ResourceID columns in the PupDBScript, ResourceProps, and Resources tables.


Sites Table

The Sites table is the starting point for retrieving data about a site. It maps the site name with a site ID. This ID is not the same as the Internet Information Services (IIS) metabase ID for the site. Together with the ResourceProps, Resources, and SiteResources tables, this table stores the data for the Administration database.

Entries in the Sites table have a one-to-many relationship with entries in the SiteResources table. For more information about one-to-many relations, see One-To-Many Relation.

The columns of the Sites table are described in the following table.

Sites Columns | Description
i_SiteID | An integer that identifies a particular site. This column corresponds to the i_SiteID columns in the PupDBScripts and SiteResources tables.
s_Name | A string containing a user-friendly name for the site.
s_Description | An optional string containing a user-friendly description for the site.
i_Status | This column is not currently used.
d_DateCreated | The date and time that this site entry was created.
d_DateModified | The date and time that this site entry was last modified.


SystemProps Table

The SystemProps table defines the characteristics of resources. Together with the ExtendedProps table, this table defines the schema of the Administration database.

The columns of the SystemProps table are described in the following table.

SystemProps Columns | Description
i_ApplicationID | This column is not currently used.
s_Name | This column is not currently used.
s_ClassName | Set to an arbitrary string. It is used as the bstrConfigSchemaClass parameter to both the GlobalConfig.CreateServiceConfig and the SiteConfig.CreateComponentConfig methods.
s_ResourceType | A string used to map a single row in this table, representing a single resource type, with the associated resource properties in the ExtendedProps table. The corresponding column in the ExtendedProps table is also named s_ResourceType.
s_Description | This column is not currently used.
f_ResourceFlags | The values in this column are bit fields that store information about a number of Boolean characteristics of resources. For more information about the meaning of the bits in this flag, see the f_ResourceFlags column of the Resources Table. The constants for the bits in this flag are defined in the ConfigFlags enumeration in the file cssnapin.h.
f_PupFlags | When set to zero (0), tells Commerce Server Site Packager that the name passed when packaging is a file name. When set to one (1), tells Commerce Server Site Packager that the name passed when packaging is a folder name.
s_RefResource | This column is not currently used.
s_MachineName | This column is not currently used.
i_Status | This column is not currently used.
s_ProgidSnapin | A string that provides the ProgID of a snap-in extension for this resource. The snap-in extension must implement the IDispatch interface.
s_ProgidPUP | A string that provides the ProgID of a COM component that implements the Commerce Server Site Packager (IPuP) interface. For more information, see Site Packager Interface.
s_PUPParam1 | This column is not currently used.
s_PUPParam2 | This column is not currently used.
s_PUPParam3 | This column is not currently used.


Adding a Resource

The process of adding a new resource, and its corresponding configuration values, to the Administration database is a two-step process. First, the schema for the new resource and its properties must be defined. Second, an instance of the new resource and its particular property values must be added.

The first step consists of adding rows to the schema tables: SystemProps and ExtendedProps. The second step consists of adding corresponding rows to the three resource instance tables: ResourceProps, Resources, and SiteResources.

This section provides details regarding how these rows should be added.

This section contains:

  • Modifying the Resource Schema Tables. Describes how the resource schema tables should be modified as the first step in adding a new resource and its properties to the Administration database.

  • Modifying the Resource Instance Tables. Describes how the resource instance tables should be modified as the second step in adding a new resource and its properties to the Administration database.


Modifying the Resource Schema Tables

When a new resource is added for management within Commerce Server Manager it is necessary to add new rows to the SystemProps and ExtendedProps tables in the Administration database (MSCS_Admin). New rows in the SystemProps table correspond to new resources. New rows in the ExtendedProps table correspond to properties associated with the new resources.

For more information about the columns of the SystemProps and ExtendedProps tables, see SystemProps Table and ExtendedProps Table, respectively.

The Site Status sample in the Commerce Server 2000 Software Development Kit (SDK) includes a pair of files that show one way to add a row representing a new resource to the SystemProps table. The file SiteStatusInit.sql includes the following SQL command, which inserts a new row and initializes the required column values (lines wrapped here for readability):

IF NOT EXISTS(SELECT s_ClassName FROM SystemProps
              WHERE s_ClassName = 'MSCS_SDKSiteStatus')
insert into SystemProps (s_Name, s_ClassName,
                         s_ResourceType, f_ResourceFlags,
                         f_PupFlags, s_ProgIDSnapin)
                  VALUES('', 'MSCS_SDKSiteStatus',
                         'SDKSiteStatus', 6,
                         0, 'CommerceSDK.SiteStatus')

The file InstallSiteStatus.vbs provides an example of one way to run the previous SQL command:

Dim WshShell
Set WshShell = Wscript.CreateObject("Wscript.Shell")
sCmdLine = "osql /S (local) /U sa /P /d MSCS_Admin /i SiteStatusInit.sql"
WshShell.Run sCmdLine, 1, True

The file SiteStatusInit.sql in the Site Status sample in the SDK also includes several SQL commands for adding property schema information to the ExtendedProps table. The following code excerpt shows one of the three properties added in this file (lines wrapped here for readability):

IF NOT EXISTS(SELECT s_PropertyName FROM ExtendedProps
              WHERE s_PropertyName = 's_AppName')
insert into ExtendedProps VALUES ('SDKSiteStatus', 's_AppName',
                                  0, 1, 0,
                                  'SDK SiteStatus Application Name',
                                  8200, '', 's_AppName')


Modifying the Resource Instance Tables

When a new resource is being added for management within Commerce Server Manager it is necessary to add new rows to the ResourceProps, Resources, and SiteResources tables in the Administration database (MSCS_Admin). Taken together, new rows in these tables define a particular instance of a new resource, allowing Commerce Server Manager to display the new resource in the correct location within the scope-pane hierarchy.

These three tables should only be modified using the administration objects GlobalConfig and SiteConfig. Do not modify them directly in SQL Server Enterprise Manager or using SQL scripts.

For more information about the columns of the ResourceProps, Resources, and SiteResources tables, see ResourceProps Table, Resources Table, and SiteResources Table, respectively.

Depending on whether the new resource is a global resource or a site resource, a different mechanism is used to migrate values already added to the SystemProps and ExtendedProps tables into these three tables.

The Site Status sample in the Commerce Server 2000 Software Development Kit (SDK) includes a file named InstallSiteStatus.vbs. This file provides an example of how the SiteConfig object is used to migrate the table values, resulting in a new resource (and corresponding snap-in extension) appearing within the Site Resources folder of the named site ("Retail" in this example). The following code, modified slightly from how it appears in the file InstallSiteStatus.vbs, shows how to use the SiteConfig object in this way:

sSiteName = "Retail"
sResourceName = "Site Open/Close Applications"

' Initialize the SiteConfig to the selected site.
Dim oSiteCfg
Set oSiteCfg = CreateObject("Commerce.SiteConfig")
oSiteCfg.Initialize sSiteName

' Add the SiteStatus resource to the resource tables.
' Note: The string "MSCS_SDKSiteStatus" must match the
'       corresponding s_ClassName value in the SystemProps table.
oSiteCfg.CreateComponentConfig sResourceName, "MSCS_SDKSiteStatus"
oSiteCfg.Fields(sResourceName).Value.Fields("s_Description") = _
                                            "SDK Site Status Resource"
oSiteCfg.SaveConfig
Set oSiteCfg = Nothing

To add a new resource to the Global Resources within Commerce Server Manager, you only need to change the example as follows (significant changes are shown in bold font):

sResourceName = "Site Open/Close Applications"

' Initialize the GlobalConfig to the selected site.
Dim oGlobalCfg
Set oGlobalCfg = CreateObject("Commerce.GlobalConfig")
oGlobalCfg.Initialize  ' no site name

' Add the SiteStatus resource to the resource tables.
' Note: The string "MSCS_SDKSiteStatus" must match the
'       corresponding s_ClassName value in the SystemProps table.
oGlobalCfg.CreateServiceConfig sResourceName, "MSCS_SDKSiteStatus"
oGlobalCfg.Fields(sResourceName).Value.Fields("s_Description") = \
                                            "SDK Site Status Resource"
oGlobalCfg.SaveConfig
Set oGlobalCfg = Nothing


Levels of Integration

There are three different levels of integration at which a new resource can engage Commerce Server Manager. These levels are distinguished by a trade-off between the development effort and the level of customization. The three levels of integration are as follows, shown in order of least development effort to greatest development effort:

  1. A generic resource, which can be implemented simply by adding appropriate rows to certain tables within the Administration database.

  2. A generic resource with a custom user interface. The user interface is implemented as a Microsoft Management Console (MMC) snap-in extension that extends Commerce Server Manager.

  3. A resource with a custom user interface, which stores its configuration values somewhere other than the Administration database.

When using the first two levels of integration, the configuration values for your resource are stored in the Administration database, and even using the third level, some of your configuration values may be stored in the Administration database. If you store the configuration values for your resource in the Administration database, and your Web pages need to access one or more of these values frequently, you should consider caching a copy of these values in memory.

The SiteConfig and GlobalConfig objects should be used to access configuration values stored in the Administration database. You cannot store these objects at the application scope because they use apartment threading. You should copy the frequently accessed values into a Dictionary object, and make the Dictionary object accessible through the IIS Application object.

This section discusses further details of these three levels of integration.

This section contains:

  • Using the Generic Properties Dialog Box. Provides additional information about the integration approach that requires the least development effort.

  • Integrating a Custom Snap-in Extension. Provides additional information about an integration approach that offers a customized user interface while preserving some of the ease-of-use advantages of generic resource integration.

  • Packaging Other Data. Provides additional information about the integration approach that allows configuration data to be stored somewhere other than the Administration database, yet still allows the resource to use Commerce Server Site Packager.


Using the Generic Properties Dialog Box

A generic resource, which can be implemented simply by adding appropriate rows to certain tables within the Administration database, has the following characteristics:

  • The configuration data for a generic resource can be changed using the Generic Resource dialog box in Commerce Server Manager. This dialog box presents a generic interface through which the configuration values of a generic resource can be changed. This eliminates the need to develop a user interface for configuring a new resource.

  • The configuration data is maintained within this database, and consequently, it is automatically packaged for deployment by Commerce Server Site Packager.

  • The configuration data can also be accessed and altered programmatically using the Commerce Server administration objects GlobalConfig, SiteConfig, and SiteConfigReadOnly.

This level of integration involves the least development effort, consisting of adding the rows to appropriate tables in the Administration database. For more information about how to add these rows, see Adding a Resource.


Integrating a Custom Snap-in Extension

A resource with a custom user interface, which requires the development of a Microsoft Management Console (MMC) snap-in extension, has the following characteristics:

  • The configuration data for this level of integration is administered using a custom MMC snap-in extension that extends the MMC node corresponding to the new resource.

  • The configuration data is still maintained in the Administration database, preserving the ease of deployment advantages that that choice offers.

  • The configuration data can also be accessed and altered programmatically using the Commerce Server administration objects: GlobalConfig, SiteConfig, and SiteConfigReadOnly. For more information about these objects, see GlobalConfig Object, SiteConfig Object, and SiteConfigReadOnly Object, respectively.

  • The MMC snap-in extension should only use the Commerce Server administration objects, GlobalConfig, SiteConfig, and SiteConfigReadOnly, to display and change the configuration data in response to user interaction.

  • The ProgID of the snap-in extension is stored in the s_ProgIDSnapIn column of the Resources table in the Administration database. If the value of this column in the row for your resource is incorrect the Generic Resource dialog box may be invoked instead of your snap-in extension.

This section provides additional details about integrating a custom MMC snap-in extension into Commerce Server Manager.

This section contains:

  • Commerce Server Manager NodeType GUIDs. Provides details regarding specific globally unique identifiers (GUID) needed to extend the Commerce Server Manager snap-in.

  • System Registry Modifications. Describes the system registry modifications required to extend the Commerce Server Manager snap-in.

  • Working with the Clipboard. Describes additional information about Commerce Server Manager snap-in data provided to the new snap-in extension using Microsoft Clipboard.


Commerce Server Manager NodeType GUIDs

The file cssnapin.h defines the NodeType globally unique identifiers (GUID) used by the Microsoft Management Console (MMC) snap-in. They are also shown in the following table with their corresponding C++ constants and their data value.

The NodeType GUIDs in the first two rows are most significant in terms integrating an MMC snap-in extension associated with a new resource. If the new resource is global, the group resources GUID is required (first row), and if the new resource is associated with a specific site, the site resources GUID is required. The other NodeType GUIDs shown in the table are not significant in this context.

NodeType GUID Constants and Values | Description
CSnapInGUID_NODETYPE_Group_Resources 1503A832-6945-11D2-AFF4-00c04F8670E4 | Microsoft Commerce Server 2000 Group Resources Extend this node to add a new global resource.
CSnapInGUID_NODETYPE_Resource 1503A834-6945-11D2-AFF4-00c04F8670E4 | Microsoft Commerce Server 2000 Resource Extend this node under the appropriate site to add a new site resource.
CSnapInGUID_NODETYPE_Root 1503A830-6945-11D2-AFF4-00C04F8670E4 | Microsoft Commerce Server 2000
CSnapInGUID_NODETYPE_Group 1503A831-6945-11D2-AFF4-00C04F8670E4 | Microsoft Commerce Server 2000 Groups
CSnapInGUID_NODETYPE_Sites 1503A833-6945-11D2-AFF4-00C04F8670E4 | Microsoft Commerce Server 2000 Sites
CSnapInGUID_NODETYPE_Site 1503A835-6945-11D2-AFF4-00C04F8670E4 | Microsoft Commerce Server 2000 Site
CSnapInGUID_NODETYPE_Site_Resources 1503A836-6945-11D2-AFF4-00C04F8670E4 | Microsoft Commerce Server 2000 Site Resources

The file cssnapin.h also defines the following NodeType GUIDs:

Constant: CSnapInGUID_NODETYPE_Addresses

GUID: 1503A837-6945-11D2-AFF4-00C04F8670E4

Constant: CSnapInGUID_NODETYPE_Address

GUID: 1503A838-6945-11D2-AFF4-00C04F8670E4

Constant: CSnapInGUID_NODETYPE_AddrItem

GUID: 1503A839-6945-11D2-AFF4-00C04F8670E4

Constant: CResourceNodeItemGUID_NODETYPE

GUID: FAEBE804-5362-4F79-8353-34E1D1DC4D11

Constant: CWebServerNodeItemGUID_NODETYPE

GUID: 2CB5E907-F79A-4b11-AD24-9E3808B7B387

Constant: CSnapInGUID_NODETYPE_Resource_NNSE

GUID: A3DF131F-2075-463E-B8DA-74B31365161E


System Registry Modifications

When adding Microsoft Management Console (MMC) extension snap-ins it is necessary to make certain system registry modifications. These include the normal Component Object Model (COM) entries in the HKEY_CLASSES_ROOT registry key, as well as the MMC-specific entries in the HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\MMC\\NodeTypes and ...\\MMC\\SnapIns registry keys.

If the new extension snap-in will have child nodes exposed in the scope pane, it is also necessary to add the GUID corresponding to the new extension snap-in to the Extension/NameSpace key of the appropriate NodeType key in the system registry.

Depending on whether the new extension snap-in corresponds to a global resource or a site resource, it will be necessary to modify either the "Microsoft Commerce Server 2000 Group Resources" or the "Microsoft Commerce Server 2000 Resource" NodeType registry entry. For more information about the corresponding NodeType GUIDs, see the first two rows in the table in Commerce Server Manager NodeType GUIDs.

The Site Status sample in the Commerce Server 2000 Software Development Kit (SDK) performs these registry modifications in the file Registry.cpp, and uses some data type information provided in the file Extend.h. The following code excerpt shows the source code that performs these modifications. The excerpt shows a pre-initialized array of EXTENDER_NODE structures, defined in the file Extend.h, and designed to perform a name space extension of the site resources, due to the GUID supplied for the guidNode structure member (unique aspect shown in bold font). To make the same system registry extension for an extension snap-in being added as a global resource, the first component of that GUID would have to be set to 0x1503a832. (The array in the following code excerpt contains one actual entry and one dummy entry, the latter of which is used for loop termination.)

// List all of the nodes that we extend.
EXTENDER_NODE _NodeExtensions[] = {
    {
        // Extension type:
        NameSpaceExtension,
        // "Microsoft Commerce Server 4.0 Site Resources" guid:
        {0x1503a834, 0x6945, 0x11d2,
            { 0xaf, 0xf4, 0x0, 0xc0, 0x4f, 0x86, 0x70, 0xe4 } },
        // CLSID_COpenCloseExtension guid:
        {0xa5ce2b5a, 0x2259, 0x485d,
            { 0x9c, 0x11, 0xa0, 0x20, 0xb7, 0xc3, 0x8e, 0x2f } },
        // Description:
        _T("Commerce 2000 Resource Extension Open/Close sample")
    },

    // Dummy entry for loop termination logic.
    {DummyExtension, NULL, NULL, NULL}
};

The following excerpt shows the for loop that processes the array shown in the previous excerpt. It adds the GUID and description stored in the guidExtension and szDescription structure members as a key/value pair in the Extensions/NameSpace key of the MMC/NodeType entry corresponding to the GUID stored in the guidNode structure member.

Note that the loop terminates when a NULL description is found, as is the case in the last element in the array.

    // register each of the node extensions
    for (pNodeExtension = &(_NodeExtensions[0]) ;
         *pNodeExtension->szDescription ;
         pNodeExtension++)
    {
        hr = StringFromCLSID(pNodeExtension->guidNode, &wszExtendCLSID);
        _tcscpy(szKeyBuf, _T("SOFTWARE\\Microsoft\\MMC\\NodeTypes\\"));
        _tcscat(szKeyBuf, wszExtendCLSID);

        switch (pNodeExtension->eType) {
        case NameSpaceExtension:
            _tcscat(szKeyBuf, _T("\\Extensions\\NameSpace"));
            break;
        default:
            break;
        }

        // Create and open key and subkey.
        long lResult = RegCreateKeyEx(HKEY_LOCAL_MACHINE ,
            szKeyBuf,
            0, NULL, REG_OPTION_NON_VOLATILE,
            KEY_ALL_ACCESS, NULL,
            &hKey, NULL) ;

        if (lResult != ERROR_SUCCESS)
        {
            return FALSE ;
        }

        hr = StringFromCLSID(pNodeExtension->guidExtension,
                             &wszNodeCLSID);
        assert(SUCCEEDED(hr));

        // Set the Value.
        if (pNodeExtension->szDescription != NULL)
        {
            RegSetValueEx(hKey, wszNodeCLSID, 0, REG_SZ,
                          (BYTE *)pNodeExtension->szDescription,
                          (_tcslen(pNodeExtension->szDescription)+1)
                                                     *sizeof(_TCHAR));
        }

        RegCloseKey(hKey) ;

        CoTaskMemFree(wszExtendCLSID);
        CoTaskMemFree(wszNodeCLSID);
    }


Working with the Clipboard

Certain Clipboard formats must be supported by Microsoft Management Console (MMC) snap-ins so that they can pass data back and forth with the MMC framework. The Site Status MMC Extension Snap-In sample in the Commerce Server 2000 Software Development Kit (SDK) illustrates the Clipboard formats that must be supported. This sample defines the required Clipboard formats within four files: compdata.h, compdata.cpp, dataobj.h, and dataobj.cpp. The header files contain the definitions of the formats, and the source files show the registration of those formats. Search these files for the string "clipboard" to find the pertinent code.

The following code excerpt shows how to retrieve the name of the site associated with the sample extension snap-in from the Clipboard and place it into the bstrSiteName variable.

    // Get the site name for this resource from
    // the clipboard "CCF_MSCSAPPNAME" in global memory
    stgmedium.hGlobal = GlobalAlloc(0, sizeof(BSTR));
    if (NULL == stgmedium.hGlobal)
        return GetLastError();
    hr = lpDataObject->GetDataHere(&formatetc, &stgmedium);
    if (!FAILED(hr))
        bstrSiteName = *((LPCOLESTR *)stgmedium.hGlobal);
    GlobalFree(stgmedium.hGlobal);


Packaging Other Data

A resource that has a custom user interface and stores its configuration data somewhere other than the Administration database has the following characteristics:

  • The configuration data is stored somewhere other than the Commerce Server Administration database, such as the system registry, an initialization (.ini) file, or perhaps in a different database.

  • In order to use Commerce Server Site Packager, new resources that are integrated at this level must include a Component Object Model (COM) object that implements the IPuP interface.

  • The configuration data must be administered using a custom Microsoft Management Console (MMC) snap-in extension. This is because the configuration data is not stored in the Administration database, so it is not possible to use the Generic Resource dialog box.

  • Because the configuration data is not stored in the Administration database, it cannot be accessed and altered programmatically using the Commerce Server administration objects GlobalConfig, SiteConfig, and SiteConfigReadOnly. For more information about these objects, see GlobalConfig Object, SiteConfig Object, and SiteConfigReadOnly Object, respectively. You must develop some other solution for programmatic access to the configuration data.

  • It is possible to provide a mixed solution, where some relatively simple configuration data is stored in the Administration database, allowing access through the Commerce Server administration objects, and where other more complex data is stored in other databases or facilities. Many of the resources included with Commerce Server work this way.

This section provides additional details about implementing the IPuP interface, allowing the resource to pack it own data for deployment.

This section contains:

  • Exporting Data to the Package. Provides additional details about the process of exporting data into a site package using Commerce Server Site Packager.

  • Importing Data from the Package. Provides additional details about the process of importing data from a site package.

  • Using the GenericPuP Object. Provides information about a general-purpose object that implements the IPuP interface, which can be used in certain circumstances.


Exporting Data to the Package

You can develop a custom resource in such a way that it can place arbitrary data, in the form of one or more files, in a site package and have those files unpacked on a different computer. In order for this arbitrary set of files to be placed in a site package, a custom resource must include a Component Object Model (COM) object that implements the Export method of the IPuP interface. Commerce Server Site Packager calls this method, providing the name of a temporary file or folder where the custom resource must place the file(s) to be packaged. Once the Export method returns, Commerce Server Site Packager will add the file (or files) to the package.

The ProgID of the object that implements the IPuP interface must be placed into the s_ProgidSnapIn column of the SystemProps table in the Administration database (the ProgID is also added to the s_ProgIDSnapIn column of the Resources table when the SiteConfig object is used to migrate configuration values). When the Commerce Server Site Packager encounters this ProgID in the course of packaging the site, it will instantiate the corresponding object and call the Export method of its IPuP interface.

For more information about the Export method, see IPuP::Export.


Importing Data from the Package

You can develop a custom resource in such a way that it can place arbitrary data, in the form of one or more files, in a site package and have those files unpacked on a different computer. In order for this arbitrary set of files to be retrieved from a site package, a custom resource must include a Component Object Model (COM) object that implements the Import method of the IPuP interface. Commerce Server Site Packager calls this method, providing the name of a temporary file or folder where the Commerce Server Site Packager has placed the file(s) to be unpacked. The Import method must do something with this file or files before returning, such as moving them to another location or moving their contents into a database. Once the Import method returns, Commerce Server Site Packager will delete the file (or files) from the temporary location.

The ProgID of the object that implements the IPuP interface must be placed into the s_ProgidSnapIn column of the SystemProps table in the Administration database (the ProgID is also added to the s_ProgIDSnapIn column of the Resources table when the SiteConfig object is used to migrate configuration values). When Commerce Server Site Packager encounters this ProgID in the course of unpacking the site, it will instantiate the corresponding object and call the Import method of its IPuP interface.

For more information about the Import method, see IPuP::Import.

If the custom resource being unpacked is a site-level reference to a global resource, the Commerce Server Site Packager will call the CreateGroupResource method of the same IPuP interface before calling the Import method. This will provide the custom resource with the opportunity to create the global resource and return its name so that the site-level reference can refer to it. For more information about the CreateGroupResource method, see IPuP::CreateGroupResource.


Using the GenericPuP Object

The GenericPuP object is one of several objects included with Commerce Server that implement the IPuP interface. These objects are used to assist in packaging the existing Commerce Server resources. Specifically, the GenericPuP object is used to package the data associated with three resources: Campaigns, Transactions, and Transaction Config.

These three resources have generic requirements in terms of how their data gets packaged, and if your custom resource has similar, generic requirements, you may be able to use the GenericPuP object instead of developing a new object that implements the IPuP interface.

Note

  • The SDK sample "PuP Resource" in the SDK\Samples\Management folder is actually a version of the GenericPuP object. You might find it useful to study the source code or to modify it for your own purposes.

The GenericPuP object is designed to be able to package and unpack tables and data in a single SQL Server database. Several parameters control the execution of the GenericPuP object, including the names of the tables to package, and the names of SQL schema scripts to be executed when unpacking or deleting the custom data. These parameters exist as database entries in the Administration database. The remainder of this topic provides details about those entries and how they can be established.

This topic contains:

  • GenericPuP Database Entries

  • Parameter Usage During Processing

  • Loading GenericPuP SQL Scripts

GenericPuP Database Entries

In order to specify the use of the GenericPuP object, you must assign its ProgID (Commerce.GenericPup) to the s_ProgIDPUP column of appropriate row in the Resources table of the Administration database. Then you must establish the remaining database entries that will control the operation of the GenericPuP object for a particular resource: the Connection String, and the GenericPuP parameters.

Connection String

When the GenericPuP object is invoked to export or import data for a custom resource, it uses the passed resource name to look for the specific connection string in the set of properties associated with that resource. This connection string uses a pre-defined naming convention so that the GenericPuP object can find the connection string amongst the other properties associated with the custom resource. The syntax for the connection string propery name is: "connstr_db_<ResourceName>" where <ResourceName> is the name of the resource for which it is being invoked. There can be only one such connection string, so the GenericPuP object can only package or unpack data from one database.

Note

  • If you look in the s_PropertyName column of the ResourceProps table in the Administration database, you will see the three connection strings connstr_db_Transactions, connstr_db_TransactionConfig, and connstr_db_Campaigns, corresponding to the three standard resources that use the GenericPuP object.

GenericPuP Parameters

After retrieving the connection string, the GenericPuP object will retrieve its parameters from the s_PupParam1, s_PupParam2, and s_PupParam3 columns of the row for the corresponding resource in the Resources table of the Administration database. These three parameters contain the following information:

s_PUPParam1

Contains a comma-delimited list of names of the tables to be packaged and unpacked for the resource.

For example, the table list for the Transactions resource is "TransDimension,TransCategory".

s_PUPParam2

Contains a comma-delimited list of the names of the SQL schema scripts to execute when importing the resource. These scripts are used to create the proper schema prior to importing the data.

For example, the schema script list for the Transaction Config resource is "AppConfig,TaxAndShipping".

s_PUPParam3

Contains a comma-delimited list of the names of the SQL scripts to execute when deleting the resource. If the Delete method implemented by the GenericPuP object is invoked, it will execute these scripts to clean up the database tables associated with the corresponding resource.

For example, the delete script list for the Campaigns resource contains the single script name: "SchemaDrop".

The scripts associated with the parameters s_PUPParam2 and s_PUPParam3 exist in the txt_script column of the pupdbscripts table in the Administration database. The u_scriptname column contains the name of the script as it appears in the list specified by this parameter, and the other two columns in that table, iSiteID and iResourceID, exist to prevent script name clashes between different resources.

The SiteConfig object implements three methods, GetSQLScript, PutSQLScript, and DeleteSQLScript, for managing the scripts stored in the pupdbscripts table. For more information about these three methods, see SiteConfig.GetSQLScript, SiteConfig.PutSQLScript, and SiteConfig.DeleteSQLScript, respectively.

For examples of how to set up your resource configuration to use the GenericPup object see the file SiteCreate.vbs in the SiteCreate folder of your Commerce Server installation directory. Follow the same steps as used by the three resources in that file that use the GenericPup object: Campaigns, Transactions, and Transaction Config.

Parameter Usage During Processing

When the Export method implemented by the GenericPuP object is invoked to package data, it performs the following steps:

  1. Packages all of the data in the tables specified in the s_PUPParam1 column.

  2. Packages all of the SQL scripts specified in s_PUPParam2 and s_PUPParam3 columns.

When the Import method implemented by the GenericPuP object is invoked to unpack data, it performs the following steps:

  1. Executes the SQL schema scripts specified in the s_PUPParam2 column.

  2. Unpacks the data in the tables specified by the s_PUPParam1 column. The scripts executed in step 1 must have already established the appropriate tables and schema.

When the Delete method or the DeleteGroupResource method implemented by the GenericPuP object is invoked to delete resource data, it performs the following steps:

  1. Executes the SQL schema scripts specified in the s_PUPParam3 column.

  2. Deletes all scripts associated with the current resource from the pupdbscripts table of the Administration database.

Loading GenericPuP SQL Scripts

The following sample code demonstrates one way to load a SQL script from a text file into the txt_script column of the pupdbscripts table of the Administration database. This sample also establishes appropriate values in the other columns. This sample uses the PutSQLScript method of the SiteConfig object to perform the actual database manipulation:

' Define a routine that takes the following four parameters:
' 1) A reference to a SiteConfig object,
' 2) The name of a resource,
' 3) The name of a text file containing the SQL script to load, and,
' 4) The name by which the script will be known in the Admin database.
Sub LoadResourceDBScript(oSiteConfig, sResource, _
                         sFilePath, sScriptName)

    ' Declare variables and constants for text file access...
    Dim oFS, oFile, sScriptContents
    Const ForReading = 1
    Const TristateUseDefault = -2

    ' Read the script from the specified text file...
    Set oFS = CreateObject("Scripting.FileSystemObject")
    Set oFile = oFS.OpenTextFile(sFilePath, ForReading, _
                                 False, TristateUseDefault)
    sScriptContents = oFile.ReadAll()
    oFile.Close
    Set oFile = Nothing

    ' Use the passed SiteConfig object to create
    ' (or overwrite) a row in the pupdbscripts table...
    oSiteConfig.PutSQLScript sResource, sScriptName, _
                             sScriptContents
End Sub

' The following code calls the routine defined previously...

' Create the SiteConfig object...
Dim oSiteConfig
Set oSiteConfig = CreateObject("Commerce.SiteConfig")

' Initialize variables for the other
' parameters to LoadResourceScript...
Dim sResource, sFilePath, sScriptName
sResource = "Transactions"
sFilePath = "C:\temp\Requisition.sql"
sScriptName = "Requisition"

' Call the routine LoadResourceScript, previously defined...
LoadResourceScript oSiteCfgAdmin, sResource, _
                   sFilePath, sScriptName


Other Sources of Information About MMC

The Microsoft Developer Network (MSDN) online Web site includes many topics that discuss various aspects of Microsoft Management Console (MMC) snap-ins and extension snap-ins.

Building your extension snap-in using the Active Template Library (ATL) can simplify and speed development because the ATL will take care of a lot of the details for you.


Building Business Desk Modules

This section describes the architecture of Commerce Server Business Desk modules and explains how to build a new Business Desk module.

This section contains:

  • Module Development Basics. Describes Business Desk in general and Business Desk modules in particular. Discusses skill set assumptions that this section makes, and the basic steps required to build a new Business Desk module. Introduces Business Desk terminology and workflow.

  • Business Desk Architecture. Describes the architecture of Business Desk in terms of its constituent parts. These include the Framework, categories, modules, actions, and tasks. Discusses Business Desk security and state management.

  • Business Desk Conventions. Describes the standards and conventions employed in the existing Business Desk modules. Some of these are completely internal, such as coding standards, and some are visible to Business Desk users, such as conventions for error and confirmation messages. The purpose of this section is to make it easier to build new Business Desk modules that conform well to the existing modules.

  • Business Desk Configuration. Describes how Business Desk configuration works in general, and in particular, the configuration information a Business Desk module must provide to execute properly within the Business Desk Framework.

  • Data Manipulation in Business Desk. Discusses the mechanisms typically employed to retrieve data from a database for display in a Business Desk module, and how data that is changed by the user is saved back to the underlying database.

  • HTML Components in Business Desk. Describes the data display and manipulation components that are used extensively in the existing Business Desk modules. One or more of these components are likely to comprise a major portion of the user interface in any new Business Desk module.

  • Business Desk Utilities. Describes the various utility functions that are part of the Business Desk Framework. These functions are employed by the existing Business Desk modules, and will be useful in writing new Business Desk modules.

  • Business Desk Source Code. Provides a roadmap to the source code for the existing Business Desk modules, all of which is included with the product. Often, the easiest way to create a new Business Desk module is to start with the source code for a similar, existing Business Desk module, and modify it as needed.

  • Automating Module Installation. Describes a Component Object Module (COM) object that helps automate the process of integrating new Business Desk modules into existing Business Desk installations. The source code for this object is provided in the Commerce Server Software Development Kit (SDK).


Module Development Basics

Commerce Server Business Desk is a user interface framework implemented primarily as Active Server Pages (ASP) containing Dynamic Hypertext Markup Language (DHTML). This framework provides a structured environment in which third party developers can easily extend the management functionality provided with Microsoft Commerce Server 2000. This environment includes structured page navigation, standard mechanisms for data manipulation, shared utility routines, and a multitude of conventions that help assure a consistent user experience.

By default, every Commerce Server Web site has a distinct instance of Business Desk associated with it. Though Business Desk shares the same set of commerce resources with the Web site, such as various databases, it exists as a separate Active Server Page (ASP) application, with a directory structure and virtual root of its own.

Particular types of management functionality are implemented within Business Desk as distinct Business Desk modules. Microsoft Commerce Server 2000 ships with a number of Business Desk modules that are designed to manage many of the different types of data used by a commercial Web site. Nevertheless, requirements for new Web site features, and their corresponding management functionality, are bound to occur. This drove the highly extensible design of Business Desk, and to the creation of this set of topics that describe how to build a new Business Desk module.

This section contains:

  • Skill Set Assumptions. Describes the assumptions made by these topics regarding the skill set of the developer intent on building a new Business Desk module. Provides some references for learning more about the required technologies.

  • Summary of Required Steps. Summarizes the steps required for building a new Business Desk module. Provides links to topics containing more detailed information required to complete those steps.

  • Business Desk Terminology. Introduces the terminology associated with the basic aspects of Business Desk.

  • Typical Module Workflow. Describes how the pages and corresponding workflow within a Business Desk module are typically arranged.


Skill Set Assumptions

As a developer of a new Commerce Server Business Desk module, you need to be sufficiently familiar with the following technologies:

  • Dynamic Hypertext Markup Language (DHTML)

  • Extensible Markup Language (XML)

  • Extensible Stylesheet Language (XSL)

  • XML Query Language (XQL)

  • Active Data Objects (ADO)

  • HTML Components (HTC), also known as DHTML Behaviors

  • Active Server Pages (ASP)

For detailed information about these technologies, see the online version of the Microsoft Developer Network at http://msdn.microsoft.com.


Summary of Required Steps

The following sequence of steps is required to build a new Commerce Server Business Desk module. (For more information about terminology that may be unfamiliar, see Business Desk Terminology.)

  1. Create a new folder under the Business Desk root folder for the site in question. Give it a unique name appropriate to the purpose of the new Business Desk module.

  2. Create a module configuration file in the Config folder within the Business Desk root folder. Give it a unique name appropriate to the purpose of the new Business Desk module. This file must express the module configuration information in a particular XML format. For more information about this XML format, see Module Configuration Files.

    Typically, the module configuration file contains an action element for each of the several action pages in the module and at least one module element. This file also describes the taskbar buttons for each action page.

  3. Add a moduleconfig element to the master configuration file that references the newly created module configuration file. Like the module configuration files, the configuration information in the master configuration file is expressed as XML. For more information about XML format of the master configuration file, see Master Configuration File.

    The moduleconfig element to be added identifies the ID of the category with which the new module is to be associated. In some cases it may be appropriate to define a new category for the new module. This is done within the master configuration file.

  4. Create the appropriate ASP pages for the new Business Desk module. Typically, there is one ASP page for each defined action element, plus any module-specific utility files included in the action pages. They should reside in the folder created in step 1.

    Each action page should include the appropriate Business Desk utilities file(s) and link to the main Business Desk style sheet (Bizdesk.css). Then they should call one of the two routines InsertTaskBar (list pages) or InsertEditTaskBar (edit pages) immediately after the opening HTML <BODY> tag.

    Although step 4 is described here as a single step, the creation and debugging of the action pages represents the vast majority of the work involved in developing a Business Desk module.

  5. Create a new HTML help file for each action page in the new module and place them in the Business Desk "docs\htm" folder. Set the helptopic attribute of each action element in the new module configuration file to refer to the appropriate new help file. For the sake of consistency, it is recommended that any new help topics be modeled on the existing help topics.

    If there is no specific help topic page for a given action page, simply leave the helptopic attribute as an empty string and clicking the help button for that page will bring up general Business Desk help.

The SDK includes three different aids to this process, as follows:

  • The folder "<install location>\SDK\Samples\Management\BizDesk" contains a VB Script file named AddModuleToConfig.vbs. This file assumes much of the burden of editing the new module configuration file and the master configuration file. The required information is passed as command line parameters to this script. Refer to the script itself for more information about these parameters.

  • The same SDK folder contains several files that are designed to make the process of creating a new Business Desk module easier. This includes the file Instructions.txt, which provides further instructions on making use of those files. The additional files include ASP pages for basic list, edit, and response pages, and a template for a file in which strings can be isolated.

  • The folder "<install location>\SDK\Samples\Management\BizDesk Module Installer" contains the files required to build the BizDeskModuleInstaller object, which can be used to help automate the process of installing a new module into an existing instance of the Business Desk. For more information about the BizDeskModuleInstaller object, see Automating Module Installation.


Business Desk Terminology

This topic defines the basic concepts associated with Commerce Server Business Desk and the terminology associated with them. The following list contains the names and descriptions of these concepts:

framework

A set of services provided for use by Business Desk modules. These services include navigation, security, and user interface controls. In addition, the framework provides a set of standardized mechanisms defining how to integrate Business Desk modules.

category

An organizational construct used within the navigation pane that allows the grouping of related Business Desk modules.

module

A set of ASP files that provide a particular type of related functionality that are organized with one or more entry points from the navigation pane.

master configuration file

The XML configuration file that defines the categories and modules available within a particular instance of Business Desk. Each module entry identifies a module configuration file that contains the configuration information for that module.

module configuration file

An XML configuration file that defines the actions, tasks, and entry points for a module (or set of modules). Module entry points identify the category with which they are associated.

HTML Components (HTCs), also known as DHTML Behaviors

A set of data display and manipulation controls that are implemented as HTML Components that are used extensively within Business Desk modules. Business Desk includes the following HTCs: DynamicTable, EditField, EditSheet, ExpressionBuilder, ListEditor, ListSheet, QueryBuilder, and TreeView. For more information about these HTCs, see HTML Components in Business Desk.

action page

A single ASP file that provides a particular aspect of the functionality associated with a module. It is typically displayed as a result of clicking a module name in the navigation pane, or as a result of clicking one of the task buttons on an action page.

list page

One of two main types of action pages, list pages provide a read-only view of some type of data, and allow that data to be filtered, sorted, selected, and acted upon. List pages typically display a ListSheet HTC. Sometimes a find pane and its associated HTCs are displayed above the ListSheet HTC. List pages share the Business Desk workspace with the navigation pane.

edit page

One of two main types of action pages, edit pages provide mechanisms for altering the data being displayed. Different edit pages employ different HTCs, depending on the nature of the data being edited. Edit pages do not share the Business Desk workspace with the navigation pane. The latter is hidden from view when edit pages are rendered, thereby preventing navigation to a different module until the edit page is dismissed and the user returns to a list page.

EditSheet group (or EditSheet section)

A section within an EditSheet HTC on an edit page that has a collapsable heading, allowing the information in that section to be displayed or hidden as preferred by the user.

task

An operation performed from an action page, often leading to the display of a different action page where the details of the task are performed. Tasks are initiated by pressing a task button. Some tasks, such as Open and Delete, are context-sensitive; they apply to whatever is selected in the current action page.

task bar

The horizontal area at the top of the content pane where the buttons corresponding to various tasks can be found. (In the user interface documentation, the taskbar is referred to as the toolbar. They are the same, and the naming difference in the User Interface (UI) is due to a desire to conform to Windows standards where end users are concerned.)

navigation pane

The window on the left side of list pages used to display the hierarchy of categories and modules.

content pane

The window on the right side of list pages, and sole window of edit pages, in which action pages are rendered.

find pane

An area in the upper portion of the module content pane in list pages in which find criteria are entered, and then used in a Find task. Most commonly, the lower portion of the module content pane consists of a ListSheet HTC in which the results of the Find task are displayed.

page title bar

The horizontal area at the top of the content pane used to display the page title.

status bar

The horizontal area at the bottom of the content pane used to display status messages.

HTML Application (HTA)

A special type of browser instance in which the normal browser user interface is not displayed. Normally, HTAs will not have the full range of menu and toolbar choices found in a generic browser instance. The Business Desk is designed to run only as an HTA.


Typical Module Workflow

This topic discusses the typical workflow found within most Commerce Server Business Desk modules. This is only a statement of typical workflow; some Business Desk modules may not conform to it. It is the responsibility of the designer of a new Business Desk module to determine the best workflow for that module. Nevertheless, the workflow discussed here has emerged as the most typical.

Using a few modules in Business Desk quickly yields the following observations about the typical workflow for Business Desk modules. The initial action page for a given module presents a mechanism for viewing a table containing a few properties (the columns) of a number of records (the rows). The control that implements this table is the ListSheet HTML Component (HTC) It can be configured in number of different ways.

Frequently, there are too many records to view at one time. Paging through different screens of records is one answer to this problem. It is also typical for there to be mechanisms for limiting the set of records displayed, such as the ability to search for and display only those records matching specified criteria. The ability to sort the records is also typical, and is accomplished in the ListSheet HTC by clicking the column heading of the property on which to sort.

The next step in the workflow involves choosing a task to perform and initiating that task by pressing a task button. Any task that involves existing data requires that the data be identified by being selected. The task buttons associated with such tasks are usually not enabled unless an appropriate selection has been made. Other tasks, such as the New task, generally do not require existing data to be selected.

In any event, the choice of a task often leads to a different action. This new action is generally an action page, known as an edit page, which allows the editing of properties associated with the new or selected record (or records). Once the editing is complete and the Save task is chosen, the user can click a Back taskbar button to display the original ListSheet HTC and continue to the next task.

Sometimes the act of choosing a task results in the display of a dialog box, rather than immediately displaying a new action. A typical example is a dialog box used to confirm a Delete task.

Other tasks might display a short menu to determine the action to be taken. For example, when the New task is clicked, a menu might be displayed to allow the user to select which of several types of objects they wish to add.

The following diagram illustrates one possible Business Desk session, outlined here using the numbered boxes near the arrows.

  • In step 1, the user chooses Module 1.

  • In steps 2 and 3, the user "drills down" two levels to examine and perhaps modify some detailed data, returning to the list page for Module 1 in steps 4 and 5.

  • The steps shown for Module 2 illustrate how a task might loop back to the same action page. An example is the Save and Create New task where the workflow is optimized for a situation in which a number of new items need to be created, one after the other.

  • The steps for Module 3 illustrate how a task might lead back to the same action page, but with a dialog box intervening. An example is the Delete task, where it is typical to present a confirmation dialog box, especially when the data is particularly important or difficult to recover.
Nested Edit
Confirmation Dialog
Edit
Edit
List
List
List
Module 3
Module 2
Module 2
Module 1
Module 1
Module 1
Welcome to Business Desk
Nav
Nav
12
11
10
9
8
7
6
5
4
3
2
?
?
?
?
?
?
1
Nav
Nav

A typical new module is likely to have a single list page that is displayed when the module is chosen in the navigation pane. The list page will probably have a small number of tasks it can perform, perhaps five or six tasks. Of these, a few might lead to different edit pages, or perhaps to the same edit page, initialized with different data (the New task versus the Edit task). Some tasks might lead directly to confirmation dialog boxes, and then back to the list page, having carried out or aborted the task.


Business Desk Architecture

This section describes the architecture of Commerce Server Business Desk. The following diagram illustrates how a set of configuration files provides two important types of information needed for the Business Desk Framework to support navigation. The first type determines the set of categorized modules that will be accessible within Business Desk. The second type is used to build and manage the taskbar, which will probably be unique to each action page.

The diagram also illustrates how modules are typically designed such that their initial action page is a list page, from which edit pages may be accessed using task buttons. It also shows the typical design in which a user must return to the initial list page in order to move to a different module.

The choice of the HTML Component (HTC) shown in the various edit pages is purely arbitrary, though a master EditSheet HTC is generally used to contain any other editing controls. The ListSheet HTC is the most common HTC on list pages, sometimes accompanied by individual HTML controls and EditField HTCs in a find pane.

The ListSheet HTC provides a few different modes in which it operates, many of which are designed to accommodate hierarchical data. This often allows the use of a single list page, as opposed to multiple layers of nested list pages on different action pages.

Individual
EditField
HTCs
ListEditor
HTC
EditSheet
HTC
Expression
Builder
HTC
Profile
Designer
HTC
DynamicTable
HTC
ListSheet
HTC
Find By
ListSheet
HTC
ListSheet
HTC
Module 3
Module 3
Edit Pages
Action Pages
List Pages
Module 3
Module 2
Module 2
Module 2
Module 1
Module 1
Module 1
Module
Configuration
File
Module
Configuration
File
Module
Configuration
File
Master
Configuration
File
Task Buttons
and Menus
?
?
?
?
?
?
?
?
?
?
Nav
Nav
Nav
Nav Pane

There are three main points to the diagram. First, the master configuration file, together with a set of module configuration files, provides the information needed by the Business Desk Framework to manage both the navigation pane and the taskbar displayed on each action page.

The second point is that action pages that display read-only lists, known as list pages, are always displayed along with the navigation pane. This means that to move to a different module, the user must do so from a list page, not an edit page. List pages are read-only (with the exception of tasks like Delete and Import), which means that users will not generally need to be presented with warnings about leaving the module without having saved changes to data.

The third point is that navigation between action pages should typically be done through the task buttons on the taskbar. This mechanism allows the Business Desk Framework to provide services that occur during transition between action pages. Direct linking of action pages to buttons within a page should be minimized.

This section contains:

  • Framework. Describes the services provided by the Business Desk Framework as well as the visual environment in which Business Desk displays the various Business Desk modules.

  • HTML Application and the Client Installer. Describes how the Business Desk is normally run within the context of an HTA, and how the files necessary for this are downloaded to the client the first time Business Desk is invoked.

  • Configuration Files. Describes how a number of files containing configuration information, specified using XML, provide the data that allows the Business Desk Framework to supply many of its services.

  • Categories. Describes the notion of categories and how they are used to organize modules within Business Desk.

  • Modules. Describes the composition of Business Desk modules, including their manifestation as ASP pages as well as how they make themselves known to the Business Desk Framework.

  • Action Pages. Describes typical contents of the ASP pages that implement Business Desk actions, including information about special elements that all such pages should include, and provides an anatomy of such pages.

  • Tasks. Describes the notion of a task within the Business Desk environment and how tasks are used as the mechanism through which Business Desk provides support for navigation within a particular module.

  • HTML Components. Describes the use of HTML Components (HTC) within Business Desk, including how they provide a standardized mechanism for viewing and altering data.

  • XMLHTTP Operations. Describes the functionality used by a list page to retrieve additional data for the ListSheet HTC without requiring the whole page to be re-rendered. This is an important enhancement that improves the performance of paging through large sets of data, or late loading of detailed data. Also describes framework routines for using XMLHTTP communication to enable saving without needing to reload the page.

  • Security. Describes how the security mechanisms within Business Desk allow for restricting particular users to subsets of the available Business Desk modules.

  • State Management. Describes the mechanisms available for preserving state on either the client or the server between the various action pages of Business Desk.

  • Error Reporting. Describes the mechanisms available for reporting client and server errors to the Business Desk user.

  • Online Help. Describes how the online Business Desk Help system is implemented and how online Help for new Business Desk modules can be integrated.


Framework

The Commerce Server Business Desk Framework provides the environment in which Business Desk modules are executed. The following list describes the various aspects of this environment:

  • The Framework provides mechanisms through which one module can discover and enumerate the other modules configured in a particular instance of Business Desk.

  • The Framework includes a set of sophisticated data manipulation controls, most of which are implemented as HTML Components (HTCs). HTCs are a form of DHTML behaviors supported in Microsoft Internet Explorer 5. These components provide consistent display, selection, and modification of data among various Business Desk modules, greatly enhancing the sense that Business Desk and its modules are operating as a single, integrated application. List management and data validation are examples of the standardized services provided by these components.

  • The Framework provides a "security" mechanism through which a particular user will not have specific modules displayed in the navigation pane, thereby restricting them from performing the functions available in those modules. More specifically, the security itself is provided by Internet Information Services (IIS) and Access Control Lists (ACLs), and the Framework displays or conceals modules based on those security settings. Whenever a 404 (file not found) or 401 (access) error occurs, a custom error page is displayed.

  • The Framework provides the visual environment in which modules are displayed. This environment includes several standard elements such as the navigation pane, the content pane, page title, taskbar, and a status bar.

  • The Framework provides standard mechanisms for navigation between modules and within a module. The navigation pane provides for navigation between different modules, allowing the user to choose a new module in which to work. The task buttons provide for navigation between the various pages comprising a given module. When a Business Desk edit page is displayed, the navigation pane is hidden, forcing the user to complete or cancel the edit action before leaving the module. Hiding the navigation pane also provides a larger area in which the edit page can be displayed.


HTML Application and the Client Installer

Normally, the Business Desk runs as an HTML Application (HTA). An HTA is a customized instance of a browser that hides some of the normal browser features (such as the toolbar and address bar) so that a more consistent and usable user interface can be provided. Business Desk is designed such that, in production, it forces itself to be run as an HTA.

You can override the behavior that forces execution only within an HTA by changing the Business Desk from production mode to development mode. Near the top of the Global.asa file for the Business Desk, you will find the following line of code:

MSCSEnv = PRODUCTION

PRODUCTION is a constant defined a few lines above, along with a sibling constant DEVELOPMENT. If you change the initialization of the MSCSEnv variable from PRODUCTION to DEVELOPMENT, a number of more debugging friendly behaviors ensue. One of these is the ability to execute Business Desk within an normal browser instance. Remember to change this line of code back to its original form before moving Business Desk, which now includes your new module, into a production environment.

Another aspect of Business Desk architecture that does not impact the development of new modules, but which is nevertheless important to understand, is that the first time Business Desk is invoked from a particular machine, it is going to launch the Client Installer. This short process will download a small number of files that must exist on the client for the Business Desk to operate as designed. As already mentioned, this does not affect the development of new modules.


Configuration Files

A set of Extensible Markup Language (XML) configuration files, the master configuration file and a number of module configuration files, are used to inform the Business Desk Framework about a number of different aspects of the modules that are included in a particular instance of Business Desk. At the highest level, each module uses this mechanism to specify information such as the category to which it belongs, the action pages it includes, and the tasks that are available on each of those action pages. At lower levels, a wide variety of additional information is specified in each of these configuration files.

For additional information about configuration of Business Desk, see Business Desk Configuration.

For detailed information about the XML structure of the master configuration file, see Master Configuration File.

For detailed information about the XML structure of the module configuration files, see Module Configuration Files.


Categories

The purpose of categories is to provide a way to organize the various modules in Commerce Server Business Desk. They provide the first level of organization in the navigation pane. The entry points to the modules serve as the second level.

Categories are implemented as entries in XML configuration files, and are displayed only in the navigation pane.

As the author of a new Business Desk module, you need to determine whether the new module belongs in one of the existing categories, or whether the functionality it provides warrants the creation of a new category. If you need to create a new category, you edit the XML contained in the master configuration file and add a new category element. The unique category ID that you devise for this category can then be referenced from the module configuration file that you create for your new Business Desk module. If you are going to add your new module to an existing category, you refer to the category ID of the existing category in your module configuration file.

A category is not displayed in the navigation pane if either of the following conditions is met:

  • No modules specify that category.

  • The current user does not have permission to access any of the module entry points within that category.


Modules

Commerce Server Business Desk modules are what provide the user interfaces that are used to accomplish actual, specific work within Business Desk. Though quite a few Business Desk modules ship with Microsoft Commerce Server 2000, undoubtedly the need for new modules will arise. How to build and integrate such new modules with the existing modules is the subject of this section.

A Business Desk module consists of the following:

  • A set of related ASP pages, including any private utility pages, that present a user interface for managing a particular type of business data. The module also includes any additional, pure-processing ASP pages that support the presented user interface. With the exception of the utility pages, typically included in pages of the other types, these pages are known as action pages.

  • Information about how and where the module should integrate into Business Desk relative to the existing categories and modules. This information is contained in the module configuration file, or potentially in more than one such file.

  • Information about how Business Desk should manage navigation between the ASP pages comprising the module, expressed in terms of tasks, and possibly including some icon files for display on task buttons specific to that module.

  • Optionally, and recommended, help files specific to action pages in the module.


Action Pages

Action pages are the Active Server Page (ASP) pages that constitute a module. Action pages can be used for pure-processing; that is, they are not responsible for the display of any user interface.

In contrast, many action pages are directly responsible for the user interface displayed in the content pane of Commerce Server Business Desk. There are two main types of action pages that are responsible for the display of the user interface: list pages and edit pages.

Any action page linked to as a module or task entry point must be registered in a module configuration file.

At a minimum, action pages responsible for the display of the content pane are comprised of the following:

  • Directives to include the appropriate Business Desk utility files. Some module-specific utility files might also be included.

  • The Business Desk customizable style sheet (CSS), which provides a consistent set of styles for a particular instance of Business Desk, as well as the styles required by the Business Desk HTML Components (HTCs).

  • A call to one of the Framework utility functions, InsertTaskBar or InsertEditTaskBar, to display the task buttons specified in the module configuration file for this action.

  • One or more HTML forms, sometimes including one or more HTCs, that specify the user interface elements associated with the action.

    Although the editing HTCs must generally be within the forms; non-editing controls (like the ListSheet HTC) need not be.

  • Optionally, the ASP code that processes the form data upon submission of the form. This code can be on the same action page, or can be on a different ASP page of either the pure-processing variety or the user interface variety, depending on how the tasks are configured. Typically, if the same page is to be displayed after some ASP code is executed, the form associated with the task will post to that same page and the ASP processing will be done at the top of the page before the content is redisplayed.

This section contains:

  • List Pages

  • Edit Pages


List Pages

List pages are one of two main types of action pages within Commerce Server Business Desk. List pages are characterized by several distinguishing features, as follows:

  • They are read-only. Data should never be modified on a list page (with the exception of search information in the find pane).

  • They appear along side the navigation pane, the latter of which allows a Business Desk user to leave the current module by selecting a different module. The list page is displayed in the right side of the Business Desk workspace.

  • Typically, list pages make use of a ListSheet HTML Component (HTC) for displaying data, using one of several distinct modes of operation offered by that HTC.

  • The list page is often divided into two distinct areas, arranging one above the other. The top area is known as the find pane, and typically contains a small number of EditField HTCs that allow the user to specify find criteria. The bottom area contains the ListSheet HTC mentioned above, and is known as the content pane. When a Find task is performed using the criteria specified in the find pane, the results are displayed in the ListSheet HTC in the content pane.

The following table describes the recommend logical structure for list pages.

Abbreviated List Page Code Description
<% InsertTaskBar %>

List Page server-side routine to insert the proper taskbar and show the navigation pane.

<DIV  id='FindByArea'>

DIV containing the whole find pane.

    <XML id='efMeta'> . . . </XML>

XML data-island containing the configuration data for the EditField HTCs.

    <XML id='efData'> . . . </XML>

XML data-island containing the actual data to be displayed in the EditField HTCs.

    <DIV id='edit1'> . . . </DIV>

DIV containing the first of several EditField HTCs used in the find pane.

    <DIV id='edit2'> . . . </DIV>

DIV containing the second of several EditField HTCs used in the find pane.

    <DIV id='edit3'> . . . </DIV>

DIV containing the third of several EditField HTCs used in the find pane.

</DIV>

End of the find pane DIV.

<DIV  id='ContentArea'

DIV containing the whole content pane.

    <XML id='lsMeta'> . . . </XML>

XML data-island containing the configuration data for the ListSheet HTC.

    <XML id='lsData'> . . . </XML>

XML data-island containing the actual data to be displayed in the ListSheet HTC.

    <DIV id='list1'> . . . </DIV>

DIV containing the ListSheet HTC used in the content pane.

</DIV>

End of the content pane DIV.


Edit Pages

Edit pages are one of two main types of action pages within Commerce Server Business Desk. Edit pages are characterized by several distinguishing features, and subject to certain conventions, as follows:

  • They are read/write. Data should only be modified on an edit page (with the exception of find pane fields on a list page).

  • They do not appear along side the navigation pane. When an edit page appears, the navigation pane is hidden and the edit page occupies the entire Business Desk workspace. This ensures that the user must save or cancel changes before moving to another module. To accomplish this behavior, edit pages must use the InsertEditTaskbar routine rather than the InsertTaskbar routine.

  • Edit pages typically make use of one or more different HTML Components (HTCs) to allow modification of data, including the DynamicTable HTC, the EditSheet HTC, the ListEditor HTC, and individual EditField HTCs. These various HTCs should be defined within a master (or outer) EditSheet HTC. This allows the event handlers to ensure proper operation of confirmation and warning dialogs associated with the Save task.

  • Edit pages with only one EditSheet group should not be expandable or collapsible, and therefore should not have a title bar.

  • When first loading, edit pages should, in general, have the first EditSheet group open and all others closed.

  • If you add an EditField HTC to an edit page you must supply your own label and required icon (if needed). For example:
    <TABLE>
<TR>
    <TD width=30><%= g_imgRequired %></TD>
    <TD CLASS='esLabelCell'>
        <LABEL FOR='password'>Password:</LABEL>
    </TD>
    <TD CLASS='esDataCell'>
        <DIV ID='password' CLASS='editField'
             MetaXML='efMeta'
             DataXML='efData'>Loading property...</DIV>
    </TD>
</TR>
</TABLE>
  • The g_imgRequired constant can be used to insert the markup for a required icon. The required icon is usually in a cell 20 pixels wide. If no required icon is needed simply replace the icon with a &nbsp; element.

  • All field labels should be nested within a LABEL element to provide for accessibility, and end with a semi-colon for consistency.

  • The esDataCell and esLabelCell values for the CLASS attribute allow the field to adopt the characteristics associated with the standard EditSheet layout.

  • If no required icon is needed simply replace the icon with a &nbsp; element

  • The following layout spacing conventions should be followed:
    • The content pane should have a 20 pixel margin on all sides.

    • Control buttons should always be left-aligned, in a single horizontal row with six pixels between buttons. The normal size of a button is 80 pixels wide and 25 pixels high. They can be made wider to accommodate longer text.

    • Paging controls should always be right-aligned.

    • Control buttons and paging controls should always be 12 pixels away from the control above them.
  • When an edit page is a module entry point (for example, tax rates page), the page must be given the following back button task so that the Back button links to the Business Desk welcome page (rather than to a list page):
    <task icon='taskback.gif' id='back'>
    <goto action='welcome.asp' />
    <name>&lt;U&gt;B&lt;/U&gt;ack</name>
    <key>b</key>
    <tooltip>Back to Main Menu</tooltip>
</task>

The following table describes the recommend logical structure for a particular, sample edit page. It demonstrates how to properly create a nested HTC structure of the following form:

    Master EditSheet
        EditSheet
        EditSheet
            EditSheet
            EditSheet
        EditSheet
            ListEditor
        EditSheet

Note that the code itself is abbreviated for clarity.

Abbreviated Edit Page Code Description
<% InsertEditTaskBar %>

Edit Page server-side routine to insert the proper taskbar and hide the navigation pane.

<XML  id='MasterMeta'>

Start of the XML data-island containing the configuration data for the outer EditSheet HTC.

    <editsheets>

Presence indicates that this EditSheet HTC contains multiple embedded EditSheet groups, listed in the order they are displayed from top to bottom.

    <editsheet> . . . </editsheet>

First nested EditSheet group. Gets its data from the containing EditSheet HTC (id='MasterData' in this example).

    <editsheet>

        <template
            register='InnerES'>
            <![CDATA[
              <DIV id=InnerES
                  class='EditSheet'
                  MetaXML='ESMeta'
                  DataXML='ESData'>
              </DIV>
            ]]>
        </template>
    </editsheet>

Second nested EditSheet group. In this example, the nested EditSheet group contains yet another EditSheet HTC (id=InnerES).

Because it uses the template mechanism, the inner EditSheet HTC must have its own MetaXML and DataXML data-islands.

The register attribute on the template tag assures the correct bubbling of events from the inner EditSheet to the master EditSheet.

    <editsheet>

        <template
            register='InnerLE'>
            <![CDATA[
              <DIV id=InnerLE
                  class='ListEditor'
                  MetaXML='LEMeta'
                  DataXML='LEData'>
              </DIV>
            ]]>
        </template>
    </editsheet>

Third nested EditSheet group. In this example, the nested EditSheet group contains a ListEditor HTC (id=InnerLE).

Because it uses the template mechanism, the inner ListEditor HTC must have its own MetaXML and DataXML data-islands.

The register attribute on the template tag assures the correct bubbling of events from the ListEditor to the master EditSheet.

    <editsheet> . . . </editsheet>

Fourth nested EditSheet HTC. Gets its data from the containing EditSheet HTC (id='MasterData' in this example).

    </editsheets>

End of container for multiple EditSheet HTCs.

</XML>

End of master EditSheet HTC configuration data-island.

<XML  id='MasterData'> . . . </XML>

XML data-island containing the actual data for the master EditSheet HTC. Data actually displayed in nested, non-template EditSheet HTCs.

<XML  id='ESMeta'>

Start of the XML data-island containing the configuration data for the inner EditSheet HTC.

    <editsheets>

Presence indicates that this EditSheet HTC contains multiple embedded EditSheet HTCs, listed in the order they are displayed from top to bottom.

    <editsheet> . . . </editsheet>

First nested EditSheet group. Gets its data from the containing EditSheet HTC (id='ESData' in this example).

    <editsheet> . . . </editsheet>

Second nested EditSheet group. Gets its data from the containing EditSheet HTC (id='ESData' in this example).

    </editsheets>

End of container for multiple EditSheet HTCs.

</XML>

End of nested EditSheet HTC configuration data-island.

<XML  id='ESData'> . . . </XML>

XML data-island containing the actual data for the nested EditSheet HTC.

<XML  id='LEMeta'>

    <listeditor> . . . </listeditor>
</XML>

XML data-island containing the configuration data for the nested ListEditor HTC.

<XML  id='LEData'> . . . </XML>

XML data-island containing the actual data for the inner ListEditor HTC.

<DIV  id='MasterEditSheet'

      class='EditSheet'
      MetaXML='MasterMeta'
      DataXML='MasterData'>
      Loading. Please wait...
</DIV>

DIV that defines the content of entire content pane.


Tasks

A Commerce Server Business Desk task is what ties one action page to another action page, sometimes performing some work during the page transition. In some circumstances the resultant action page can be the same as the originating action page. For example, the Delete task is likely to present a confirmation dialog box, delete the selected record(s) if confirmed, and then return the user to the originating page.

Another way to think about tasks is that they are the mechanism through which Business Desk users initiate high-level actions within the Business Desk. Examples of high-level actions include opening an edit page for a particular selected item, deleting a selected item, and creating a new item. High-level actions can be contrasted to low-level actions that take place within a single page. Examples of low-level actions include scrolling, paging, and changing the value of a displayed field.

Frequently, a task provides a mechanism for performing some more detailed manipulation of data that has been selected on the originating page. For example, suppose a user selects a row that corresponds to a particular record on one action page. By clicking the button for the Open task, the user is presented with a new action page that displays that record in more detail, showing additional fields that were not visible on the originating action page. The new page is likely to allow editing of at least some of the fields being displayed, allowing those fields of the record to be changed by the user.

Tasks are presented in Business Desk user interface as a horizontal row of buttons, known as the taskbar, located at the top of the content pane. There are two types of task buttons: standard task buttons and task menu buttons. Task menu buttons are one of several ways for handling what is known as task branching. The aspects of Business Desk tasks are discussed in more detail in the following topics.

This section contains:

  • Task Buttons and Menus

  • Task Branching

  • The Task Bar


Task Buttons and Menus

Tasks are presented in the Commerce Server Business Desk user interface as buttons. Typically, a task button displays an icon, retrieved from the image file specified as the value of the icon attribute of the task element. If the icon attribute is missing, the data value associated with the name element (child of task element) is used to label the button. The data value associated with the tooltip element (child of the task element) is used as mouse-over text.

For more information about the attributes and sub-elements of the task element, see the task element topic in the "Business Desk XML Structures" reference.

There are two types of task buttons used within Business Desk: standard task buttons and task menu buttons. Standard task buttons are buttons that perform some action when clicked. The action might be, for example, to go to a new action page, to display a deletion confirmation dialog box, or to save modified data.

In contrast, task menu buttons display a drop-down menu when clicked, presenting a number of distinct sub-tasks as possible choices. The user must click one of those choices before any action is taken.

A large number of icons have been pre-defined for a variety of generalized tasks, including some task menu icons. Wherever possible, developers of new Business Desk modules are encouraged to make use of these existing icons. For more information about icons, see Icons.


Task Branching

There are times when a particular task actually represents a number of distinct sub-tasks. For example, when adding a new item of some type, you add a new item with all blank fields, or a new item with field values inherited from a selected item of the same type.

This task branching can be handled in different ways. Sometimes the sub-task is obvious from the item selected, and no user input is required. The code can make the correct sub-task choice on behalf of the user.

If the user must explicitly make the sub-task choice, the preferred method is to define the task as a menu. Using this method, when the user clicks the task button a menu drops down, presenting them with the sub-task choices. This type of mechanism is easily configured within the corresponding task element in the module configuration file.

Another method of accomplishing sub-task branching when the user must make the choice is to use an intermediate dialog box. This can be done by adding an ONTASK attribute to the form associated with a task ("postto" type tasks only). The ONTASK attribute names a function to be executed after the user clicks the task button. This function could display the dialog window and then submit the form unless the user cancels the task.


The Task Bar

Every action page that presents a user interface in the content pane needs to define a set of tasks that are available from that page. These tasks are defined in the module configuration file, using the tasks element contained in each action element. For more information about the details of task definition for each action page, see the tasks element topic in the "Business Desk XML Structures" reference.

The tasks defined for an action page are displayed as a series of task buttons, starting at the top left corner of the content pane and continuing to the right. This series of buttons is known as the taskbar. Task buttons appear in the taskbar in the same order that the corresponding task elements appear within the tasks element in the module configuration file.

There are some conventions about the order in which tasks should be defined, and thus the order in which their associated task buttons will appear in the taskbar. For more information about task bar conventions, see Task Bar.

In addition to the tasks defined by each module, as represented by a left-justified set of task buttons, there is a single global task. This task is the Help task, which has a standard, right-justified button. The Help button displays with a question mark icon, and has the mouse-over text "View help for this page." The Help task is the only global task that is automatically included on every action page. Pages that do not specify a help topic using the helptopic attribute of the action element will display the general Business Desk help when clicked. There is no supported mechanism for adding new global tasks.


HTML Components

One of the important services provided by the Commerce Server Business Desk Framework is a set of HTML Components (HTCs) that provide a standardized manner in which data can be displayed and manipulated. These HTCs are used extensively in Business Desk modules that ship with Commerce Server 2000, and it is expected that they will also be used extensively in new Business Desk modules developed by third parties.

For more information about the HTCs provided by the Business Desk Framework, see HTML Components in Business Desk.

For detailed reference information about the properties, methods, and events supported by each HTC, and for information about the XML structures upon which these HTCs rely, see HTML Components and Business Desk XML Structures, respectively.


XMLHTTP Operations

Two of the HTML Components (HTCs) provided by the Commerce Server Business Desk Framework provide a special feature known as XMLHTTP operations. These HTCs are the ListSheet HTC and the TreeView HTC. The purpose of this feature is to enhance the performance of these HTCs by providing a structured mechanism in which the HTC can request additional XML data from the server in such a way that the page will not need to be reloaded.

In addition, there are a number of routines in the framework for doing XMLHTTP operations on a page outside the context of the ListSheet and TreeView HTCs. These routines can be used to implement pages that save information to the server without having to reload the entire page. Examples include many of the edit pages in the Campaign Manager module.

For more information about XMLHTTP operations and the fetch pages upon which they rely, see XMLHTTP Operations and Fetch Pages.

For more information about the configuration of XMLHTTP operations within the XML meta-data data-islands for the ListSheet HTC and the TreeView HTC, see ListSheet Configuration and TreeView Configuration, respectively.


Security

The Commerce Server Business Desk Framework supports hiding particular modules in the navigation pane to which a particular user should not have access. This is accomplished using NT file system (NTFS) Access Control Lists (ACLs) on the files that serve as the entry point for each module. For example, if a particular user does not have read permission on the entry point file associated with a particular module, that module will not appear in the navigation pane, and the user will not be able to access it. The user may not even know that such a module exists.

It is important to consider applying the appropriate access control to more files than just the entry point files. A better strategy is to establish the appropriate ACLs at the (Business Desk module) folder level so that all the contained files are similarly protected. This helps prevent users from circumventing Business Desk security mechanisms by trying to directly access module pages other than through the entry point page.

If users try to display a page to which they do not have access rights, a custom Business Desk error page is displayed.

Note

  • Business Desk Framework does not implement any security mechanisms. Rather, it provides a mechanism for preventing individuals from seeing Business Desk modules that are outside their areas of responsibility. Microsoft Internet Information Services (IIS), Microsoft Windows 2000 (for example, using ACLs and authentication), and Microsoft SQL Server should be used to provide security.

Consider the following additional points when determining security requirements for a particular instance of Business Desk:

  • Most databases allow some type of security to be implemented at the level of the data fields. A new Business Desk module could be written such that it handled data protection at this level; however, the modules that ship with Microsoft Commerce Server 2000 do not implement this level of security, and would need to be modified to do so.

  • Care should be taken to supply the correct ACLs for all relevant Business Desk folders, regardless of whether any module entry point files exist in those folders.

  • If the user connects to Business Desk from the Internet via an unauthenticated session, Internet Explorer prompts for the user name, password, and domain name in order to authenticate the user for the Business Desk application.

  • When the user is already logged onto the local network, an account context is implicit and that context is used for transparent validation of the authenticity of the user.


State Management

The Commerce Server Business Desk Framework maintains a client state dictionary that is used by modules to pass data between pages. Three client-side routines are provided for interacting with this dictionary. Use SetTemp (client-side) to store data, GetTemp (client-side) to retrieve data, and ClearTemp (client-side) to remove previously stored data. The data to be stored can be any variant type, including objects.

To keep this dictionary operating efficiently, care should be taken to clear values that no longer need to be stored in this dictionary.

All pages displayed within a particular instance of Business Desk share this dictionary, and there are no mechanisms to prevent one page from overwriting a value stored by another page. For this reason, you need to ensure that the dictionary key names that you use are unique and not used by another module. One common practice is to prefix all key names with the module name or some variation thereof.

One important use of the client state dictionary is when nested edit pages are being used. Often, the nested edit page needs to pass information back to the calling edit page. For example, this information might concern newly created objects or renamed objects. The nested edit page stores the relevant information in the client state dictionary, usually in the ONTASK routine associated with the Save task. The information can then be retrieved from the client state dictionary in the callback routine in the calling edit page.

Similarly, Business Desk also provides routines for storing state information on the server that can be accessed from client-side script. These routines convert a client-side Dictionary object into XML, use XMLHTTP to transfer it to the server, convert the XML back to a Dictionary object on the server, and then save it in the Session object. The reverse operation retrieves the saved state from client-side script. For more information about saving state on the server, see dSetServerState (client-side), dGetServerState (client-side), and dClearServerState (client-side).

Modules can use cookies to save small amounts of state across calls to different pages. Use this state management method only when storing less than 100 bytes of data per action page.


Error Reporting

The Commerce Server Business Desk Framework provides error reporting routines for both client-side and server-side script. These routines fall into the following categories:

  • Formatting routines that are used to construct an HTML table that shows the details of one of several categories of errors.

  • A routine used to set error information in server code that will be displayed on the client when the task bar is inserted in the page.

  • Display routines that result in an error dialog box to be displayed to the Business Desk user.

  • A routine that is used to fetch friendly error strings based on a more terse error string ID.

This topic contains:

  • Server-Side Error Routines. Describes the routines supplied by the Framework for formatting and displaying errors within server-side script.

  • Client-Side Error Routines. Describes the routines supplied by the Framework for formatting and displaying errors within client-side script.

  • Error Routine Examples. Provides a number of examples, showing how the error reporting routines can be combined to report different types of errors.

Server-Side Error Routines

There are four server-side routines for formatting error details, one each for formatting the following types of errors: ADO errors, ASP errors, XML parsing errors, and VBScript errors. For more information about server-side error routines, see:

sGetADOError (server-side) | sGetScriptError (server-side)
sGetASPError (server-side) | sGetXMLError (server-side)

The routine SetError is provided for logging an error in server-side script for eventual display to the Business Desk user. The error information is stored in the ASP Session object and is automatically retrieved and displayed to the user the next time one of the taskbar routines (InsertTaskBar or InsertEditTaskBar) is invoked. For more information about the SetError routine, see SetError (server-side).

Server-side errors are also logged to the Windows NT Application Event Log under the Commerce Server 2000 source.

The routine sGetErrorById is provided to allow the error summary strings stored in the global MessageManager object to be retrieved based on more cryptic, non-localized identifier strings. For more information about the sGetErrorById routine, see sGetErrorById (server-side).

Client-Side Error Routines

There are two client-side routines for formatting error details, one for formatting the details of XML parsing errors, and one for formatting the details of VBScript errors. For more information about client-side error routines, see:

sGetScriptError (client-side) sGetXMLError (client-side)

The routine ShowErrorDialog is provided for displaying an error dialog box to the Business Desk user from client-side script. For more information about the ShowErrorDialog routine, see ShowErrorDlg (client-side).

The error dialog is displayed immediately, and is modal. The detail formatting routines are called within the parameter list of ShowErrorDialog, providing the detail string via their return value.

Error Routine Examples

The following examples show various ways in which the formatting and display routines can be combined to report different types of errors.

The following server-side example shows a call to SetError where the dialog box title is referenced through a localizable string constant, the summary string is looked up using sGetErrorById, and the error details are retrieved using the ASP getLastError method. This example displays an error dialog box with the critical icon.

The call to InsertTaskBar following the call to SetError results in a call to the client-side routine ShowErrorDialog, passing the SetError parameters that were temporarily stored in the Session object.

<%
Call SetError(L_ASP_ERROR_TITLE, _
              SGetErrorById("CS4ERR_ASP_ERROR"), _
              sGetASPError(Server.getLastError), _
              ERROR_ICON_CRITICAL)

Call InsertTaskBar(L_PAGETITLE_TEXT, L_STATUS_TEXT)
%>

The following client-side example shows a call to ShowErrorDialog where the dialog box title and summary strings are referenced through localizable string constants and the error details are contained in the Visual Basic global Err object. This example displays an error dialog box with the question icon.

<SCRIPT LANGUAGE='VBScript'>
Call ShowErrorDialog(L_VB_SCRIPT_ERROR_TITLE, _
                     L_VB_SCRIPT_ERROR_MESSAGE, _
                     sGetScriptError(Err), _
                     ERROR_ICON_QUESTION)
</SCRIPT>

The following client-side example shows a call to ShowErrorDialog where the dialog box title and summary strings are referenced through localizable string constants and the error details are retrieved using the XML Document Object Model (DOM) parseError method (assumes a reference to an XML document is contained in the variable xmlDoc). This example displays an error dialog box with the critical icon.

<SCRIPT LANGUAGE='VBScript'>
Call ShowErrorDialog(L_XML_PARSE_ERROR_TITLE, _
                     L_XML_PARSE_ERROR_MESSAGE, _
                     sGetXMLError(xmlDoc.parseError), _
                     ERROR_ICON_CRITICAL)
</SCRIPT>

The following client-side example shows a call to ShowErrorDialog where the dialog box title is referenced through a localizable string constant, the summary string is looked up in server-side script, and the error details are retrieved in server-side script using the ASP getLastError method. This example displays an error dialog box with the alert icon.

<SCRIPT LANGUAGE='VBScript'>
Call ShowErrorDialog(L_ASP_ERROR_TITLE, _
                     "<%= sGetErrorById("CS4ERR_ASP_ERROR") %>", _
                     "<%= sGetASPError(Server.getLastError()) %>", _
                     ERROR_ICON_ALERT)
</SCRIPT>

The following client-side example shows a call to ShowErrorDialog where the dialog box title and summary strings are referenced through localizable string constants and the error details are retrieved in server-side script using the first error object in the errors collection of an Active Data Objects (ADO) Connection object (assumes a reference to an ADO Connection object is contained in the variable oConn, and that that object contains at least one valid error object). This example displays an error dialog box with the information icon.

<SCRIPT LANGUAGE='VBScript'>
Call ShowErrorDialog(L_ADO_ERROR_TITLE, _
                     L_ADO_ERROR_MESSAGE, _
                     "<%= sGetADOError(oConn.errors.error(0)) %>", _
                     ERROR_ICON_INFORMATION)
</SCRIPT>

The following client-side example shows a call to ShowErrorDialog that displays a dialog box with the default title, summary string, and icon. No details button appears in the dialog box.

<SCRIPT LANGUAGE='VBScript'>
Call ShowErrorDialog("", "", "", "")
</SCRIPT>


Online Help

Every action page specified in a module configuration file must specify an associated help file. Specifically, the action element is required to include the helptopic attribute, the value of which specifies the pathless name of an HTML file that is meant to contain help for that action. Such help files must be placed in the Help folder within the root folder of Commerce Server Business Desk.

When a Business Desk user clicks the Help task, the Business Desk Framework looks up the help file associated with the current task and displays it in a separate help window. If the helptopic attribute contains an empty string then the general Business Desk help page is displayed.


Business Desk Conventions

The Commerce Server Business Desk modules that ship with Microsoft Commerce Server 2000 were developed taking into account established standards for Microsoft Windows applications and defacto standards for Web applications. The goal was to improve both the usability of the Business Desk application and the maintainability of the Business Desk code base. Usability is improved because adherence to the standards tends to increase the consistency between modules developed by different individuals or organizations. Maintainability is improved because the code base is more consistent, allowing new developers to more quickly understand and more successfully modify the code that implements Business Desk.

The topics in this section serve two purposes. First, once developers of new Business Desk modules have learned the standards used, the more easily they will be able to comprehend the Business Desk source code and use it in their new modules, both in terms of invoking Framework functions and in terms of re-using sections of existing code.

Second, to the degree that developers adopt and apply these standards in their own modules, Business Desk usability and maintainability is preserved, benefiting the business managers using it to maintain their Web sites, and any new developers that must learn the now-extended code base to perform future maintenance.

This section contains:

  • Coding Practices. Describes the coding practices used in the Business Desk Framework and module code.

  • Fonts and Color Scheme. Describes the default Business Desk color scheme and the justification behind it. Includes information on how to modify the color scheme.

  • Icons. Describes the icon scheme used in Business Desk. Also provides information about when and how to use various icons.

  • Accessibility. Describes accessibility practices employed in Business Desk. Provides an accessibility checklist for use in module development.

  • Localization. Describes how to make the process of localizing a Business Desk module as easy as possible.

  • Title Bar. Describes the conventions adopted for the text shown in the title bar.

  • Task Bar. Describes the conventions adopted by existing Business Desk modules with respect to the taskbar.

  • ListSheets. Describes standards established for ListSheet HTCs.

  • EditFields. Describes standards established for EditField HTCs.

  • Find Pane. Describes standards established for the find pane.

  • Modal Dialog Boxes. Describes standards established for modal dialog boxes employed by both Business Desk modules and the Framework itself.

  • Confirmation, Warning, and Error Dialogs. Describes the standards adopted with regard to confirmation messages.

  • Asynchronous Behavior. Describes various aspects of how asynchronous behavior is implemented within Business Desk, allowing new modules to successfully integrate with those mechanisms.

  • Error Messages. Describes the standards adopted with regard to error messages.

  • Status Messages. Describes the standards adopted with regard to status messages.

  • Links Between Modules. Describes the conventions adopted with regard to direct linking between actions that belong to different modules.

  • Help Topics. Describes the behavior of the online Help system built into Business Desk. Information about how to develop Help topics for new modules as well as information about how such help can be integrated into the existing system is provided.


Coding Practices

The following list summaries the coding standards observed during the development of Commerce Server Business Desk.

  • Follow Hungarian naming conventions for variables.

  • Follow file naming conventions.

  • Provide clear and complete comments in the code.

  • Keep use of included files to a minimum.

  • Validate all HTML using an HTML validation tool.

  • Make sure all HTML element IDs are unique and are all in lowercase.

  • Establish some common page characteristics by including the file BDHeader.asp.

  • Specify "Option explicit" at the beginning of each client script block.

  • Use "Request.Querystring" and "Request.Form", as appropriate.

  • Specify ByRef and ByVal explicitly in VBScript function definitions.

  • Keep the number of queries per page to a minimum.

  • Use symbolic constants for clarity.

  • Specify the scripting language per page (ASP) and per element (DHTML).

  • Capitalize all HTML element names and attributes, and all constant names.

  • Use lowercase or mixed case for scripting code.

  • Use a main function for each page to keep use of page globals and script executed inline to a minimum.


Fonts and Color Scheme

The fonts and color scheme used by Commerce Server Business Desk are defined within a customizable style sheet (CSS), allowing centralized modification of these aspects of the Business Desk look and feel. The name of the main CSS file is Bizdesk.css and it is located in the Include folder within the root folder of Business Desk.

There is a separate CSS file for the navigation pane, named Navtree.css.

For the sake of consistency, new modules should adopt the fonts and color scheme defined in the file Bizdesk.css so that any subsequent changes are applied consistently throughout Business Desk.

For detailed information about the CSS file used by Business Desk, see Style Sheet Reference.


Icons

Every action page specified in a module configuration file has a number of tasks associated with it. Given this specification the Commerce Server Business Desk Framework can assemble and display the appropriate taskbar (also known as a toolbar in the Business Desk help). The most prominent visual aspects of the taskbar are the icons that represent the different possible tasks. These icons are specified in the module configuration files as the value of the icon attribute of the task element. The value to be specified is the pathless name of a file, typically a GIF file, located in the Assets folder under the Business Desk root folder.

The Assets folder contains a fairly large set of pre-defined icon files used by existing modules and available for use in new modules. Most of these files are intended for representing tasks that lead to a single subsequent page. The names of the icon files associated with tasks have the form taskTYPE.gif, where TYPE is a short string that describes the associated task. For example, the icon file associated with the export task is named taskExport.gif.

In addition, there are a few icons intended for use in tasks for which multiple choices are offered. These choices are offered in the form of a menu that drops down from the task button when it is clicked. These icons all include a small down-arrow to inform the user that a menu offers further choices. The names of this type of icon file has the form taskTYPEMenu.gif, where TYPE describes the associated task. For example, the icon file associated with the new menu (task) is named taskNewMenu.gif.

Note

  • There is only one icon file per task, and the look of the different button states (enabled versus disabled versus clicked) is controlled by the Framework and the customizable style sheet (CSS).

In addition to the pre-defined icon files, you can place new icon files in the Assets folder and then refer to them in new module configuration files. However, for the sake of consistency, you should use one of the pre-defined icons wherever applicable.

If you need to create new icons, the size of task icons is 22 pixels tall by 23 pixels wide. The size of task menu icons is 22 pixels tall by 33 pixels wide.

There are other icons in the Assets folder that are not used directly by module developers. These include the icons used in error dialog boxes, which correspond to errors of different levels of severity, the icons used to indicate invalid and required input, and the animation icon displayed while a page is loading.


Accessibility

Commerce Server Business Desk Framework and modules have followed certain guidelines to help assure that Business Desk will be accessible to users with disabilities. To maintain consistency with the Framework and existing modules, new modules must follow the accessibility guidelines for Web applications. For more information about accessibility guidelines, see http://msdn.microsoft.com.

Some examples of these guidelines are:

  • The Business Desk must function properly with graphics turned off in the browser.

  • The Business Desk must continue to function properly when custom fonts and font sizes are configured in Internet Explorer.

The following additional design considerations should also be observed:

  • Color should never be the only visual clue.

  • Subtle use of color should be avoided. High contrast is more accessible.

  • Provide keyboard options, including those such as the tab key for navigating to different fields on a page. All visual elements on the page should be included in the tab order.

  • Avoid horizontal scrolling wherever possible.

  • Accommodate screen readers wherever possible. This means that tables and graphics should have associated text that explains their purpose and provides some level of detail about their contents.


Localization

The Commerce Server Business Desk Framework and the Business Desk modules that are delivered with Commerce Server 2000 have been developed in a way that helps to minimize the cost of translating Business Desk into foreign languages. Depending on the circumstances in which a new Business Desk module is being developed, it might be wise for you to adopt the same general guidelines followed by Microsoft developers.

The following list enumerates these guidelines:

  • Navigation should tend to be located at the left and top of the page.

  • Horizontal groupings of controls (other than task buttons) should be avoided so that the typical expansion associated with localization does not disrupt the display.

  • The proper codepage and response charset should be specified in two specific Business Desk include files that are included by all pages. Normal module pages that display HTML in the content pane should be modified to use the proper codepage in the include file BDHeader.asp. Module fetch pages, which are designed to return nothing except XML, should be modified to use the proper codepage in the include file BDXMLHeader.asp.

  • Each module should have a file called "<ModuleName>Strings.asp" in which localizable strings are defined as VB Script constants. Any action page that needs to display one of these strings should include the file and reference the string using its constant name. Hard coded strings should be avoided.

  • Building strings from sub-strings should be avoided because the subject/verb/object order can vary from language to language. Where appropriate, the framework routine sFormatString should be used to ease localization efforts.

  • Allow extra space in forms for the string expansion that typically occurs during localization.

  • Do not use images with text in them.

  • Do not display SQL column names, which will not be localized, on an action page. Other mechanisms exist for supplying display names.

  • Do not display partial file names as part of other messages.


Title Bar

The title bar is used to display information about the current module and action page. Title bar text should use the following format:

Module Title - [action] [option]


Task Bar

Task bar conventions fall into two categories:

  1. Conventions for the left-to-right ordering of the task buttons.

  2. Conventions and mechanisms for handling the enabled/disabled state of the different types of tasks.

Task Button Order

On List Pages, tasks should be ordered in the taskbar in the following order, starting from the left:

  1. Individual item tasks that do not require selection. For example, View, New, and Compose.

  2. Individual item tasks that do require selection. For example, "Open", "Run", "Preview", and "ViewDetails". Paired tasks also belong in this category. For example, "Delete/Restore" and "Archive/Unarchive".

  3. Tasks that operate on the entire list. For example, "Publish", "Refresh", and "Find".

  4. When in doubt, use the modules delivered with Commerce Server as examples.

On Edit Pages, order tasks as follows:

[Back] [SaveBack] [Save] [SaveNew]

Enabling and Disabling Tasks

The New and Find tasks are automatically enabled by the Framework routine OnLoad. When a New task menu is used, the individual menu items must be enabled and disabled by the module page.

The Save and SaveNew tasks are automatically managed by the Framework so long as there is one top level (master) EditSheet HTC that has the OnChange, OnRequire, and OnValid events handled by the SetDirty, SetRequire, and SetValid methods, respectively. In general, the Save and SaveNew tasks should only be enabled when something has been changed and there is no missing required data and no invalid data.

Tasks must be re-enabled after an OnTask routine has been cancelled and the form is not submitted.

The Open, Copy, and Delete tasks should only be enabled when item(s) that support the respective operation are selected. Other tasks that depend on an item being selected should behave in the same way.

The Back task on Edit Pages is always enabled by the Framework.

Tasks that are always available should be enabled in the OnLoad routine and whenever an OnTask routine does not submit the form.


ListSheets

New modules that use ListSheet HTCs in their list pages should conform to the following guidelines:

  • ListSheets containing only one column should not allow sorting (sort='no') since the order would not change.

  • ListSheets that are showing a filtered view of the list based on criteria provided in the find pane should have the following label (placed above the ListSheet in question) to remind the user that they are viewing a filtered list:

    Filtered View (use the Find command to modify the filter criteria)

    A tooltip should be provided for this label. The tooltip should show the criteria upon which the filtered list is based.


EditFields

New modules that use EditField HTCs panes in their list pages should conform to the following guidelines:

  • Editfield input prompts should use the defaults for the field type unless the default prompt is ambiguous or does not convey enough information. For example, a name field with the default "enter text" prompt may be fine, but a password field or a field meant to contain an email address should probably be more specific.

  • Required fields will be indicated with a small red diamond to their left. This is the primary method available for teaching users about which fields are required and which are not.


Find Pane

New modules that use find panes in their list pages should conform to the following guidelines:

  • If a list page starts out with an empty list, the find pane should be initially showing. This most often occurs when showing the entire list by default is not practical due to its size. For more information about showing the find pane, see ShowFindBy (client-side).

  • If a list pages starts out with data displayed in its list, the find pane should be initially hidden. For more information about hiding the find pane, see HideFindBy (client-side).

  • Find pane field prompts should use the defaults for the field type unless the default prompt is ambiguous or does not convey enough information. For example, a name field with the default "enter text" prompt may be fine, but a password field or a field meant to contain an email address should probably be more specific.

    In the case of a drop down list, use the default prompt, or provide a default selection to avoid showing a prompt at all.

  • In find pane fields that support the use of wildcard characters, include a line at the bottom to indicate this fact, phrased as follows:

    Wildcard characters (*) can be used in the <field name> field

  • If a find pane has multiple groups of find fields, each displayed or hidden based on some selection control, it should usually have a Find All button for easy access to the data. The Find All should be the default, until changed by the user. Note that sometimes the sheer size of the list prevents the Find All button from being feasible.

  • If a find pane has just one group of find fields, such that any of the properties may be changed but none of them are ever hidden, the default values in those fields should be the most common ones, yielding the result most likely to be useful to the user.

  • In situations where the find pane presents a large number of options, a Reset button should be included, so that the find criteria can easily be restored to its original state.


Modal Dialog Boxes

In Commerce Server Business Desk, modal dialog boxes are used to offer one or more choices to the user. One use of modal dialog boxes is when transitioning from one page to another, or between different tasks on the same page. Depending on the choice(s) made, the user may be shown different subsequent pages, or default values may be provided in a different way.

If a simple choice needs to be made when clicking on a task button, it is preferable to use task menus rather than displaying a modal dialog box. For more information about task menus, see Task Buttons and Menus.

It is not possible to anticipate all situations in which a Business Desk module might appropriately use a modal dialog box. An alternative is to familiarize yourself with the use of modal dialog boxes in the modules that ship with Commerce Server 2000 and follow their lead.

To promote consistency, modal dialog boxes created for new modules should follow the same conventions used by the modal dialog boxes in existing modules, as follows:

  • The background color for all modal dialog boxes should be the same color as used for the background of Business Desk itself. This should occur automatically when the Business Desk customizable style sheet (CSS) is used.

  • The font for all text in modal dialog boxes is 8 pt. Verdana.

  • All buttons along the bottom of the dialog should be right-justified by including them in a table with a wide far-left cell and follow the normal order of such buttons in Win32 applications:
    <table width=100%><tr>
<td width=100%></td>
<td><button…><button…><button…></td>
</tr></table>


Confirmation, Warning, and Error Dialogs

Confirmation, warning, and error dialogs should conform to the following conventions:

  • All warning messages should be displayed in a message box with the title text set to "Warning". The only button should be the OK button (vbOKOnly).

  • All field validation errors should be displayed in a message box with the title text set to "Validation error". The only button should be the OK button (vbOKOnly).

  • Cross-field validation should usually be done using the onChange event for all fields involved. For example, if you want an end date to always be after a start date, then you should add an onChange event handler to both fields that checks that both fields are valid and that this condition exists; if not, you should display a message box as described above.

  • Any errors other than field validation should be displayed using the ShowErrorDlg routine. Server-side errors can be saved for display on the next page by calling SetError routine. For more information about these routines, see ShowErrorDlg (client-side) and SetError (server-side).

  • Delete confirmation dialogs should be displayed in a message box with the title text set to "Delete?". The dialog should use Yes and No buttons (vbYesNo). Confirmation dialogs for Restore or other similar operations should be handled in the same way.

  • The file SharedStrings.asp defines a number of string constants meant for use in these types of dialogs.

  • To promote a consistent user interface for simple confirmation, warning, and error dialogs, use the ASP files dlg_confirm.asp, dlg_warn.asp, and dlg_error.asp, respectively, as the first argument to the showModalDialog routine.

    These files are located in the Include folder. See the file ActionPageUtil.asp for examples.

Properly built Edit Pages allow the Framework to handle the enable/disable state of the Save and SaveNew tasks as well as Save confirmation and warning dialogs. The following practices must be observed to obtain this behavior:

  • Use one master EditSheet HTC to contain all editing controls on the page.

  • Associate the following handlers with the master EditSheet HTC events:
    • The SetDirty method with the onChange event,

    • The SetRequired method with the onRequire event, and,

    • The SetValid method with the onValid event.

    If additional functionality is required, make sure you call one of these routines, as appropriate, in your event handler.

  • If nested EditSheet HTCs on the page use the template mechanism for freeform layout, make sure to register the IDs of any HTCs within the template in the register attribute of the template element.

  • HTML checkbox and radio button elements need special handling because they do not fire the onChange event. This means that they cannot be registered using the register attribute of the template element. For HTML checkbox and radio button elements, explicitly call the SetDirty method as the onClick handler for each element.

  • When the Edit Page is properly constructed, the Save and SaveNew buttons will not be enabled unless changes have been made to the page, all fields are valid, and no required fields are missing. Note that any special cross-field validation must be done separately.


Asynchronous Behavior

Commerce Server Business Desk modules should not leave the user wondering whether Business Desk is still working or not. This means that operations that take a long time to complete should be performed asynchronously, with some feedback provided to the user indicating that the operation has been started and is being performed.

Any operation that could take more than 10 seconds to complete should provide an intermediate page with the status message: "Loading... Please wait." This is automatically displayed when initially loading a page and when a ListSheet HTC is executing a fetch operation via XMLHTTP.

Operations that could take in excess of one minute to complete, such as importing or exporting a catalog, or generating reports, should be designed in a truly asynchronous fashion. They should run on the server in a separate process, allowing the Business Desk user to perform other tasks in the meantime. The user should be informed that processing has begun, and there should be a page where the user can view the completion status of all such long-running operations.


Error Messages

Commerce Server Business Desk uses a centralized set of friendly error messages for use by all Business Desk modules. These error messages are used for errors encountered within the Business Desk module code, and not in response to HTTP errors. Typically, modules also define their own, unique error messages for use where no shared friendly error message will suffice.

Friendly error messages are passed to the routines SetError and ShowErrorDlg as a text string (in the strFriendlyError parameter).

Server-side friendly error messages are available through a MessageManager object, initialized on application start-up (Global.asa), and then placed in the Application object. Client-side friendly error messages are available through the XML Document Object Model (DOM), added to it when the Business Desk Framework initializes. Using these mechanisms, all module writers have access to the same set of shared error messages.

In addition to both centralized and private friendly error messages, the routine that displays errors can also include detailed information. The detailed information is initially hidden in the error dialog box, but can be shown by clicking the Details button.

Detailed error information is passed to the routines SetError and ShowErrorDlg as a string containing pre-formatted HTML (in the strErrorDetails parameter). If the strErrorDetails parameter is found to be empty, then no Details button is displayed in the dialog box.

The HTML formatting typically specifies a small table with two columns containing a name and value, respectively.

There are a number of client-side and server-side error formatting routines, designed to translate a variety of error objects into a corresponding HTML table. For example, the sGetScriptError client-side routine formats the contents of the global VBScript Err object into an HTML table, and returns it as a string.

The Business Desk Framework provides the following two client-side and four server-side error formatting routines, useful for formatting ADO, ASP, VBScript, and XML Parse errors.

Server-side error formatting routines:

sGetADOError (server-side) | sGetScriptError (server-side)
sGetASPError (server-side) | sGetXMLError (server-side)

Client-side error formatting routines:

sGetScriptError (client-side) sGetXMLError (client-side)

The server-side routine SetError caches its parameters in the Session object, where they are displayed on the client the next time one of the taskbar insertion routines is called. The SetError routine also appends the error to the Microsoft Windows NT Event Log.

Business Desk handles HTTP errors differently, displaying a custom error page. This page contains the original Internet Information Services (IIS) error text, but it is presented in a page that is branded with a Business Desk image. By default, all HTTP "page not found" and "access denied" errors reported by IIS are handled in this standard way.

HTCs gracefully handle XML configuration inputs with missing attributes or tags. If an HTC encounters an error when initializing due to malformed XML, the control will not display and a standard message stating "The control could not load. Please contact your system administrator" will be displayed in a standard message box. There will also be a button that allows the user to see the details of the XML error that caused the control failure.

Data validation error checking is typically performed, and appropriate errors displayed, within the HTCs being used to edit the data. Additional validation error messages, such as for cross-field validation, should display using the standard MsgBox function in the Internet Explorer Document Object Model (DOM).

The ListSheet HTC expects errors returned from fetch pages to be encoded in error nodes by the AddErrorNode routine in the file HTTPXMLUtil.asp. The ListSheet HTC will then automatically display these errors in a dialog.


Status Messages

Status messages should conform to the following guidelines:

Selection:

  • When a single item is selected in a list, the status text should read:

    Selected itemtype: itemname

  • When multiple items are selected, the status text should read:

    number selected

  • When the Select All button is used, the status should read:

    All items in all pages are selected

  • When the last selected item is unselected, the status text should read:

    No items selected

Find:

  • When no items are found, the status text should read:

    No items found

  • When one item is found, the status text should read:

    1 item found

  • When a known number of multiple items are found, the status text should read:

    number items found

Delete:

  • When a single item is successfully deleted, the status text should read:

    Deleted itemtype: itemname

  • When multiple items are successfully deleted, the status text should read:

    number items deleted

  • When a single item is not successfully deleted, the status text should read:

    Unable to delete: itemname

  • When multiple items are not successfully deleted, the status text should read:

    Unable to delete number items

For other operations that result in the re-display of a list, status text similar to that used for Delete operations should be used. Examples of such operations include: import, export, and restore.


Links Between Modules

In general, if one module contains a direct link to another module, it should be implemented through a task button. For example, there is a task button in the Campaign Manager that links to the analysis reports.


Help Topics

To specify a help topic for a particular action page with a module, provide the name of the HTML file containing the help topic as the value of the helptopic attribute of the appropriate action element in the appropriate module configuration file. This file must exist in the docs/htm folder.

When new help topics are added to the docs/htm folder, you can also add corresponding entries to the file Bizdesk.hhc in the docs folder. This will allow the new topics to appear in a particular location within the help system table of contents. Any new index entries related to the new topics can be added to the file Bizdesk.hhc, located in the same folder.

Note

  • Extreme care should be used when making additions to the .hhc and .hhk files so that the existing table of contents and index entries are not disturbed.

Dialog boxes can also have help displayed from a button to the right of the OK and Cancel buttons. When this button is clicked, call the OpenHelp routine with the name of the HTML file containing the help topic in question. This file must exist in the docs/htm folder.


Business Desk Configuration

Different instances of Commerce Server Business Desk can be configured to contain different categories and modules. This configuration is accomplished using a distinct set of XML files for each Business Desk instance. This set of files is comprised of a single master configuration file, named BizDesk.xml, and a series of module configuration files, whose names are variable but refer to the particular module or category with which they are associated. The XML in these two types of files is combined to create a particular configuration using moduleconfig elements in the master configuration file, each of which specifies a distinct module configuration file.

Multiple modules can be defined in a single module configuration file, or each module can be defined in its own module configuration file, or some combination thereof.

The order of category definition in the master configuration file, the order of module definition with a module configuration file, and the order in which module configuration files are defined as belonging to a particular category, define the order in which categories and modules appear in the navigation pane.

All of the configuration files for a particular site, both master and module configuration files, are located in the Config folder under the root folder of the site.

When the Business Desk application loads, it creates a Dictionary object structure that merges the information in the master configuration file and all associated module configuration files, and stores this structure in the Application object. Then, for each particular Business Desk session, this structure is filtered based on the role defined for the current user, creating a custom Business Desk navigation tree for that role.

Note

  • Any manual changes to the master and module configuration files are not reflected in Business Desk until Internet Information Services (IIS) is reset or the Business Desk application is otherwise restarted.

A detailed explanation of the structures of the master and module configuration files is provided in the following XML reference topics:

  • Master Configuration File

  • Module Configuration Files


Data Manipulation in Business Desk

Commerce Server Business Desk is a data-driven application that serves as a management interface for data-driven Web sites. It provides an easy to use mechanism for examining and modifying the various items of data displayed as the content of the Web site pages viewed by Web site users. This data is usually stored in Microsoft SQL Server 2000 databases and the Active Directory directory, though it is possible for the data to exist in other types of databases.

Another important aspect of Business Desk is its reliance on Dynamic HTML (DHTML) and HTML Components (HTCs). These technologies allow for more interactivity within the Web browser itself than has been typical of Web applications, dramatically reducing the number of server roundtrips required to manipulate data in powerful ways. The data to be manipulated is delivered to the Web browser within the page itself; it is passed to the Web browser in a form known as an XML data-island.

An XML data-island is a well-formed segment of XML contained within an xml element and identified by the value associated with the id attribute of that element. The data itself is represented within the XML structure. The structure of the XML is limited only by the rules of XML syntax and the conventions adopted by the script code that is designed to access it. The data is accessed using the normal mechanisms of the Document Object Model (DOM). Such access occurs within the various HTCs that are part of the Business Desk Framework, and can also occur in client-side script on the Web page itself.

The purpose of this section is to describe the typical mechanisms employed by various Business Desk modules to allow Business Desk users to alter the Web site while minimizing the server roundtrips often associated with poor performance in Web applications. The basic steps required to provide this functionality are:

  1. ASP code on a Business Desk module Web page retrieves the data from the database, typically using Active Data Objects (ADO).

  2. ASP code on the page converts a Recordset object returned by ADO into an XML data-island using one of several framework routines.

  3. Microsoft Internet Explorer 5.5 downloads the page, which now contains the XML data-islands and elements with styles linking them to the corresponding HTCs. All the edit type HTCs with the exception of the ExpressionBuilder, ListEditor and DynamicTable include form elements that will automatically be posted with an enclosing form.

  4. The HTCs execute within Internet Explorer 5.5, using the included XML data-islands as the source of configuration information and the data to be displayed.

  5. The user makes changes to the data, eventually requesting that those changes be saved.

  6. The changes are posted back to a Business Desk module Web page using an HTML form. This page converts the posted changes into the appropriate ADO Recordset object format, and then uses ADO to update the database with those changes.

The remainder of this section consists of topics discussing each of these main aspects of data manipulation.

This section contains:

  • XML Data-Islands. Describes how XML data-islands on the ASP pages are used to pass data to the HTCs, and specifically describes the different ways in which XML data-islands can be created.

  • Data versus Meta-data. Describes the difference between data and meta-data in the context of Business Desk, and particularly in the context of the HTCs provided by the Business Desk Framework.

  • Retrieving Data. Describes typical mechanisms for accessing databases from server-side script.

  • Getting Data to the Client. Describes how the Recordset objects returned by ADO are converted to XML data-islands on the page being downloaded to the Web browser.

  • XML Data Merging. Describes how some XML data-islands can be merged for use in the more complex forms of the ListSheet HTC.

  • XMLHTTP Operations and Fetch Pages. Describes special mechanisms used by the ListSheet and TreeView HTCs for retrieving new data from the server without needing to be reloaded in the browser.

  • Data Validation. Describes the data validation techniques employed within both client-side and server-side scripts.

  • Saving Changes to Data. Describes how the data representing modified records is returned to the server and persisted back to the databases from which it originated.


XML Data-Islands

XML data-islands are used to pass data to the HTML Components (HTCs) used on many of the ASP pages in Commerce Server Business Desk. An XML data-island is data, described in XML, that is accessed through an id attribute associated with one of two different elements (xml and script) that might be contained in the ASP page. The data itself often exists in the ASP pages themselves, but need not.

An XML data-island can exist in an ASP page, either hard-coded or generated programmatically using ASP script, using one of the following three tagging mechanisms:

  • Within an xml element:
    <xml id='DataIslandID'>
    data-island XML can go here
</xml>
  • Within a script element that includes the type attribute with the value "text/xml":
    <script type='text/xml' id='DataIslandID'>
    data-island XML can go here
</script>
  • Within a script element that include the language attribute with the value "xml":
    <script language='xml' id='DataIslandID'>
    data-island XML can go here
</script>

The XML data comprising the data-island does not need to be specified on the ASP page itself. Any of the above mechanisms for embedding an XML data-island on an ASP page can use the src attribute to specify the URL of another file from which the contents of the data-island will be retrieved. Any of the following three single lines of code, in conjunction with the data-island XML contained in the specified source file, specify legitimate XML data-islands:

<xml    id='DataIslandID' src='XMLDataFileURL' />

or

<script id='DataIslandID' src='XMLDataFileURL' language='xml' />

or

<script id='DataIslandID' src='XMLDataFileURL' type='text/xml' />


Data versus Meta-data

The HTML Components (HTCs) used to manipulate data within Commerce Server Business Desk modules are instantiated on a Web page as DHTML behaviors associated with an element on the page, typically a DIV element. This element is known as the container element because it contains the HTC. The container element can have arbitrary attributes assigned to it, allowing them to be accessed from the code in the HTC. Such attributes are known as container attributes, and an important aspect of understanding each of the HTCs supplied with the Business Desk Framework is an understanding of the container attributes it expects to be associated with its container element.

A common type of value for a Business Desk HTC container attribute is a string that is the ID of a corresponding data-island in the document. Two of the container attributes expected by most of the Business Desk HTCs each provide the ID of an XML data-island. One of these IDs references a data-island that contains the actual data to be manipulated, represented in a standard format that is an XML representation of a set of database records. The other ID references a data-island that contains what is known as meta-data, or data about the data. For each of the fields in the records of the set, this includes such information as the type of the data and the name to be displayed in the column heading. In addition, the meta-data for many HTCs includes global configuration information that affects the display and behavior of the HTC as a whole.

The data for a particular field in one data-island and the corresponding meta-data for that field in the other data-island are associated using XML attributes and elements. Attributes in the meta-data XML identify a corresponding element in the XML containing the data.

The following table shows the container attributes associated with each of the Business Desk HTCs. With the exception of the meta-data container attribute named DataID, all the data and meta-data container attributes are assigned values that are the same as the value of the id attribute of the corresponding XML data-island (the id attribute of an xml or script element). The container attribute DataID is a special case; it is assigned a value that is the same as the id attribute of a field element within the data-island specified by the corresponding MetaXML container attribute.

HTC Name | Data Container Attributes | Meta-Data Container Attributes | Miscellaneous Container Attributes
DynamicTable | DataXML | MetaXML | <none>
EditField | DataXML | MetaXML | <none>
EditSheet | DataXML | MetaXML | <none>
ExpressionBuilder | <none> | XMLCfgID | <none>
ListBox | <none> | <none> | <none>
ListEditor | DataXML | MetaXML | <none>
ListSheet | DataXML | MetaXML | <none>
QueryBuilder | <none> | XMLCfgID | AutoActivate
TreeView | DataXML | <none> | <none>

The format of the meta-data data-islands is specific to each HTC. For more information about the details of these XML formats, see Business Desk XML Structures.

With one exception, the data-island associated with the DataXML container attribute is in a standard format, regardless of which HTC is in use. For more information about this standard format, creating data-islands programmatically, and creating data-islands containing hierarchical data, see Standard XML Data Record Format, Getting Data to the Client, and XML Data Merging, respectively.

The exception to the standard format usage is the TreeView HTC, which expects the data-island associated with the DataXML container attribute to have a completely different format. For more information about this format, see TreeView Configuration.


Retrieving Data

In general, the Commerce Server Business Desk modules that ship with Microsoft Commerce Server 2000 make use of Active Data Objects (ADO) within ASP code to access a database and retrieve the relevant information in the form of an ADO Recordset object. Business Desk provides some global variables and utility functions for creating ADO Connection and Command objects that most of the Business Desk modules shipped with Commerce Server 2000 use. These variables and functions are defined in the Business Desk include file DBUtil.asp.

The DBUtil.asp include file includes the following line to define global ADO Connection and Command objects for use on Business Desk module ASP pages:

Dim g_oConn, g_oCmd

The DBUtil.asp include file defines the routine oGetADOConnection. This routine takes a connection string as its only parameter. It returns a reference to an ADO Connection object that has been initialized with connection and command timeouts of 15 and 30 seconds, respectively, and that has been opened using the passed connection string.

The DBUtil.asp include file also defines the routine oGetADOCommand. This routine takes a Connection object and a command type as parameters. It returns a reference to an ADO Command object that has been initialized to use the passed connection and command type. The passed command type is typically AD_CMD_TEXT, which is also defined in this file.

When these two routines are combined with the creation and opening of an ADO Recordset object, the result is a Recordset object containing the results from the query, ready to be converted into an XML data-island. For more information about converting a Recordset object into and XML data-island, see Getting Data to the Client. The strings sYourConnectionString and sYourSqlQuery, used in the following script, must have been defined elsewhere.

Set g_oConn = oGetADOConnection(sYourConnectionString)
Set g_oCmd = oGetADOCommand(g_oConn, AD_CMD_TEXT)

Dim rsRecSet
g_oCmd.CommandText = sYourSqlQuery
Set rsRecSet = Server.CreateObject("ADODB.Recordset")
rsRecSet.Open g_oCmd, , AD_OPEN_KEYSET, AD_LOCK_PESSIMISTIC


Getting Data to the Client

Data is passed to the Commerce Server Business Desk HTML Components (HTCs) in the form of XML data-islands, frequently within the Web page itself. When the HTCs are executed by Internet Explorer 5 on the client, they can access and display this data for the Business Desk user.

For more information about the ways in which XML data-islands can be created on a page, see XML Data-Islands.

The DBUtil.asp include file defines several routines for producing XML data-islands in the correct format. These routines write all the resultant XML onto the page with the exception of the surrounding xml or script element, and its attributes. Note that the id attribute of both the xml and the script elements is required to identify the data-island to the HTC that is going to use it.

The DBUtil.asp include file contains two routines for converting ADO Recordset objects into the corresponding XML data-islands understood by the HTCs: xmlGetXMLFromRS and xmlGetXMLFromRSEx. It also includes two routines that result in the same XML data-islands, but that also include the database connection and query steps: xmlGetXMLFromQuery and xmlGetXMLFromQueryEx. For more information about these functions, see one of the following:

  • xmlGetXMLFromRS (server-side)

  • xmlGetXMLFromQuery (server-side)

  • xmlGetXMLFromRSEx (server-side)

  • xmlGetXMLFromQueryEx (server-side)

Many of the Microsoft Commerce Server 2000 COM objects are designed to return ADO Recordset objects specifically so that one of these routines can be called to convert them to XML data-islands on an ASP page.

The following code example shows how the invocation of the xmlGetXMLFromRS routine can appear within an xml element on an ASP page. Invocation of this routine and each of the other three routines can appear within an xml element, or within a script element containing the proper attributes to identify it as containing an XML data-island. The id attribute of the xml or script element, DataIslandID, is then assigned to the DataXML container attribute of the DIV element containing the corresponding HTC.

<xml id='DataIslandID'>
<%
    xmlGetXMLFromRS rsRecordset
%>
</xml>

From the perspective of the HTC, it is not important that the XML data-island be produced using one of the provided routines, or even that it be produced from an ADO Recordset object. All that matters from the perspective of the HTC is that the XML data-island be in the expected format. This design allows for greater flexibility with respect to where the data originates, and how it is processed prior to being converted to the proper XML format. The original data may be hard-coded on the page or even the result of an XSL transform.


XML Data Merging

The ListSheet HTML Component (HTC) can be instantiated in several different modes. Many of these modes present data in a hierarchical fashion, allowing details to be hidden, drilled into, and then hidden again. When operating in this manner, the ListSheet HTC expects data to be represented hierarchically in the corresponding XML data-island. This is achieved by merging either two (or three) distinct single-tiered XML data-islands into a single two-tiered (or three-tiered) data-island. The following routines, provided by the Commerce Server Business Desk Framework, perform data merging of this sort:

sMergeGroups2 (server-side) | sMergeGroups2 (client-side)
sMergeGroups3 (server-side) | sMergeGroups3 (client-side)
xmlMergeGroups2 (server-side) | xmlMergeGroups2 (client-side)
xmlMergeGroups3 (server-side) | xmlMergeGroups3 (client-side)
 | xmlMergeGroupsByID2 (client-side)
 | xmlMergeGroupsByID3 (client-side)

The following example illustrates how XML data merging works for two levels. A three level merge is conceptually similar. The following XML representation of two records is considered to be the higher-level information, containing in this case the name and age of different people, to be displayed in the group rows of a ListSheet HTC (the userid is configured to be hidden).

<xml id=master>
    <document recordcount=2>
        <record>
            <name>David</name>
            <age>39</age>
            <userid>dav001</userid>
        </record>
        <record>
            <name>Sarah</name>
            <age>33</age>
            <userid>sar015</userid>
        </record>
    </document>
</xml>

The following XML representation of three records is considered to be the detailed information, containing in this case the names and ages of the children of the people in the XML structure above, to be displayed in the detail rows of a ListSheet HTC (the userid is configured to be hidden).

<xml id=detail>
    <document recordcount=2>
        <record>
            <userid>sar015</userid>
            <name>Jennifer</name>
            <age>6</age>
        </record>
        <record>
            <userid>sar015</userid>
            <name>Thomas</name>
            <age>3</age>
        </record>
        <record>
            <userid>dav001</userid>
            <name>Lilly</name>
            <age>10</age>
        </record>
    </document>
</xml>

A variety of MergeGroups routines can be used to combine either two or three sets of XML records, resulting in a two- and three-tier set of records appropriate for use with a two- or three-level ListSheet HTC. If the two XML structures above are represented in two XML document objects referenced by the variables xmlMaster and xmlDetail, respectively, they could be merged by calling the following routine, which places the resulting merged XML in the string variable sMerged:

sMerged = sMergeGroups2(xmlMaster, xmlDetail, "userid")

The field element name userid is passed in as the key. It must be an element that exists in both sets of records. If a record in the master set and a record in the detail set are found to have the same value for the specified element, the two records are merged in the resulting set, with the master record elements occupying the first-tier of the result record and the detail record elements occupying the second-tier of the result record.

The following XML representation shows the result of combining the two sets of records above. The merged, second-tier fields are shown in bold font. Note that the key element, at least, appears on both tiers of the result records:

<xml>
    <document recordcount=2>
        <record>
            <name>David</name>
            <age>39</age>
            <userid>dav001</userid>
            <record>
                <userid>dav001</userid>
                <name>Lilly</name>
                <age>10</age>
            </record>
        </record>
        <record>
            <name>Sarah</name>
            <age>33</age>
            <userid>sar015</userid>
            <record>
                <userid>sar015</userid>
                <name>Jennifer</name>
                <age>6</age>
            </record>
            <record>
                <userid>sar015</userid>
                <name>Thomas</name>
                <age>3</age>
            </record>
        </record>
    </document>
</xml>


XMLHTTP Operations and Fetch Pages

The ListSheet and TreeView HTML Components (HTCs) support a special class of operations in which a form is posted to a special type of page on the server. This type of page is known as a fetch page. Fetch pages are designed to process these operations and return the results as an XML document containing data in the standard XML data format.

Nothing besides the XML data can be present on the page being returned. Indeed, the content type of the page being returned must be set to "text/xml." Specifically, every fetch page should include the file BDXMLHeader.asp, which establishes the content type and other common page characteristics. Some of the lines from this include file are shown here with the two alternative forms of the first line, the second of which specifies the Norwegian IA5 codepage (do not duplicate line 1 in the actual include file):

 Line
   1    <%@ Language=VBScript %><%'@ Language=VBScript CodePage=1252 %><%
   1    <%'@ Language=VBScript %><%@ Language=VBScript CodePage=20108 %><%
   2
   3    ' switch the @ lines above to set a codepage
   4    ' that is different than the system locale
   5
   6    '   IE 5.5 supports the following settings for charset and codepage:
   7    '      (these are recommended though not all have been tested)
   8

At this point, the file BDXMLHeader.asp includes a list of possible CodePages. Refer to the actual file for details.

   n
 n+1    Option Explicit
 n+2
 n+3    if not isEmpty(Application("MSCSPageEncodingCharset")) then _
 n+4               Response.Charset = Application("MSCSPageEncodingCharset")
 n+5    Response.AddHeader "Pragma", "no-cache"
 n+6    Response.ContentType = "text/xml"
 n+7    Response.Expires = -1
 n+8    Response.Buffer = true
 n+9    %><?xml version='1.0' encoding='<%= Response.Charset %>' ?>
n+10

It is important that the content type of the returned page is set to "text/xml" so that the browser passes the data through to the existing list page, without re-rendering anything. The point of an XMLHTTP operation is to allow the ListSheet and TreeView HTCs to fetch and display new data from the server without reloading the entire list page.

Since the ListSheet HTC posts an XML document, the fetch page can access the various arguments included with the posted form by converting this XML request to a Dictionary object using the dGetRequestXMLAsDict routine. For example:

set g_dRequest = dGetRequestXMLAsDict()
sOperation = g_dRequest("op")

Another important consideration in the construction of fetch pages concerns include files. Since the data returned by the page must be pure XML, any client-side script or HTML will corrupt this XML and make it invalid. The file ActionPageUtil.asp is a good example of a file that must not be included in fetch pages for these very reasons.

At times, the fetch page may need to save some or all of the data passed to it as form arguments so that that data can serve as defaults for the remainder of the session. The ASP Session object is the most natural candidate for saving this type of data. A common example of this type of data is the criteria used within the find pane. If preserved in the Session object, these criteria can be available to be set as the default values in the event that the list page needs to be re-rendered (such as after returning from an edit page).


Data Validation

One of the main purposes of Commerce Server Business Desk is to provide a way for business managers to change the data that determines how their Web site appears to users. Such changes can consist of changing existing data, adding new data, or deleting old data. Several types of errors can occur when data is entered. The entered data might not be of the correct type, or it could exceed the allowable range of values. When a new record is being created, some of the required data could be missing. Further, there could be inconsistencies between various fields in a record based on dependencies between those fields.

Some types of errors are relatively easy to detect and handle in a generic way. Such errors are handled automatically within the relevant HTML Components (HTCs), completely on the client-side. Such errors include:

  • Enforcement of minimum and maximum allowable values for numbers, dates, and times. The min and max attributes of some types of child elements of the fields element are used to specify these restrictions, which are enforced when the input field loses focus.

  • Enforcement of a maximum and minimum length for text input. The maxlen and minlen attributes of some types of child elements of the fields element are used to specify these restrictions, which are enforced when the input field loses focus.

  • Enforcement of matching a particular pattern of characters. The charmask child element of some types of child elements of the fields element is used to specify such pattern restrictions, which are enforced when the input field loses focus.

  • Enforcement of certain formats. The format child element of some types of child elements of the fields element is used to specify such formats, which are enforced when the input field loses focus. Date and Numeric types support different formats.

  • Enforcement of required fields being supplied with a non-empty value. The required attribute of some types of child elements of the fields element is used to specify this restriction, which is enforced when the user commits changes.

The Business Desk user is notified of these types of errors as soon as they are detected, before the erroneous values are sent to the server for subsequent processing. Errors are reported using client-side modal dialog boxes that provide the Business Desk user with a standardized error message, or in the case of the pattern matching errors, a customized error message that is specified in the XML configuration information along with the pattern itself. Once the invalid data dialog box is dismissed, the field or fields that caused the error are marked to draw the attention of the Business Desk user to those fields.

Some types of data validation are more involved and must be handled by the module in a custom manner, usually on the server-side. These types of validation include uniqueness checking across records and cross-field validation. When these types of errors occur, the module is responsible for displaying an appropriate error message, re-displaying the page upon which the error was made, and restoring the state of that page.

A common technique for performing cross-field data validation in client-side code is to trap the OnChange event provided by many of the Business Desk HTCs. You can write a handler function for the OnChange event that, for example, performs consistency checking between different fields on the page, or which forces a user-supplied value into a more acceptable format. The following HTCs support the OnChange event:

  • DynamicTable

  • EditField

  • EditSheet

  • ListEditor


Saving Changes to Data

The most typical scenarios for saving changes to data is to save a record or set of records that have presumably been altered, or deleting one or more records. In general, saving changes could be the initial save of a new record, the saving of changes to an existing record, or the saving of similar changes to a set of records. In all of these cases, the save or delete action is usually initiated by a user pressing a task button.

The changed data is sent to the server to be saved using HTML forms with the POST method (as opposed to the GET method). Typically, for each server-side page used to process such changes to data, a unique HTML form is defined that specifies the arguments to be posted with the form. The following lines of HTML code show the definition of such a form:

<FORM ID='memberchange' METHOD='POST'>
    <INPUT TYPE='hidden' ...>
    ...
    <INPUT TYPE='hidden' ...>
</FORM>

The ACTION attribute is usually not specified for forms used for tasks within the Commerce Server Business Desk Framework. Rather, the association of particular forms and the pages designed to process them is accomplished through the module configuration files. For more information about how forms are associated with the pages designed to process them, see the postto topic in the Module Configuration Files section.

Normally, various edit type HTCs will be enclosed in the form and each will automatically create an INPUT element using the same name as the XML node with which the HTC is associated.

Other arguments for the form can be defined as INPUT elements with their type attributes set to "hidden". Other important attributes that need to be set are:

  • The id attribute, which allows access to the element through the Document Object Model (DOM).

  • The name attribute, which supplies a name to associate with the item of data when posting the form.

  • The value attribute, assuming that there is a default.

The id attribute and the name attribute can be assigned the same value.

The following line of HTML code illustrates a typical INPUT element within such a form, including a default value provided by an ASP variable:

<INPUT TYPE='hidden' ID='expdate'
       NAME='expdate' VALUE='<%= DefaultExpDate%>'>

Sometime before the form is submitted, the module code may assign a (new) value to the INPUT element using the DOM. The element is located using its id attribute and the (new) value is assigned to its value attribute. Once such value changes have been made for all appropriate input elements associated with the form, the form can be submitted and the values become available to the server page processing the changes through the ASP Request object.

A hidden value in a form is often set as a result of an event in the ListSheet HTML Component (HTC). For example, when the OnRowSelect event fires, the key ID for the selection can be placed in a hidden input field so that the selection is sent to an edit page when the form is posted by the task.

Occasionally, you may need to perform some special client-side processing after the task button is clicked, but before the form is posted. Most often, this involves requesting further information from the user, such as asking what type of new record to add, or confirming a modification or delete operation. Sometimes such processing can be performed automatically, without further user interaction. In any event, different processing paths are possible, including different data being submitted with the form, different forms being submitted, or the same form being submitted to a different page for processing.

An ONTASK attribute is defined for the FORM element to support this requirement. If the ONTASK attribute is defined for a FORM element being processed by the Business Desk Framework, the Framework attempts to execute the value provided for that attribute. Most often, the value is a routine name, allowing that routine to perform the required processing.

The following line of HTML code shows the same FORM element as above, though this time it has an ONTASK attribute defined:

<FORM ID='memberchange' METHOD='POST' ONTASK='OnMemberChange'>

When an ONTASK attribute is defined, the executed routine is responsible for submitting the form once the special processing is accomplished. The form can be submitted using the submit method of the form.

The final step in changes to data being persisted to a database occurs within ASP code on the server. A form is posted to an ASP page on the server, and it generally includes various fields of data that can be accessed using the ASP Request object. Using this object, the server-side script retrieves the data posted with the form and places it into an Active Data Objects (ADO) Recordset object to be persisted.

The information in the form will include any fields that were in an EditSheet contained by the form. This includes all EditFields and fields in the EditSheets, which will be sent along with the form.

The DynamicTable and ListSheet HTCs, however, return XMLlists instead of fields. These XMLlists, retrieved through the OnChange event object property XMLlist, needs to be assigned to a hidden form field (see the shipping page for an example).


HTML Components in Business Desk

The Commerce Server Business Desk Framework includes a number of HTML Components (HTCs) that are used extensively by the modules that ship with Commerce Server 2000. (HTCs are one of the ways in which the DHTML behaviors supported in Internet Explorer 5 can be implemented. The HTCs supplied with Commerce Server are more complex than typical Internet Explorer 5 behaviors.) The Business Desk HTCs are also intended for use in new Business Desk modules developed by third parties. Not only does such use save third parties significant effort in developing new modules, it benefits the users of Business Desk by promoting a common look-and-feel throughout an extended Business Desk.

Each of the HTCs that ship with Business Desk defines a unique set of events, properties, and methods. Each HTC also has a particular format in which it expects to be passed its configuration data, including both the configuration data used to control the behavior and display of the control, as well as the actual Web site data itself. Also, each HTC is instantiated within script on an ASP page in a slightly different manner. These details are provided in the Business Desk Reference in the section entitled HTML Components.

Each HTC has a variable named m_bDebug, defined at the beginning of the HTC file containing the script code for the HTC. If this variable is set to True, error messages display in alerts to help in debugging while a module is being developed. If the variable m_bDebug is set to False, the same error is sent in an onError event instead of being displayed in an alert. The onError event can then be trapped and handled in script code.

The following table describes the HTCs supplied with the Business Desk Framework, and provides links to more detailed information in the Programmer’s Reference.

HTML Component | Description
DynamicTable | Used for editing tabular data where editing is limited to the columns being displayed.
EditField | Used for editing individual items of data of various types.
EditSheet | Used to bundle together other controls that are used to edit data.
ExpressionBuilder | Describes the control used for creating named expressions that can be used for targeting. The ExpressionBuilder HTC makes use of an embedded version of the QueryBuilder HTC.
ListBox | Used for list-to-list copy and move operations.
ListEditor | Used for editing tabular data where the editing of individual records occurs in a separate table below the table containing the list.
ListSheet | Used to display a list of records and allows selection of one or more of those records for editing. This HTC is read-only.
QueryBuilder | Used to build a simple query.
TreeView | Used to display an XML structure in a tree format.

The ListSheet and TreeView HTCs are unique in that they both offer a mechanism for requesting additional XML data from the server without needing to reload the entire page containing the HTC in question.


Business Desk Utilities

An important aspect of the Commerce Server Business Desk Framework is the set of constants, global variables, and utility routines that provide an extensive base of shared code used by the modules that ship with Microsoft Commerce Server 2000, and which are intended for use by third party developers of new modules.

This shared code is made available to Business Desk modules in the form of include files, specified in the action pages for a module. Depending on the nature of the action page, such as whether it contains client-side script or server-side script, or both, different include files are appropriate for inclusion.

The details of the constants, global variables, and utility routines in the various include files are provided in the Business Desk Reference, in the following sections:

  • Include Files. Describes the include files that define the constants, global variables, and utility routines that constitute much of the Business Desk Framework. Explains when to include and when to not include each of these files.

  • Constants. Describes the constants defined in the various Business Desk include files. Defines which constants are available in client-side versus server-side script.

  • Global Variables. Describes the global variables defined in the various Business Desk include files. Defines which global variables are available in client-side versus server-side script.

  • Utility Routines. Describes the routines defined in the various Business Desk include files. Defines which routines are available in client-side versus server-side script.

    Many of the utility routines are shown in the following list, organized according to their intended use.

Action Page Routines:
ClearStatusText (client-side) | OpenHelp (client-side)
dGetAction (server-side) | SetPageTitleText (client-side)
HideStatusAnimation (client-side) | SetStatusText (client-side)
HideStatusLegend (client-side) | SetWaitDisplayText (client-side)
HideWaitDisplay (client-side) | ShowWaitDisplay (client-side)
List Page Routines:
HideFindBy (client-side) | ShowFindBy (client-side)
InsertTaskBar (server-side) | ToggleFindBy (client-side)
SetFindByHeight (client-side) |
Edit Page Routines:
InsertEditTaskBar (server-side) | SetDirty (client-side)
OpenEditPage (client-side) | SetRequired (client-side)
ResetSaveBtns (client-side) | SetValid (client-side)
Task Button Routines:
DisableTask (client-side) | EnableTask (client-side)
DisableTaskMenuItem (client-side) | EnableTaskMenuItem (client-side)
elGetTaskBtn (client-side) | SetTaskTooltip (client-side)
EnableAllTaskMenuItems (client-side) | ToggleTask (client-side)
EnableAllTasks (client-side) |
General Utility Routines:
AddClass (client-side) | nGetYear (client-side)
BDHALsizeButtons (server-side) | RemoveClass (client-side)
BDHALsizeSelects (server-side) | ReplaceClass (client-side)
bHasClass (client-side) | sFormatString (client-side)
bIsDate (client-side) | sFormatString (server-side)
dtGetDate (client-side) | sGetFormattedDate (client-side)
GetSiteConfigField (server-side) | sRelURL2AbsURL (server-side)
nGetDay (client-side) | xmlGetSiteTermsValue (client-side)
nGetMonth (client-side) |
State Saving Routines:
ClearTemp (client-side) | dSetServerState (client-side)
dClearServerState (client-side) | GetTemp (client-side)
dGetServerState (client-side) | SetTemp (client-side)
Data Retrieval Routines:
oGetADOCommand (server-side) | xmlGetXMLFromQuery (server-side)
oGetADOConnection (server-side) | xmlGetXMLFromQueryEx (server-side)
rsGetRecordset (server-side) |
XML Conversion Routines:
dDictFromXML (client-side) | xmlMergeGroups2 (client-side)
dDictFromXML (server-side) | xmlMergeGroups2 (server-side)
sMergeGroups2 (client-side) | xmlMergeGroups3 (client-side)
sMergeGroups2 (server-side) | xmlMergeGroups3 (server-side)
sMergeGroups3 (client-side) | xmlMergeGroupsByID2 (client-side)
sMergeGroups3 (server-side) | xmlMergeGroupsByID3 (client-side)
xmlGetXMLFromRS (server-side) | xmlXMLFromDict (client-side)
xmlGetXMLFromRSEx (server-side) | xmlXMLFromDict (server-side)
XML DOM Helper Routines:
AddCDATANode (client-side) | AddItemNode (server-side)
AddCDATANode (server-side) | AddWarningNode (server-side)
AddErrorNode (server-side) | xmlGetXMLDOMDoc (client-side)
AddItemNode (client-side) | xmlGetXMLDOMDoc (server-side)
XMLHTTP Routines:
dGetRequestXMLAsDict (server-side) | xmlPostFormViaXML (client-side)
xmlGetRequestXML (server-side) | xmlXMLFromForm (client-side)
Error Routines:
SetError (server-side) | sGetScriptError (server-side)
sGetADOError (server-side) | sGetXMLError (client-side)
sGetASPError (server-side) | sGetXMLError (server-side)
sGetErrorById (server-side) | ShowErrorDlg (client-side)
sGetScriptError (client-side) | ShowXMLNodeErrors (client-side)


Business Desk Source Code

Source code for all modules used by a particular Web site is available within the folder (and its sub-folders) associated with the virtual directory of that instance of Business Desk. This source code can serve as a useful model when building a new Business Desk module.

The following table correlates folders within the Business Desk virtual root folder with the various modules available in Business Desk, and with other code that constitutes the Business Desk Framework. As a developer of a new Business Desk module, you may find it useful to analyze which existing modules contain functionality most similar to what you need to construct, and then "steal" code from those modules.

Business Desk Folders Module (Category), or Contains…
\analysis\
 Reports (Analysis)

Completed Reports (Analysis)

\application\
 Data Codes (Orders)
\assets\
 Contains numerous GIF files used in the modules for task buttons, required and invalid icons, and so on.

View the file icon_inventory.htm for a nicely arranged summary of the contents.

\AuthFiles\
 Contains files related to the Authentication Service – not to relevant to Business Desk module development.
\Catalogs\
 Catalog Designer (Catalogs) – Designer sub-folder

Catalog Editor (Catalogs) – Editor sub-folder

\catalogsets\
 Catalog Sets (Catalogs)
\common\
 Contains the shared files used from multiple modules in different folders.
\config\
 Contains the Business Desk configuration files. This includes the master configuration file and the various module configuration files.
\docs\
 Contains the files that constitute the Business Desk help system. Individual help topics are in the "htm" sub-folder.
\exprarch\
 Contains files required for the proper operation of the ExpressionBuilder and QueryBuilder HTCs.
\include\
 Contains various Business Desk global include files intended for use in different kinds of module files. For more information about the files in this folder, see Include Files.

Most module include files should reside within the folder associated with the module.

\marketing\
 Campaign Expressions (Campaigns)

Campaign Manager (Campaigns)

List Manager (Campaigns)

Target Group (Campaigns)

Reference Tables (Campaigns)

\orders\
 Basket Manager (Orders)

Order Status (Orders)

\organizations\
 Organizations (Users)
\productionrefresh\
 Publish (Catalogs)

Publish Transactions (Orders)

Publish Campaigns (Campaigns)

\Profiles\
 Profile Designer (Users)
\segviewer\
 Segment Viewer (Analysis)
\shipping\
 Shipping Methods (Orders)
\tax\
 Tax Rates (Orders)
\users\
 Users (Users)

The following table correlates folders within the Widgets folder within the Commerce Server installation folder with the various HTML Components (HTCs) available for use in Business Desk.

HTC (Widget) Folders Contains source code for…
\editHTC\
 DynamicTable HTC

EditField HTC (and the HTCs for the different types)

EditSheet HTC

ListEditor HTC

\exprbldrHTC\
 ExpressionBuilder HTC

QueryBuilder HTC

\listHTC\
 ListBox HTC

ListSheet HTC

TreeView HTC

\OWC\
 Executable for the Office Web Controls (OWC).
\profile\
 ProfileDesigner HTC - not documented and not intended for use by third parties.


Automating Module Installation

The Commerce Server SDK includes a COM object designed to help automate the installation of new Business Desk modules. This may be useful in situations where a new module needs to be added to a number of different instances of Business Desk. The source files for this COM object are located in the folder "<install folder>\SDK\Samples\Management\Business Desk Installer".

The BizDeskModuleInstall object is capable of being called from both C/C++ code, and automation clients such as Visual Basic.

Note that this object relies on the SiteConfig object to determine the list of applications installed in a site.

The BizDeskModuleInstall object is externally creatable. Create this object using the ProgID CommerceSDK.BizDeskModuleInstall.

The Type Library for this object, once built, will be: Microsoft Commerce Server 2000 SDK BizDesk Module Install Type Library. The DLL name is: BizDeskModuleInstall.dll.

The BizDeskModuleInstall object implements the following four methods:

Init, IsBizDesk, AddModule, RemoveModule

To see a sample of how these methods can be invoked, see the Sample Code section.

These methods can return a number of different custom COM errors, which can be found in the Error Table section at the end of this topic.

Init Method

Use this method to initialize the state of the BizDeskModuleInstall object, establishing the instance of the Business Desk upon which the other methods will operate.

Definition

HRESULT Init(

  BSTR bstrIisVDirName

)

Parameters

bstrIisVDirName

[in] A BSTR containing the name of the virtual directory in Internet Information Services (IIS) that corresponds to the application selected by the user.

IsBizDesk Method

Use this method to determine whether or not the selected IIS application is a Business Desk application. This is accomplished by determining whether the "./config/bizdesk.xml" file exists in the application.

Definition

HRESULT IsBizDesk(

  VARIANT* bRetVal

);

Parameters

bRetVal

[out, retval] The address of a Boolean used to return a value indicating whether or not the IIS virtual directory specified in the Init method contains an instance of the Business Desk. A value of True indicates that it is an instance of the Business Desk. A value of False indicates that it is not an instance of Business Desk.

AddModule Method

Use this method to add a new Business Desk module to the instance of the Business Desk specified in the call to the Init method.

Definition

HRESULT AddModule(

  BSTR bstrCategory,

  BSTR bstrConfigPath,

  VARIANT bOverwrite,

  VARIANT* bSuccess

);

Parameters

bstrCategory

[in] A BSTR containing the name of the category into which the new module should be installed.

bstrConfigPath

[in] A BSTR containing the full path to the module configuration file.

bOverwrite

[in] A Boolean value indicating whether or not to overwrite an existing module configuration file. A value of True indicates that any existing module configuration file will be overwritten. A value of False prevents any overwriting from occurring.

If an existing module configuration file is overwritten, a backup of that file will be placed in a "_backup" folder within the "config" folder.

bSuccess

[out, retval] The address of a Boolean used to return a value indicating whether the method was successful. A value of True indicates success. A value of False indicates a failure, in which case the HRESULT will contain further details.

RemoveModule Method

Use this method to remove the specified module from the instance of the Business Desk specified in the call to the Init method.

Definition

HRESULT RemoveModule(

  BSTR bstrCategory,

  BSTR bstrModulePath,

  VARIANT* bSuccess

);

Parameters

bstrCategory

[in] A BSTR containing the name of the category from which the specified module is to be removed.

If the category is empty after removing the module, the category will also be removed.

bstrModulePath

[in] A BSTR containing the path of the folder containing the files associated with the module being removed. The path must be specified relative to the "config" folder.

bSuccess

[out, retval] The address of a Boolean used to return a value indicating whether the method was successful. A value of True indicates success. A value of False indicates a failure, in which case the HRESULT will contain further details.

Sample Code

The following sample code shows how the methods of the BizDeskModuleInstall object can be invoked. This sample shows the invocation of the AddModule method, with the invocation of the RemoveModule method commented out.

Dim bRet As Boolean
Dim oBizInstall As Object
set oBizInstall = CreateObject ("CommerceSDK.BizDeskModuleInstall")
oBizInstall.Init "adbizdesk"
If oBizInstall.IsBizDesk Then
    bRet = oBizInstall.AddModule("MyCategory", _
                                 "d:\temp\module.xml", True)
    'bRet = oBizInstall.RemoveModule("MyCategory", "module.xml")
End If

Error Table

The following table describes the errors that can be returned from the methods of the BizDeskModuleInstall object.

Constant (32-bit value) | Description
S_OK (00000000) | Returned when a method completes successfully.
E_FILE_EXISTS (80041001) | Returned when the module configuration file already exists in the specified location.
E_NOT_CS_APPLICATION (80041002) | Returned when the specified IIS Application is not a Commerce Server application.
E_FILE_NOT_FOUND (80041003) | Returned when the module configuration file cannot be found.
E_APP_NOT_FOUND (80041004) | Returned with the specified IIS Virtual Directory cannot be found.
E_UNHANDLED (80041005) | Returned when an unhandled error occurs.
E_INVALID_MODULE (80041006) | Returned when the specified module does not exist.
E_INIT_MOD_INSTALL_FIRST (80041007) | Returned if the IsBizDesk, AddModule, or RemoveModule methods are called before the Init method is called.
E_INVALID_CATEGORY_FOR_MODULE (80041008) | Returned when an invalid category is specified.
E_IMPROPER_CS_APP (80041009) | Returned when a configuration inconsistency is detected between Commerce Server and IIS. The BizDeskModuleInstall object must be run locally on the same machine where the physical Business Desk files exist.


Building Pipeline Components

The Microsoft Commerce Server 2000 pipeline is a software infrastructure that executes a sequence of components. Each component is a custom-tailored Component Object Model (COM) object designed to perform operations on some part of an OrderForm or Dictionary. The pipeline coordinates the interaction of pipeline components by passing the OrderForm or Dictionary object from one component to another.

You can use pipelines to model many linear processes. The two main processes modeled in Commerce Server are order processing, which is handled by the Order Processing pipelines (OPP), and content selection, which is handled by the Content Selection Framework (CSF) pipelines. The OPP automates order processing in a business-to-consumer scenario. The CSF pipelines automate the selection of advertisements and discounts.

Commerce Server includes a set of components that can be combined into a pipeline to support either architecture. In addition, you can create your own components to extend the capabilities of the pipeline architecture, as described in this section.

This section contains:

  • About Pipeline Components. Describes the basic structure of pipeline components and introduces the OrderForm and Dictionary objects on which pipeline components operate.

  • Creating Pipeline Components Using Visual Basic. Explains how to create and build a pipeline component using the Visual Basic Pipeline Component Wizard, as well as how to customize your components using Microsoft Visual Basic.

  • Creating Pipeline Components Using the Active Template Library (ATL). Explains how to create, build, and register a pipeline component using the ATL Pipeline Component Wizard, as well as how to customize your components using C++.

  • MinMaxShip Sample Pipeline Component. Describes the design of the MinMaxShip sample pipeline component and explains how to implement it in Commerce Server pipelines.

Notes

  • Commerce Server includes wizards for creating pipeline components using Microsoft Visual Basic and Microsoft Visual C++. For the most current sample code for the components, see the ATL Pipeline Component Wizard, the Visual Basic Pipeline Component Wizard, and the complete sample code in the Programmer's Reference.

  • You must have Visual C++ version 6.0 or Visual Basic version 6.0 or higher installed on your computer in order to use the ATL Pipeline Component Wizard.

See Also

Programmer's Reference

Working with Pipelines

Order Processing Pipelines

OrderForm Object

Dictionary Object


About Pipeline Components

A pipeline component is a Component Object Model (COM) server object that implements the IPipelineComponent interface. The following is the definition of this interface as it appears in the Pipecomp.idl file:

    interface IPipelineComponent : IUnknown
    {
        import "oaidl.idl";

        HRESULT Execute(
                    [in]            IDispatch*  pdispOrder,
                    [in]            IDispatch*  pdispContext,
                    [in]            LONG        lFlags,
                    [out,retval]    LONG*       plErrorLevel
                );

        //
        // By default, a pipeline is in "execution mode", this call is
        // used to prepare the pipeline for "design mode" (fEnable ==
        //  TRUE) or to go to design mode (fEnable = FALSE).
        //

        HRESULT EnableDesign( [in]    BOOL fEnable );

    };

When the pipeline creates an instance of a component, it requests an interface pointer to the IPipelineComponent implementation of the component, then uses this pointer to invoke IPipelineComponent::Execute method.

The IPipelineComponent is the only interface that a component must implement to function within the pipeline. However, to enhance the usability of a component, or to take advantage of the transaction capabilities of COM+, you may also design your component to implement one or more of the following interfaces:

  • IDispatch. Implementing this interface is optional. However, it makes it possible for clients to access the capabilities of your component from macro languages, such as Visual Basic Scripting Edition (VBScript) or Visual Basic.

  • IPipelineComponentAdmin. This interface is a component configuration interface. If your component requires configuration at design time, then you should implement this interface. The IPipelineComponentAdmin interface defines the GetConfigData and SetConfigData methods, to which the caller passes a Dictionary object. The GetConfigData and SetConfigData methods write or read this Dictionary object to retrieve or set configuration data on the component.

  • IPipelineComponentDescription. When you implement the this interface, you identify to the Pipeline Editor the keys and values in the OrderForm object that your component reads and writes, as well as the pipeline context values that your component uses. The Pipeline Editor displays these keys when the user selects the Values Read and Written tab for the component.

  • IPersistStreamInit. This interface allows components written in C++ to save data to the configuration file. Visual Basic components cannot implement this interface. For Visual Basic components, the IPipelineComponentAdmin interface is used to get and save data to and from the configuration file.

  • ISpecifyPropertyPages. This interface allows your component to specify property pages for use in the Pipeline Editor.

See Also

IPipelineComponent Interface

IPipelineComponent::Execute

IPipelineComponentAdmin Interface

IPipelineComponentDescription Interface

IPersistStreamInit Interface

ISpecifyPropertyPages Interface

IPipelineComponentAdmin::GetConfigData

IPipelineComponentAdmin::SetConfigData


Creating Pipeline Components Using Visual Basic

By creating your own components you can customize the pipeline your customers use. If your business requires these custom components, you can create them using the Visual Basic Pipeline Component Wizard and Microsoft Visual Basic version 6.0 or higher, and register them using the Pipeline Component Registration Tool.

You can write pipeline components in Visual Basic. However, Visual Basic components will, in general, be slower than the same component written in Microsoft Visual C++. For more information about additional limitations to components written in Visual Basic, see Special Considerations for Visual Basic Pipeline Components.

This section contains:

  • Using the Visual Basic Pipeline Component Wizard

  • Implementing the IPipelineComponent Interface

  • Persisting Data

  • Using the Pipeline Component Registration Tool

  • Special Considerations for Visual Basic Pipeline Components


Using the Visual Basic Pipeline Component Wizard

The Visual Basic Pipeline Component Wizard gives site developers point-and-click access to creating a framework code base for creating pipeline components. This wizard is provided as a new project item in the Visual Basic projects menu, and generates code based on responses provided by the user to a series of questions. Previous knowledge of the Visual Basic language is required to complete this wizard.

This section contains:

  • Installing the Visual Basic Pipeline Component Wizard

  • Running the Visual Basic Pipeline Component Wizard

See Also

Implementing the IPipelineComponent Interface

Persisting Data

Using the Pipeline Component Registration Tool

Special Considerations for Visual Basic Pipeline Components


Installing the Visual Basic Pipeline Component Wizard

Registering the PipelineCompWizard.dll causes a new project item to be installed in Visual Basic.

To register the PipelineCompWizard.DLL

  1. Click Start, and then click Run.

  2. In the Run dialog box, type regsvr32 followed by the path to the Visual Basic Pipeline Component Wizard. For example, type regsvr32 "C:\Program Files\Microsoft Commerce Server\SDK\Tools\VB Pipe Wizard\PipelineCompWizard.dll", and then click OK.

The RegSvr32 dialog box appears indicating success in registering the PipelineCompWizard.dll.

See Also

Running the Visual Basic Pipeline Component Wizard


Running the Visual Basic Pipeline Component Wizard

The Visual Basic Pipeline Component Wizard enables you to create a framework from which you can build custom pipeline components. The Visual Basic Pipeline Component Wizard configures the pipeline component to the specifications set while running the wizard.

To run the Visual Basic Pipeline Component Wizard

To register the DLL components

To run the Visual Basic Pipeline Component Wizard

  1. Click Start, point to Programs, and then click Microsoft Visual Basic 6.0.

    Or, if you have Microsoft Visual Studio 6.0 installed, point to Microsoft Visual Studio 6.0, and then click Microsoft Visual Basic 6.0.

  2. To open the wizard, on the File menu, click New Project.

  3. In the New Project dialog box, double-click Pipeline Component Wizard.

    The Pipeline Component Wizard - Introduction (Step 1 of 7) dialog box appears.

  4. Click Next to begin using the wizard.

  5. In the Pipeline Component Wizard - Transaction Support (Step 2 of 7) dialog box, click Yes to support transacted pipelines or click No if you want to use non-transacted pipelines, and then click Next.

  6. In the Pipeline Component Wizard - Shipping Support (Step 3 of 7) dialog box, click Yes to support the new multiple-shipping architecture used in Commerce Server 2000 or click No if you want to create a component that does not process shipments. (If you are creating a Shipping or Tax component, click Yes.) Click Next.

  7. In the Pipeline Component Wizard - Component Properties (Step 4 of 7) dialog box, click Add.

  8. In the Add Property dialog box, in the Property name box, type the name of the property you want to add.

  9. In the Data type box, select the data type for the property from the drop-down list, and then click OK.

    The property you added appears in the Properties box in the Pipeline Component Wizard - Component Properties (Step 4 of 7) dialog box.

  10. If you want to remove any unwanted properties, in the Properties box, select the property you want to remove, and then click Remove. To add additional properties complete steps 7, 8, and 9 for each additional property.

  11. Click Next.

  12. In the Pipeline Component Wizard - Project, Class, and Form Names (Step 5 of 7) dialog box, do the following:
    Use this | To do this
    Project Name (*.vbp) | Type a name for the project or leave the default value.
    Pipeline Component Class (*.cls) | Type a component class name for the project or leave the default value.
    Pipeline Component UI Class (*.cls) | Type a component UI class name or leave the default value.
    Pipeline Component UI Form (*.frm) | Type a component UI form name or leave the default value.

    These values will be the names for the project, the form, and the classes created by the wizard.

  13. Click Next.

  14. In the Pipeline Component Wizard - Select Directory (Step 6 of 7) dialog box, select the location to store the files the wizard will generate.

  15. In the Pipeline Component Wizard - Finished! (Step 7 of 7) dialog box, click Finish to build your component based on the information you provided in the wizard.

Three new component pages appear in the Visual Basic project window: the class module code corresponding to the Pipeline component, the class module corresponding to the Pipeline UI component, and a form corresponding to the Pipeline UI component. Before registering your component for stage affinity you must register the DLL components at the command line.

To register the DLL components

  1. Click Start, and then click Run.

  2. In the Run dialog box, type regsvr32 followed by the path to the pipeline component. For example, type regsvr32 "C:\Program Files\Microsoft Commerce Server\<project name>.dll", and then click OK.

    The RegSvr32 dialog box appears indicating success in registering the .dll file.

  3. Repeat Step 2 for the component UI. For example, type regsvr32, "C:\Program Files\Microsoft Commerce Server\<project name>UI.dll" and then click OK.

Your new component is now registered.

All custom components written in Visual Basic must be registered for stage affinity using the Pipeline Component Registration Tool. For more information about registering components, see Using the Pipeline Component Registration Tool.


Implementing the IPipelineComponent Interface

All pipeline components must implement the IPipelineComponent interface to function within the Pipeline Editor. If you have created your pipeline component using the Visual Basic Pipeline Component Wizard, your component supports this interface.

In a Microsoft ActiveX dynamic-link library (DLL), the pipeline component is a class in the DLL that implements one or more of the pipeline component interfaces. You add a reference to the type library defining the interfaces, add the appropriate implementation statements, and write the implementation code. This is done for you if you used the Visual Basic Pipeline Component Wizard.

For detailed instructions about implementing COM interfaces in Visual Basic, see "Creating and Implementing an Interface" and "Implementing and Using Standard Interfaces" in the Visual Basic Help.

All pipeline component interfaces are described in a type library named Pipecomplib.tlb. If you look at the code created by the Visual Basic Pipeline Component Wizard in Running the Visual Basic Pipeline Component Wizard, you will see that the project includes a reference to this library.

The code for the class begins with the following lines:

Implements IPersistDictionary
Implements IPipelineComponent
Implements ISpecifyPipelineComponentUI
Implements IPipelineComponentDescription
Implements IPipelineComponentAdmin

This component implements four interfaces in addition to the IPipelineComponent interface. For more information about the other interfaces implemented by the Visual Basic Pipeline Component Wizard, see Pipeline Component Interfaces.

Further down in the code, you can see the code implementing the two methods of the IPipelineComponent interface, the EnableDesign method, and the Execute method.

The code for the EnableDesign method is:

Private Sub IPipelineComponent_EnableDesign(ByVal fEnable As Long)
End Sub

The EnableDesign method is used by the Pipeline Editor to tell the component when it is being used in design mode and when it is being executed. No changes need to be made to this code.

The Execute method contains the most of the functionality of the component. It determines whether or not there was an error, and if the pipeline can continue to execute. The following outline of the Execute method is straightforward:

' Execute() -- This function gets called when the pipeline runs.
' Return 1 for success, 2 for user warnings, 3 for error.
Private Function IPipelineComponent_Execute(ByVal objOrderForm As Object, ByVal objContext As Object, ByVal 1Flags As Long) As Long

      ' Initialization of variables

      IPipelineComponent_Execute = 1

      ' The implementation of the component appears here.

End Function

Note

  • Although it might appear that the dictionaries are passed by value, that is not the case. What is passed by value is a reference to the dictionary — its address (not the contents of the dictionary). A reference passed by value is basically the same as the object passed by reference.

The Execute method is a function that returns a Long. It returns one of three values: 1 for success, 2 for user warnings, and 3 for an error that should stop execution of the pipeline.

For detailed instructions about implementing COM interfaces in Visual Basic, see "Creating and Implementing an Interface" and "Implementing and Using Standard Interfaces" in the Visual Basic Help.

Using Commerce Server Objects

Pipeline components written in Visual Basic can use Commerce Server objects. The project for a component created using the Visual Basic Pipeline Component Wizard includes a reference to the Microsoft Commerce 2000 Core Components Type Library and creates variables of the CDictionary type and assigns the dictionaries passed to the Execute method to the variables:

 ' Initialize the PipeCtx dictionary as
 ' CDictionary variables
    Dim objPipeCtx As CDictionary
    Set objPipeCtx = objContext

Note

  • The dictionary has a type library name of CDictionary and a ProgID of Commerce.Dictionary.

For example, if your component includes a reference to the Microsoft Commerce 2000 Core Components Type Library, you can take advantage of early binding, and strongly type your variables in the declaration of the variables:

Dim dictLocalDictionary As Cdictionary
Set dictLocalDictionary = New CDictionary
dictLocalDictionary("Nickel") = ("what is nickel")

See Object Reference for a complete list of objects in Commerce Server and for details about their use.

See Also

Pipeline Component Interfaces

Using the Visual Basic Pipeline Component Wizard

Persisting Data

Using the Pipeline Component Registration Tool

Special Considerations for Visual Basic Pipeline Components


Persisting Data

Visual Basic pipeline components can use the IPersistDictionary interface to implement persistence. The Pipeline Editor and pipelines themselves support this interface for loading and saving. The IPersistDictionary interface is used to persist data for a pipeline component. The Pipeline Editor uses the IPersistDictionary interface to get configuration values from the component and save them in the pipeline configuration file through the Save method.

Similarly, the pipeline passes a dictionary loaded with the previously saved values to the component. Because the Pipeline Editor handles the storage of the data, the component needs only to manipulate a dictionary.

The following table describes the methods of the IPersistDictionary interface.

Method | Description
GetProgID | Returns the ProgID of the component.
IsDirty | Returns a Boolean value of True if the values have changed since they were last saved.
InitNew | Called to initialize the object.
Load | Loads the Dictionary object with the saved values.
Save | Saves the values in the Dictionary object.

The InitNew method initializes the default values for a new instance of the object. In the code created by the Visual Basic Pipeline Component Wizard in Running the Visual Basic Pipeline Component Wizard, the method is called by the Pipeline Editor:

Private Sub IPersistDictionary_InitNew()
    FIsDirty = False
End Sub

The IsDirty method checks whether the values of an object have changed since they were last saved. It returns the value of the IsDirty flag of the object. The flag is cleared by the object in its implementation of the IPersistDictionary::Save method.

The GetProgID method must return the ProgID of the object. In the example, this is a constant that matches the ProgID under which the object is registered. By default, in an ActiveX DLL this is the project name followed by a period and the class name. For example:

Private Function IPersistDictionary_GetProgID() As String
    IPersistDictionary_GetProgID = "MyProject.ClassName"
End Function
Private Function IPersistDictionary_IsDirty() As Long
    IPersistDictionary_IsDirty = fIsDirty
End Function

The IPersistDictionary interface provides a convenient way for pipeline components housed in ActiveX DLLs to save configuration values. If a component is implemented as an ActiveX Control, the component can use the control property bag to save the configuration values.

Note

  • Although you can create your pipeline component as a Visual Basic ActiveX control and use the property page of the control as the configuration tab in the Pipeline Editor, this is not recommended.

See Also

IPersistDictionary Interface

Using the Visual Basic Pipeline Component Wizard

Implementing the IPipelineComponent Interface

Using the Pipeline Component Registration Tool

Special Considerations for Visual Basic Pipeline Components


Using the Pipeline Component Registration Tool

Commerce Server 2000 includes the Pipeline Component Registration Tool for efficient registration of pipeline components written in Visual Basic. Typically, registration would be done using the DllRegisterServer entry-point routine, as is done in C++. However, because Visual Basic developers cannot export functions from their components, they usually have to find a way to register the components themselves, which can be a difficult task.

The Pipeline Component Registration Tool simplifies the registration process by registering pipeline components for stage affinity and then exporting the data to a Registry Script (.reg) file so it can be deployed on other servers.

To open the Pipeline Component Registration Tool

To register your pipeline component

To open the Pipeline Component Registration Tool

  1. Click Start, and then click Run.

  2. In the Run dialog box, type the path to your local installation of the PipeReg.exe file. For example, C:\Program Files\Microsoft Commerce Server\SDK\Tools\Registration Tool, and then double-click PipeReg.

The Pipeline Component Registration Wizard appears. You can now begin registering your component(s).

To register your pipeline component(s)

  1. In the Pipeline Component Registration Wizard (Step 1 of 3) dialog box, do the following:
    Use this | To do this
    Select component by ProgID | Type the ProgID for the component you want to register in the ProgID box. This registers a single component.
    Select component Type Library | Type the path to the Type Library (.tlb or .dll) for the component(s) you want to register in the Path box. This registers some or all of the components in the indicated type library.

  2. Click Next.

  3. If you selected the option Select component by ProgID, in the Pipeline Component Registration Wizard (Step 2 of 3) dialog box or if you selected Select component Type Library and selected a type library with only a single component, do the following:
    Use this | To do this
    Available Categories | Select from the available list of pipeline stages in which you want to make your component available, and then click the right arrow button to move the pipeline stages to the Selected Categories box.
    Selected Categories | Select from the available list of pipeline stages that you do not want this component to appear in, and then click the left arrow button to remove those stages.
    Add Custom Stage | Click to add a custom stage for this component. In the Add Custom Stage dialog box, type the custom stage label in the Label box, type the GUID for the custom stage in the GUID box, and then click OK.

    Click Next.

  4. If you selected the option Select component Type Library and selected a type library with more than one component, in the Pipeline Component Registration Wizard [Select Components] dialog box select the components you would like to register, and then click Next.

    Return to Step 3 for each component you selected.

  5. In the Pipeline Component Wizard [Registration] dialog box, do one of the following:
    Use this | To do this
    Register components only | Click to update the Implemented Categories of the component for the corresponding registry hive. This option is best for the workstation of a site developer, where components and stages may change on a regular basis.
    Export registration data | Click to export the registry information to a registry script. In the Export path box, select the path to which you want the registry script exported.
    Register and export data | Click to register and export the registration data to a registry script. In the Export path box, select the path to which you want the registry script exported.

    Click Next.

  6. In the Pipeline Component Registration Wizard [Finished] dialog box, review the information to make sure the correct components were loaded and exported to the correct path.

  7. To close the Pipeline Component Registration Wizard, click Close.

The Pipeline Component Registration Wizard adds keys under the Implemented Categories entry in the registry to indicate that it is a pipeline component and to indicate which stages the component may appear in. The Implemented Categories entry can be found at \HKEY_CLASSES_ROOT\CLSID\component_classid\implemented categories\stage_clsid key within the Microsoft Windows NT Registry, where stage_class_id is the GUID of the stage with which the component will have an affinity, and component_class_id is the class ID of the component itself. See the file pipe_stages.h in the Commerce Server SDK for the GUID values for different pipeline stages.

See Also

Using the Visual Basic Pipeline Component Wizard

Implementing the IPipelineComponent Interface

Persisting Data

Special Considerations for Visual Basic Pipeline Components


Special Considerations for Visual Basic Pipeline Components

Visual Basic supports the creation of apartment-threaded components, but does not support the creation of free-threaded components. Consequently, if you use Visual Basic to create components for either the Order Processing pipeline (OPP) or Content Selection Framework (CSF) pipeline architectures, you should be aware of certain limitations.

If you include the component in a pipeline you load using the OrderPipeline object, and if you make this object globally available, your component will work as expected. This is because the OrderPipeline object checks the threading model of each component at load-time to determine how to marshal the data of that component.

For performance reasons, however, the MtsOrderPipeline or MtsTxOrderPipeline objects do not perform this checking because these objects are generally created on a per-page basis. The MtsOrderPipeline or MtsTxOrderPipeline objects that you create on a per-page basis have no bearing on the proper functioning of Visual Basic pipeline components.

However, including such components in an MtsOrderPipeline or MtsTxOrderPipeline object that you make globally available (through the Application object, for example) is unsupported behavior. If you include a Visual Basic component in a globally available pipeline object instance, you must use the OrderPipeline object to load and execute that pipeline.

Always mark Visual Basic objects as Retain in Memory to keep the reference count above zero.

To mark Visual Basic objects as Retain in Memory

  1. In Visual Basic, on the Project menu, click <project name> Properties.

  2. On the General tab, select the Unattended Execution and Retained In Memory boxes.

See Also

Using the Visual Basic Pipeline Component Wizard

Implementing the IPipelineComponent Interface

Persisting Data

Using the Pipeline Component Registration Tool


Creating Pipeline Components Using the Active Template Library (ATL)

The ATL Pipeline Component Wizard consists of a group of files that you add to your Microsoft Visual C++ installation to automate the creation of Commerce Server 2000 pipeline components. The ATL Pipeline Component Wizard creates the object definition and implementation files. These files contain the function prototypes for all of the interfaces that you need to implement to create a fully functional pipeline component. In addition, the ATL Pipeline Component Wizard creates a property page for your project, in which you add the controls through which users set component properties.

This section contains:

  • Active Template Library

  • Building the ATL Pipeline Component Wizard

  • Creating a Project

  • Adding an Object

  • Deciding Which Interface to Expose

  • Enhancing Component Usability

  • Implementing the IPipelineComponent Interface

  • Registering the ATL Component


Active Template Library

The Active Template Library (ATL) is a collection of C++ templates included in Microsoft Visual C++ version 4.0 and greater. This template library is intended specifically to facilitate the creation of Component Object Model (COM) objects.

Although you can create a pipeline component using any development environment that supports the creation of COM components, the use of the ATL is recommended because it creates small, fast code. COM components created using the ATL are smaller and faster than other approaches to component creation, including approaches supported by Visual C++. Although you can easily create COM components using the Microsoft Foundation Classes (MFC) library, you incur the significant memory overhead that is occasioned by using a large class library.

For information about the Active Template Library, see the ATL tutorial, which is included with Microsoft Visual C++.

See Also

Building the ATL Pipeline Component Wizard

Enhancing Component Usability

Registering the ATL Component

MinMaxShip Sample Pipeline Component


Building the ATL Pipeline Component Wizard

Before using the ATL Pipeline Component Wizard, you must build it with the CommerceDLG.dll file on your local computer, and then copy specific files to the correct directories on your computer. This is because the ATL Pipeline Component Wizard functions within the Microsoft Visual C++ program.

To build the CommerceDLG.dll file

  1. Click Start, and then click Run.

  2. In the Run dialog box, type regsvr32 followed by the path to the Visual Basic Pipeline Component Wizard. For example, type regsvr32 "C:\Program Files\Microsoft Commerce Server\SDK\Tools\ATL Pipe Wizard\CommerceDLG.dll", and then click OK.

The RegSvr32 dialog box appears indicating success in building the CommerceDLG.dll file.

See Also

Creating a Project

Adding an Object

Deciding Which Interface to Expose

Enhancing Component Usability

Implementing the IPipelineComponent Interface

Registering the ATL Component

Active Template Library

MinMaxShip Sample Pipeline Component


Creating a Project

To create a custom component using the ATL Pipeline Component Wizard, you must first create an active project. To create a project in Visual C++ version 6.0, you use the ATL COM App Wizard.

To create a project in Visual C++

  1. Click Start, point to Programs, point to Microsoft Visual C++, and then click Visual C++.

  2. On the File menu, click New, and then select the Projects tab.

  3. On the Projects tab, select ATL COM App Wizard, and then do the following:
    Use this | To do this
    Project name | Type a name for the project.
    Location | Type the path to the location where the project will be saved.
    Create new workspace | Select to create a new skeleton project.
    Add to current workspace | Select to add on to an existing project.
    Platforms | Keep the default, which is WIN32.

  4. Click OK.

  5. In the ATL COM App Wizard - Step 1 of 1 dialog box, do the following:
    Use this | To do this
    Server Type Select one of the following:
    • Dynamic Link Library (DLL)

    • Executable (EXE)

    • Service (EXE)

    Note

    • If you are creating a modified ASP component, leave the Server Type as DLL because a control must be an in-process server.
    Allow merging of proxy/stub code | Specify that proxy/stub code be merged into your main project (available for DLL projects only). By default, the proxy/stub marshaling code is contained in a separate DLL.
    Support MFC | Specify that your object includes Microsoft Foundation Classes (MFC) support, and the MFC libraries will be attached to your code (available for DLL projects only).
    Support MTS | Specify the support for Microsoft Transaction Server (MTS) by adjusting the project build settings.

  6. Click Finish.

    The New Project Information dialog box appears, which lists the files that will be created for your project. These files and their descriptions are listed in the following table.

    File extension | Description
    .dsp | File that contains the project settings.
    .cpp File that contains the implementation of the following methods:
    • DllMain

    • DllCanUnloadNow

    • DllGetClassObject

    • DllRegisterServer

    • DllUnregisterServer

    This file also contains an object map, which is a list of the ATL objects in your project. This is initially blank, because you have not yet created an object.
    .idl | An interface definition language file, which describes the interfaces specific to your objects.
    .mk | A make file that can be used to build a proxy and stub DLL.

  7. Click OK.

    The project you created appears in the Visual C++ Workspace window.

  8. To save your workspace, from the File menu, click Save Workspace.

See Also

Adding an Object

Deciding Which Interface to Expose

Enhancing Component Usability

Implementing the IPipelineComponent Interface

Registering the ATL Component

Active Template Library

MinMaxShip Sample Pipeline Component


Adding an Object

After you create your project, you compile the files that Microsoft Visual C++ created for you into a dynamic-link library (DLL). To make this DLL useful, however, you must add support for an object that implements the appropriate pipeline interfaces.

When you use the ATL Pipeline Component Wizard to add an object to your project, the IPipelineComponent interface is implemented by default. In addition, you can choose to implement the ISpecifyPropertyPages, IPersistStreamInit, and IPipelineComponentDescription interfaces. For more information about which interfaces to implement, see Pipeline Component Interfaces.

Note

  • You must install the ATL Pipeline Component Wizard and create a project before starting the following procedure. For more information about installing the wizard, see Installing the ATL Pipeline Component Wizard. For more information about creating a project, see Creating a Project.

To add an object to your project

  1. In your project in Visual C++, on the Insert menu, click New ATL Object.

  2. In the ATL Object Wizard dialog box, do the following:
    Use this | To do this
    Category | Select Objects to add a new pipeline component.
    Objects | Select Commerce Component.

  3. Click Next.

  4. In the ATL Object Wizard Properties box, on the Names tab, do the following:
    Use this | To do this
    C++ Short Name | Type the name of your component.
    C++ Class | Type the class name to implement the control, or leave the default value.
    C++ .H File | Type the name of the .h file, or leave the default value.
    C++ .CPP File | Type the name of the .cpp file, or leave the default value.
    COM CoClass | Type the name of the component class for the object, or leave the default value.
    COM Interface | Type the name of the interface on which the component will implement its custom properties, or leave the default value.
    COM Type | Type the description for the control, or leave the default value.
    COM ProgID | Type the name of the ProgID, or leave the default value.

    Important

    • Do not click OK until you configure the Commerce Component tab.
  5. Click the Commerce Component tab. (This tab displays a list of the optional interfaces that you can implement on a Commerce Server pipeline component.)

  6. In the ATL Object Wizard Properties dialog box, on the Commerce Component tab, do the following:
    Use this | To do this
    ISpecifyPropertyPages | Select if your component uses property pages to allow users to set component properties.
    IPersistStreamInit | Select if your component saves and loads its properties to and from a stream.
    IPipelineComponentDescription | Select if you want your component users to identify the OrderForm object or pipe context values that your component reads and writes.

  7. Click OK.

The ATL Object Wizard creates the definition and implementation files that implement the necessary pipeline interfaces, and adds these files to the project.

In addition, the ATL Object Wizard creates a stub implementation for the object interface, on which you implement the properties for your component.

Note

  • The approach to adding properties described in this section assumes that you do not intend to implement the IPipelineComponentAdmin interface. However, Commerce Server defines this interface as an alternative way to implement properties on an object.

See Also

Deciding Which Interface to Expose

Enhancing Component Usability

Implementing the IPipelineComponent Interface

Registering the ATL Component

Active Template Library

MinMaxShip Sample Pipeline Component


Deciding Which Interface to Expose

Before a component can be configured through a macro language such as Microsoft Visual Basic Scripting Edition (VBScript), it must implement the IDispatch interface. Because any interface that you create can inherit from the IDispatch interface, you decide which of the interfaces that you implement will use the IDispatch interface to expose the properties and methods of your component.

Several options are available. When you add an object to your project, Microsoft Visual C++ adds an interface to the object definition that appears in the interface definition language (IDL) file for the project. By default, the interface that Visual C++ adds inherits from the IDispatch interface.

You can use this interface, or you can implement the IPipelineComponentAdmin interface. This interface is defined by Commerce Server 2000 specifically to enable component writers to expose their component properties. The IPipelineComponentAdmin interface defines two methods: GetConfigData and SetConfigData. These methods take a Dictionary object as a parameter, and read or write to this Dictionary object to retrieve or set the values of the properties of the component.

The options described in the preceding paragraphs are mutually exclusive; you cannot implement two IDispatch interfaces on a single object and make both available to Active Server Pages (ASP) clients.

The following lists the advantages of using the Visual C++ user interface to get an IDispatch implementation:

  • Implementing IDispatch::Invoke is done automatically. By adding properties and methods through the Visual C++ user interface, this work is done for you.

  • As you add properties and methods to your object, Visual C++ automatically adds the appropriate entries to the project IDL, header, and implementation files. Because the added interface is the default interface for the object, a VBScript client that creates an instance of your object using the ProgID gets this interface, and can set the methods and invoke the properties implemented in it.

According to the rules for Component Object Models (COM), the advantage of implementing the IPipelineComponentAdmin interface is that after an interface is published, it cannot be changed. By adding properties to a published object, you necessarily modify the dispatched interface, running the risk that you will break the client code of existing users. Because implementing the IPipelineComponentAdmin interface does not require that your component definition be modified to add support for new properties, your component can evolve over time without requiring the publication of a new interface. The IPipelineComponentAdmin interface also allows for simple persistence, because the dictionary supports persistence. And the dictionary exposed through the IPipelineComponentAdmin interface supports enumeration of property names.

The IPipelineComponentAdmin interface is required if you are implementing a shipping component that requires configuration.

Important

  • Shipping Components should expose the IPipelineComponentAdmin::GetConfigData and IPipelineComponentAdmin::SetConfigData methods from the IDispatch interface implementation, because the Commerce Server Business Desk module(s) that manage these components must be able to call these methods from a late-bound (Active Server Pages) environment.

See Also

Pipeline Component Interfaces

Enhancing Component Usability

Implementing the IPipelineComponent Interface

Registering the ATL Component

Active Template Library

MinMaxShip Sample Pipeline Component


Enhancing Component Usability

To enhance the usability of your component, you may choose to implement the optional IPipelineComponentDescription interface. This interface defines methods that return SAFEARRAY variables that identify the pipe context elements that a component reads, as well as the OrderForm or Dictionary object elements that a component reads and writes.

When a user activates the property pages for your component through the Pipeline Editor, the Pipeline Editor checks to see if your component implements the IPipelineComponentDescription interface. If it does, the Pipeline Editor invokes your IPipelineComponentDescription method implementations and displays the values that the component reads and writes in a property page.

When you run the ATL Pipeline Component Wizard, the wizard adds a reference to the IPipelineComponentDescription interface to your derivation list, and adds the IPipelineComponentDescription interface signatures to the class definition. For example:

// IPipelineComponentDescription
    STDMETHOD (ContextValuesRead)(VARIANT *pVar);
    STDMETHOD (ValuesRead)(VARIANT *pVar);
    STDMETHOD (ValuesWritten)(VARIANT *pVar);

In addition, the ATL Pipeline Component Wizard adds stub implementations to implement files. The code the wizard adds is:

//
// IPipelineComponentDescription Methods
//
STDMETHODIMP CSampleComponent::ContextValuesRead(VARIANT *pVarRead)
{
    // TODO: Add your own values to the array
    int cEntries = 1;
    // Allocate the SAFEARRAY of VARIANTs
    SAFEARRAY*    psa = SafeArrayCreateVector(VT_VARIANT, 0, cEntries);
    // Populate the SAFEARRAY of VARIANTs
    VARIANT* pvarT = (VARIANT*)psa->pvData;
    V_BSTR(pvarT) = SysAllocString(L"Example Context Value Read");
    V_VT(pvarT) = VT_BSTR;
    // Set up the return value to point to the SAFEARRAY
    V_VT(pVarRead) = VT_ARRAY | VT_VARIANT;
    V_ARRAY(pVarRead) = psa;
    return S_OK;
}

STDMETHODIMP CSampleComponent::ValuesRead(VARIANT *pVarRead)
{
    // TODO: Add your own values to the array
    int cEntries = 1;
    // Allocate the SAFEARRAY of VARIANTs
    SAFEARRAY*    psa = SafeArrayCreateVector(VT_VARIANT, 0, cEntries);
    // Populate the SAFEARRAY of VARIANTs
    VARIANT* pvarT = (VARIANT*)psa->pvData;
    V_BSTR(pvarT) = SysAllocString(L"Example Value Read");
    V_VT(pvarT) = VT_BSTR;
    // Set up the return value to point to the SAFEARRAY
    V_VT(pVarRead) = VT_ARRAY | VT_VARIANT;
    V_ARRAY(pVarRead) = psa;

    return S_OK;
}

STDMETHODIMP CSampleComponent::ValuesWritten(VARIANT *pVarWritten)
{
    // TODO: Add your own values to the array
    int cEntries = 1;
    // Allocate the SAFEARRAY of VARIANTs
    SAFEARRAY*    psa = SafeArrayCreateVector(VT_VARIANT, 0, cEntries);
    // Populate the SAFEARRAY VARIANTs
    VARIANT* pvarT = (VARIANT*)psa->pvData;
    V_BSTR(pvarT) = SysAllocString(L"Example Value Written");
    V_VT(pvarT) = VT_BSTR;
    // Set up the return value to point to the SAFEARRAY
    V_VT(pVarWritten) = VT_ARRAY | VT_VARIANT;
    V_ARRAY(pVarWritten) = psa;
    return S_OK;
}

This code contains the basic instructions for implementing the interface.

Note

  • Each of the methods in the IPipelineComponentDescription interface must return an array. If there are no association values, the IPipelineComponentDescription interface should return an empty array.

See Also

Deciding Which Interface to Expose

Implementing the IPipelineComponent Interface

Registering the ATL Component

Active Template Library

MinMaxShip Sample Pipeline Component


Implementing the IPipelineComponent Interface

All pipeline components must implement the IPipelineComponent interface. This interface is defined as follows:

// IPipelineComponent

STDMETHOD (Execute) (
    IDispatch*  pdispOrder,
    IDispatch*  pdispContext,
    LONG        lFlags,
    LONG*       plErrorLevel);

STDMETHOD (EnableDesign) (BOOL fEnable);

When the pipeline creates an instance of a component, it requests an interface pointer on the IPipelineComponent interface of the component, and then uses that pointer to call the Execute method of the component. The pipeline passes the component an IDispatch interface pointer on the OrderForm object being passed through the pipeline, and an IDispatch interface pointer on the pipe context of the site. The pipe context is a Dictionary object that contains references to various contextual pieces of information for the site, such as connection strings and cache references.

The IPipelineComponent interface is among the interfaces for which the ATL Pipeline Component Wizard adds method definitions and implementation stubs when you add an object to your project. To implement the IPipelineComponent::Execute method for your component, open the .cpp file, and modify the default implementation provided by the ATL Pipeline Component Wizard.

See Also

Deciding Which Interface to Expose

Enhancing Component Usability

Registering the ATL Component

Active Template Library

MinMaxShip Sample Pipeline Component


Registering the ATL Component

Pipeline component registration involves identifying the component as a pipeline component, identifying the stage or stages with which the component has an affinity, and optionally registering its name and threading model.

A globally unique identifier (GUID) identifies each stage in the pipeline. GUIDs are defined in the Pipe_stages.h file, which you include in the implementation file in which you are registering a component.

To identify the stage or stages with which a component has an affinity, you write the class ID of the new component to the \HKEY_CLASSES_ROOT\CLSID\component_classid\implemented categories\stage_clsid registry key within the Microsoft Windows NT Registry, where stage_class_id is the GUID of the stage with which the component will have an affinity, and where component_class_id is the class ID of the component itself.

The code with which you register your component should be invoked in the DLLRegisterServer routine that is created for you when you create the component project in Microsoft Visual C++.

The ATL Pipeline Component Wizard creates a skeleton DllRegisterServer routine for the component housing. Although this will register the component, several more keys need to be added to the registry so that the Pipeline Editor displays the component properly.

The Pipeline Editor looks under the Implemented Keys category in the registry to see if the object is a pipeline component and, if so, which stages it may appear in. The function RegisterCATID, provided in the Computil.cpp file, makes this registration easier. In addition, the name displayed for the component comes from the AuxUserType\2 key for the component. The RegisterName function handles this registration. The following is the complete DllRegisterServer routine:

STDAPI DllRegisterServer(void)
{
    HRESULT hr = S_OK;

    hr = _Module.RegisterServer(TRUE);

    if(FAILED(hr)) return hr;

    hr = RegisterCATID(CLSID_MinMaxShipping,
                       CATID_MSCSPIPELINE_COMPONENT);

    if(FAILED(hr)) return hr;

    hr = RegisterCATID(CLSID_MinMaxShipping,
                       CATID_MSCSPIPELINE_SHIPPING);

    if(FAILED(hr)) return hr;

    hr = RegisterName(CLSID_MinMaxShipping,L"MinMax.MinMaxShipping");
    if(FAILED(hr)) return hr;

    return hr;

}

See the Pipe_stages.h file for the constants for other pipeline stages and features.

See Also

Deciding Which Interface to Expose

Enhancing Component Usability

Implementing the IPipelineComponent Interface

Active Template Library

MinMaxShip Sample Pipeline Component


Error Levels

Pipeline components return one of the following values:

  • 1 = OPPERRORLEV_SUCCESS

  • 2 = OPPERRORLEV_WARN

  • 3 = OPPERRORLEV_FAIL

The pipeline keeps track of the highest error value returned by a previously executed component in the pipeline. Attached to each stage in the pipeline is an attribute that indicates the maximum error level the component will tolerate. If the current error level is less than or equal to the maximum error level for this stage, the components can run the IPipelineComponent::Execute method.

Error levels are checked upon entrance to stages to improve the user experience. For example, a user has completed the shipping stage, the tax stage, and the payment stage, and has entered incorrect information, causing level 3 errors in any or all of these stages. Instead of prompting the user with a shopper warning after each stage, the user can be presented with just one error before the processing of the credit card in the accept stage. This is because, when the level 3 errors are encountered by the accept stage, which has a maximum error level of 2, it prompts the user with a shopper warning indicating all the errors at one time.

See Also

Error Handling


MinMaxShip Sample Pipeline Component

The purpose of the MinMaxShip sample is to demonstrate interaction with the Order Processing pipeline (OPP) as a pipeline component, as well as to demonstrate the new shipping component architecture in Commerce Server 2000. By updating a custom Commerce Server Business Desk module, called Shipping Method, the MinMaxShip sample can be quickly added to an existing Commerce Server site for use in the shipping stage of an OPP.

This section contains:

  • Design

  • How to Use the MinMaxShip Sample


Design

The MinMaxShip object is a Component Object Model (COM) object that exposes a set of COM interfaces to the Order Processing pipeline (OPP).

The MinMaxShip sample object, which is included in the Commerce Server 2000 Software Development Kit (SDK), calculates the shipping total for all "shipments to process" in an order by taking the sum of the list prices for the items in a shipment, multiplying it by a percentage, and comparing the product to some specified minimum. The larger number in this comparison is then stored in the _shipping_total key for the shipment.

All shipping components, except the Splitter component, should be registered with the ShippingMethodRouter pipeline component. The Splitter component should be configured from the Pipeline Editor and the code. The remaining components should be configured from the Business Desk Shipping Method module.

See Also

How to Use the MinMaxShip Sample


How to Use the MinMaxShip Sample

The MinMaxShip sample can be found in the MinMaxShip directory of the Order Processing samples directory. For example, C:\Program Files\Microsoft Commerce Server\SDK\Samples\Order Processing\MinMaxShip. In the MinMaxShip directory, the Visual Basic code is in the folder named VB, and the C++ code is in the folder named ATL.

To build the Visual Basic sample

To build the Visual C++ ATL sample

To run the MinMaxShip sample

To build the Visual Basic sample

  1. Click Start, point to Programs, point to Microsoft Visual Studio, and then click Microsoft Visual Basic.

  2. On the File menu, click Open, and then navigate to the directory that contains the MinMaxShipVB.vbp file. For example, C:\Program Files\Microsoft Commerce Server\SDK\Samples\Order Processing\MinMaxShip\VB. Select the MinMaxShipVB.vbp file.

  3. On the File menu, click Make MinMaxShipVB.dll.

  4. After the project has been built, on the File menu, click Exit.

The Visual Basic MinMaxShip sample is now built on your computer.

To build the Visual C++ ATL sample

  1. Click Start, point to Programs, point to Microsoft Visual Studio, and then click Microsoft Visual C++.

  2. On the File menu, click Open, and then navigate to the directory that contains the MinMaxShip.dsw file. For example, C:\Program Files\Microsoft Commerce Server\SDK\Samples\Order Processing\MinMaxShip\ATL. Select the MinMaxShip.dsw file.

  3. On the Build menu, click Build MinMaxShip.dll.

  4. After the project has been built, on the File menu, click Save Workspace.

  5. To close the program, on the File menu, click Exit.

The ATL MinMaxShip sample is now built on your computer.

Running the Sample

To the MinMaxShip samples, you must first install one of the Commerce Server 2000 Solution Sites. After you have installed one of these sites, go to the directory containing the Business Desk files, and perform the following procedure.

To run the MinMaxShip sample

  1. Copy the file MinMax_edit.asp from the BizDesk directory in the MinMaxShip directory to the Shipping directory in Business Desk on the installed site. For example, copy MinMax_edit.asp from C:\Program Files\Microsoft Commerce Server\SDK\Samples\Order Processing\MinMaxShip\BizDesk to C:\InetPub\wwwroot\RetailBizDesk\Shipping.

  2. Copy the file Shipping_methods.xml from the Business Desk directory in the MinMaxShip directory to the Config directory in Business Desk on the installed site. For example, copy Shipping_methods.xml from C:\Program Files\Microsoft Commerce Server\SDK\Samples\Order Processing\MinMaxShip\BizDesk to C:\InetPub\wwwroot\RetailBizDesk\Config.

  3. If you are running the Visual Basic sample, you must open the file MinMax_edit.asp, and change the following line of code:
    g_sProgID = "commerce.minmaxshipatl.1"

    to

    g_sProgID = "commerce.MinmaxShipVB".

    Note

    • This step is not required for the Visual C++ ATL sample.

After the custom Shipping Method module is updated, you can use it to configure new shipment methods of type "MinMaxShip."

See Also

Design


Integrating a Third-Party Product Catalog

There are two general strategies for using existing product catalog data in Commerce Server 2000. You can migrate the data into the Commerce Server Product Catalog System or you can integrate your existing, or third-party catalog system with Commerce Server 2000 through its Application Program Interface (API), replacing the Product Catalog System. Choosing between these two approaches depends on a number of factors.

Integrating an existing catalog system with Commerce Server 2000 requires a programming effort to modify or replace components of Commerce Server and possibly components of your existing catalog system.

The most straightforward approach to data migration requires conversion of the existing data to Extensible Markup Language (XML) or comma separated value (CSV) format. The difficulty of this conversion depends on the format and integrity of your existing data. The size and complexity of your product catalog data will have a direct effect on the length of time needed to process the conversion. There are other approaches to migrating your existing product catalog data. You may decide to pursue a Microsoft BizTalk Server or Data Transformation Services (DTS) integration solution, or you may decide to transmit your product catalog data via other protocols. The option you choose depends on your available resources and expertise. For more information about importing catalog data, see Importing a Catalog.

Integrating a third-party catalog with Commerce Server 2000 involves providing a pipeline component that does the work of the Commerce Server QueryCatalogInfo pipeline component for your existing catalog, and integration with the following Commerce Server components:

  • Integrating with Campaigns. Describes how to provide product data from your external product catalog to the Marketing component for evaluation.

  • Integrating with the Data Warehouse. Describes the Data Warehouse, and how to modify the Data Warehouse schema to match your catalog schema.

  • Integrating with Baskets. Describes how the Basket component receives detailed product information from the product catalog through the QueryCatalogInfo component, and how you replace this component with a pipeline component that will provide information from your existing catalog.

  • Integrating Applications. Describes how to replace Commerce Server 2000 Catalog API calls in the Solution Sites in order to use them with your existing catalog system.

  • Integrating with Business Desk Catalog Modules. Describes how to modify Commerce Server Business Desk, which is a Web-based management system for the Product Catalog System, in order to use it to manage your existing catalog system.


Integrating with Campaigns

The ExpressionBuilder HTML Component (HTC) is used within the Commerce Server Business Desk Campaigns category to build expressions used for applying targeted discounts to products in your catalog. You use expressions to identify products that are eligible for discounts or are awarded by a discount. These expressions are named and saved in an XML representation in an Expression Store. Third-party catalogs must provide an XML profile that describes to the ExpressionBuilder the properties of products in the catalog.

You must replace the QueryCatalogInfo pipeline component with a functional equivalent that runs against your custom catalog system. Use this pipeline component to populate the Order dictionary with data from your external catalog in order to evaluate the expressions.

See Also

ExpressionBuilder

ExpressionEval Object


Integrating with the Data Warehouse

You must extend the following Data Warehouse components for use with a third-party product catalog:

  • Define Schema. The data schema must be defined appropriately by using the Commerce Server OLE database provider. For more information, see Extending the Data Warehouse.

  • Import Data. Catalog data is brought into the Data Warehouse by running the Catalog data import (Commerce Server) Data Transformation Service (DTS) task. You must create a custom script or application to import data from a third-party catalog into the Data Warehouse. For more information, see Importing Data into the Data Warehouse.

  • Prepare Data for Analysis. Before the data in the Data Warehouse can be analyzed it is exported to a Microsoft Online Analytical Processing (OLAP) Server to be stored in multidimensional cubes. For more info see Preparing Data for Analysis with OLAP Server

  • Modify or Create Reports. You will also need to modify or replace any reports that use product catalog data so that they can use third-party catalogs. For more information, see Creating Custom Reports.


Integrating with Baskets

When a user places an item in their basket, the product information for that item is transferred from the catalog database to the basket by the QueryCatalogInfo pipeline component. You must provide a pipeline component that will transfer product information from your existing catalog to the basket.

Note

  • If your existing catalog system is based on database queries and tables, you may be able to use the QueryProductInfoADO pipeline component, depending on the complexity of your data structure.

The substitute component must copy appropriate catalog data to each line item in the basket based on a product key (for example, the SKU). When the component copies this catalog data, it should prefix each written dictionary key with "_product_". For example, the description of the product would be copied to item._product_description. Typically, at a minimum, this written data should include _product_list_price. It could also include descriptions, tax codes, product weight, and so on.

If the SKU/key is not found in the catalog system, the component should write the key delete with a value of 1 onto the line item. The RequiredProdInfo pipeline component then handles the error condition.


Integrating Applications

The Commerce Server Solution Sites interface directly with the Commerce Server Catalog Management System API in a few places. If these applications are to be used with an existing catalog system, you must replace all calls to the Commerce Server Catalog API with calls to the Catalog API from the third-party catalog.


Integrating with Business Desk Catalog Modules

The Commerce Server Business Desk modules for managing a catalog are specific to the Commerce Server Catalog Management System. You can write alternate Business Desk catalog management modules to interface with your existing catalog, either to replace or to supplement whatever management interface or tools it may already have.

For more information, see Building Business Desk Modules.


Extending the Content Selection Framework

The Content Selection Framework (CSF) is a platform level framework for building targeted content delivery applications on the Internet. The targeted advertising and discount features of Microsoft Commerce Server 2000 are built using CSF. The framework provides the means for building new types of content delivery applications and makes it easy to customize and extend the advertising and discount delivery systems.

This section contains:

  • Extending the Capabilities of the Content Selection Frameworkescribes how to extend the scoring, selection, recording, and cache loading capabilities of the CSF.

  • Content Selection Framework Concepts. Describes scoring, filtering, tracing and debugging, selecting, formatting, and recording events in the CSF.

  • Objects and Components of the Content Selection Framework. Describes the functionality of the objects and components of the CSF.

  • Lifecycle of a Request for a Targeted Advertisement Describes the steps involved in targeting advertisements.

  • Performance and Scalability of the Content Selection Framework. Describes how to ensure your custom extensions to the CSF maintain maximum performance.

  • Creating the CSF Headlines Sample. Describes how to install and run the custom CSF Headlines sample.

  • Content Selection Framework Component Reference. Lists the components associated with the CacheManager object, the CSF pipelines, and the Framework.


Extending the Capabilities of the Content Selection Framework

This section describes some of the ways you can extend the Content Selection Framework (CSF). Because the CSF is built on pipelines, it can be extended in many different ways: scoring, selection, recording, and cache loading.

Scoring

Selection

Recording

Cache Loading

Scoring

You can create pipeline components that score content in different ways. An example of this is the CSF Headlines sample scoring component that takes into account the publish date for a headline and its priority in order to compute a score for the headline. Scoring components can also be more general, such as a scoring component that uses neural network technologies in order to score content based on its likelihood of being clicked or leading to a purchase on your site.

Selection

The SelectWinners pipeline component uses a deterministic selection algorithm when selecting generic content; it selects the content item(s) with the highest scores. You could write a new selection component that instead treats the score of each content item as a probability and uses a random number generator to select from among them.

Recording

Commerce Server 2000 records advertising and other content events to the Internet Information Services (IIS) 5.0 log file and aggregates near real-time counts of these events in the Campaigns database. You could extend this to provide statistical sampling that may be used with a third-party inventory management module. Or, if your business is aligned with a third-party auditing firm, and that firm provides a plug-in pipeline component that provides a different type of event logging, you could extend this possibly by recording advertising events to a database.

Cache Loading

If you have additional dimensions you want to target that are not included in the schema of the Campaigns database, you can override the query used by the LoadAdvertisements or LoadDiscounts components and add the new dimensions to the list in the SELECT query. For example, if you run advertisements on multiple Web sites but want to run them all from the same Campaigns database, you could add a dimension for Site. Then each site would use a slightly different query that includes a WHERE Site = 'sitename' clause. Or maybe each ad on your site is associated with a stock ticker, so you add the ticker dimension to the query and then use this to create filters executed by the FilterContent component.


Content Selection Framework Concepts

To optimize your use of Commerce Server 2000, it is important that you understand the underlying concepts on which the Content Selection Framework (CSF) is built.

Scoring

Filtering

Tracing and Debugging

Selecting

Formatting

Recording Events

Scoring

The CSF content selection process is a process of scoring content items and then selecting the "winners" based on those scores. The score for each content item is managed by the ContentList object and is a floating-point number. A content item score of zero means that the content item should not be selected under any circumstances.

There are two stages in a CSF pipeline that manipulate the scores of content items — one to assign an initial score to each item, and one to adjust the score based on targeting criteria. If there is no component in the Initial Scoring stage, then all content items receive an initial score of 1.0. Score adjustments made in the scoring stage should apply multipliers. A multiplier less than 1.0 can be used to reduce the score of a content item, a multiplier greater than 1.0 can be used to increase the score of a content item, and a multiplier of 0.0 can be used to eliminate a content item from further consideration.

Filtering

Filtering is the process of eliminating content items using indexes built on the content contained in the ContentListFactory object. Because a filter uses pre-built indexes, it is considerably more efficient than expression evaluation, but at the expense of reduced flexibility. In the Commerce Server Advertising and Discount pipelines, filters are used on the Page Group and Content Size dimensions, but can be extended to filter on any string, integral, or array column in the ContentList object schema. A filter can either require that content items have a particular column value, or it may exclude content items where the column contains particular values. Filters can also use sets of values, so that content items with any one of the values in the set will meet the filter requirements and will be passed through.

Tracing and Debugging

Sometimes it is difficult to know why a particular content item was selected and not some others. To debug or fine-tune a content delivery application, you can enable tracing in the pipeline. You enable tracing by setting the Trace property on the ContentSelector object to true. When tracing is enabled, all modifications to content item scores are tracked. Components that perform scoring should check to see if tracing is enabled, and if it is, then they should pass descriptive strings when calling the SetScore or AdjustScore methods on the ContentList object. The Commerce Server 2000 Software Development Kit (SDK) contains a file called TraceScores.asp that can be used to display the trace strings for each content item, as well as their final scores. Tracing should be used only for debugging; it should not be used in production. When the Trace flag is on, it severely degrades the performance of the CSF pipelines.

The OrderPipeline object itself provides a rudimentary form of logging so that you can see what values are read and written to or from the Order and Context dictionaries that are passed through the pipeline. To enable this type of debug logging, call the SetLogFile method on the pipeline.

Selecting

After score adjustments have been made, the CSF pipeline has to select the "winners". The SelectWinners component provided with Commerce Server treats advertisements differently than generic content items. For generic content items, it simply picks the item(s) with the highest score. For advertisements, it first decides whether to show a house ad or a paid ad. If a paid ad is selected, it takes the ad with the highest score. If a house ad is selected, it uses the weights of all house ads as probabilities and selects from among them randomly. The SelectWinners component also prevents competing ads from running on the same page and can use a PageHistory string to prevent selecting the same content item multiple times on the same page.

Formatting

The winning content item(s) need to be formatted as strings before they are returned to the page. Formatting brings the properties of the content item and the global- and page-level context properties together and uses them as insertion strings into a provided template. The end result of formatting is a SimpleList object of string values, with each list entry containing the string representing a content item. For information about the formatting process, see FormatTemplate.

Recording Events

Whenever an ad is served or clicked, this event has to be recorded. The Need of Delivery (NOD) algorithm for advertisements uses this event information to compute the score of an ad. The RecordEvent component records these events into an in-memory Dictionary object, called the Performance Dictionary. At the time of the next cache refresh, these events are written to the database by the CSFWriteEvents component. The IISAppendToLog component also records these events to the Internet Information Services (IIS) 5.0 log file for later importing into the Commerce Server Data Warehouse.


Objects and Components of the Content Selection Framework

The objects and components of the Content Selection Framework (CSF) perform all the tasks associated with the scoring, filtering, and selection of targeted content.

CacheManager Object

ContentList and ContentListFactory Objects

ContentSelector Object

Pipelines and Pipeline Components

Expression Evaluator Component

User Object

Targeting Context Profile

Data Warehouse and Analysis Reports

CacheManager Object

The CacheManager object provides simple cache management services. It can periodically invoke Component Object Model (COM) components to fill a cache object, usually a Dictionary component, with information used in the content delivery process. It can also invoke components to write out information collected during the content delivery process, for example, counts of advertising events such as ad requests and ad clicks. For information about how to author these COM components, called Loader and Writer components, see Code to Implement Custom Cache Components.

ContentList and ContentListFactory Objects

The cache loader COM components invoked by the CacheManager object usually create a ContentListFactory object, which contains the entire content set that is available for selection. For each request for content coming in from the ContentSelector object, the ContentListFactory will create a new ContentList object to be used by that single request only. The ContentList object provides methods for scoring and filtering the content in the ContentListFactory object.

ContentSelector Object

The ContentSelector object is the unified interface for selecting all types of dynamic and targeted content displayed on the site. The ContentSelector object provides the means to pass extensible sets of global- and page-level properties to the Content Selection pipelines. It invokes the appropriate pipeline object and returns the resulting content as a SimpleList object of formatted content strings, usually HTML or XML.

Pipelines and Pipeline Components

The core work of content selection occurs in pipelines. Content Selection pipelines are separated into stages such as scoring, selecting, and formatting. You can write custom pipeline components that plug into these stages, either to replace the functionality of an existing Commerce Server 2000 CSF pipeline component or to augment the default behavior.

Scriptor components allow you to prototype a pipeline component in Microsoft Visual Basic Scripting Edition (VBScript) or JScript. Pipelines are also used in the CSF for recording events related to content selection, such as ad requests and ad clicks. For information about the stages in a CSF pipeline and the CSF pipeline components provided with Commerce Server, see Content Selection Pipelines. For information about how to write pipeline components using the Commerce Server 2000 Software Development Kit (SDK), see Building Pipeline Components.

Expression Evaluator Component

The Expression Evaluator component provides flexibility for targeting content on your site. Expressions are constructed in Commerce Server Business Desk, grouped into target groups, and associated with content items available for selection on the site. At run time the EvalTargetGroups component evaluates the expressions in each target group and adjusts the scores of content items in the ContentList object. You can think of expressions as representing the goals for a content item, for example, if you want an ad to be shown to users whose favorite sport is football, but only to those users who are also over the age of 18.

User Object

To target users on your site, you will need to store information about those users and retrieve that information at run time. The Profiles resource and associated profile objects provide the means to do so. At design time you can manage and extend the properties available in the User object profile definition by using the Profile Designer module available in Business Desk and in the Profiles resource in Commerce Server Manager.

Targeting Context Profile

In addition to targeting users of your site, you may also want to target other information representing the context of a request for content. Examples of this are targeting content to users who are visiting your site from a particular domain, targeting content to specific pages or page groups on your site, and targeting content to pages where specific search keywords are provided.

The ContentSelector object serves the dual role of being the interface to CSF content selection, as well as being a property bag for setting context properties for targeting by expressions or filters. At design time you can manage and extend the properties available in the context profile using the Profile Designer module available in Business Desk and in Commerce Server Manager.

Data Warehouse and Analysis Reports

The Content Selection Framework enables you to log event data related to content selection into the IIS log files for your site. The log files can then be imported into the Data Warehouse for reporting. You use the Analysis modules in Business Desk to run reports on the user and site data stored in your Data Warehouse, and you use the results of those reports to perform business analytics on the performance of your Web site.


Lifecycle of a Request for a Targeted Advertisement

This topic describes the steps the Content Selection Framework (CSF) follows to retrieve a targeted advertisement for delivery on the site. The discount selection process is identical, except for replacing the AdvertisingNeedOfDelivery component in one pipeline with the ScoreDiscounts component in the other.

A user accesses an ASP Web page

A user clicks an ad

The CacheManager object background thread fires

A user accesses an ASP Web page

  1. The code in the ASP page creates the ContentSelector object (CSO).

  2. The code in the ASP page sets the CSO page context properties.

  3. The code in the ASP page calls the CSO.GetContent method.

  4. The CSO invokes the Advertising pipeline.

  5. The InitCSFPipeline component calls the CacheManager.GetCache method.

  6. The CacheManager object invokes the CSFLoadAdvertisements component (only the first time).

  7. The InitCSFPipeline component copies some page and global context properties into the Pipe Context dictionary.

  8. The InitCSFPipeline component creates filters for the Size and PageGroups properties.

  9. The LoadHistory component loads the user-specific history string.

  10. The FilterContent component applies the filters.

  11. The AdvertisingNeedOfDelivery component assigns each ad an initial score based on the start date and end date of the ad, the duration of the ad run, and how many events have been served to date.

  12. The HistoryPenalty component applies penalties for ads that have already been shown to the current user and enforces exposure limits.

  13. The EvalTargetGroups component evaluates target groups and adjusts scores.

  14. The SelectWinners component selects the winning advertisement(s). It prevents industry collision and uses the PageHistory string to avoid showing the same ad multiple times on the same page.

  15. The RecordEvent component records the event into an in-memory performance dictionary.

  16. The IISAppendToLog component records the event to the IIS log file.

  17. The RecordHistory component records the event to the user-specific history string.

  18. The SaveHistory component saves the user-specific history string.

  19. The FormatTemplate component formats the selected advertisements using a template that brings together ad properties, page context, and global context and puts the resulting strings into a SimpleList object.

  20. The CSO returns a SimpleList object of formatted advertisements.

  21. The content is rendered onto the ASP page.

A user clicks an ad

  1. The Redir.asp page is called.

  2. The Redir.asp page invokes the RecordEvent component.

  3. The RecordEvent and IISAppendToLog components are called.

  4. The content is rendered onto the ASP page.

The CacheManager object background thread fires

  1. The CSFWriteEvents component flushes events in the in-memory performance dictionary to the database.

  2. The CSFLoadAdvertisements component loads new advertising information, including the updated aggregate event counts used for the Need Of Delivery (NOD) calculation.

See Also

Example Code for ContentSelection Object


Performance and Scalability of the Content Selection Framework

This topic presents tips for how to ensure your custom extensions to the Content Selection Framework (CSF) maintain maximum performance.

Make pipeline components free-threaded and marked as poolable

While it is possible to create CSF pipeline components using Microsoft Visual Basic 6.0, it is not recommended. Visual Basic components are always apartment threaded and therefore the pipeline has to create a new instance of your component for each content request. For maximum performance, implement your pipeline components in Microsoft Visual C++ using the Active Template Library (ATL). Make the components both-threaded and be sure to indicate to the pipeline that it can pool the components by adding the Component Object Model (COM) category, CATID_POOLABLE, to the registration information of your component.

Avoid database access on a per-request basis

For performance reasons, CSF was designed to avoid database or disk access on each content request. Instead, it caches all of the content into in-memory ContentListFactory and Dictionary objects. It queues up campaign item event data and writes it out during the next cache refresh. When writing your own extensions to the CSF, try to retain this design point, if possible.

Too much content to fit in a single in-memory cache

If the amount of content being served by the CSF grows too large, it may not be possible to store all of the content in a single ContentListFactory object. For example, if there are more than 1,000 content items being considered, they should be segmented into multiple content caches. Find a dimension to segment on, such as page group or site name.

Alternatively, in the Load Context stage of your CSF pipeline, you can make a query against a content store, such as a Microsoft SQL Server 2000 database. Use the results of the query to build a ContentListFactory object unique to the request that contains a small subset of the content. If you use this method, build filtering in as part of your query to avoid building a new index on each ContentListFactory object that is created.

Prefer filtering to expression evaluation

When you have a dimension that is commonly used for targeting on your site, consider using a filter instead of expressions to target that dimension. Because filters use pre-built indexes on the ContentListFactory object, they are more efficient than expressions. However, filters generally require a site developer to set them up, whereas a business manager can create and manage expressions.

The "funnel effect"

Try to arrange your filtering and scoring operations in order of increasing performance cost. Filtering should be first (hence its order in the CSF pipeline), followed by rudimentary scoring, such as application of exposure limits. The last step should generally be expression evaluation because it is usually the most costly operation. Your goal should be to eliminate as much content as possible, as early as possible. For example, if your site uses multiple ad banner sizes, any given user request is usually for only one of those sizes, so a filter is used to quickly eliminate all ads with a size that does not match the requested size. You should look for other opportunities to apply such filtering.


Creating the CSF Headlines Sample

The Commerce Server 2000 Software Development Kit (SDK) includes a sample called CSF Headlines that contains components that you can use for displaying targeted news headlines on a site. It includes a scoring pipeline component and a custom cache loader component for loading the headlines and for creating a ContentListFactory object.

This section contains:

  • Step 1: Installing the CSF Headlines Sample

  • Step 2: Preparing SQL Server for the CSF Headlines Sample

  • Step 3: Preparing the CSF Components for the CSF Headlines Sample

  • Step 4: Running the CSF Headlines Sample


Step 1: Installing the CSF Headlines Sample

To install the CSF Headlines sample, perform the following procedure.

To install the CSF Headlines sample

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2000, and then click Commerce Site Packager.

  2. In the Commerce Server Site Packager screen, select Unpack from a package file [.pup], and then click Next.

  3. In the Unpack dialog box, click Browse.

  4. In the Open dialog box, navigate to <drive:>/Program Files/Microsoft Commerce Server/PuP Packages, select Blank.pup, and then click Open.

  5. When you are returned to the Unpack dialog box, select Custom Unpack, and then click Next.

  6. In the Unpack Method dialog box, click Create a new site, and then click Next.

  7. In the Site Name screen, type CSFHeadlines in the Site name box, and then click Next.

  8. In the Select Resources screen, accept the default setting, which unpacks all the resources in the Resources to unpack box, and then click Next.

  9. In the Global Resource Pointers screen, accept the default settings, and click Next.

  10. In the Database Connection Strings screen, accept the default settings, and click Next.

  11. In the Commerce Server Site Packager dialog box, do the following:
    Use this | To do this
    SQL user name | Type your SQL Server user name.
    SQL password | Type your SQL Server user password.

  12. Click OK.

  13. In the Select Applications screen, accept the default settings, and then click Next.

  14. In the Select IIS Web Sites and Virtual Directories screen, in the IIS virtual directory box, which currently holds the value blanksite, type CSFHeadlines.

  15. In the Application box, select BlankBizDesk, and in the IIS virtual directory box that currently holds the value blankbizdesk, type CSFHeadlinesBizDesk, and then click OK.

  16. Accept the default settings for the following dialog boxes, and click Next until you reach the Unpackaging is complete! dialog box.

  17. To close the Commerce Server Site Packager screen, click Finish.

To Update the ASP scripts and the pipeline directory

  1. Click Start, point to Programs, point to Accessories, and then click Windows Explorer.

  2. Copy the files GLOBAL.ASA, DEFAULT.ASP, DUMPCONTENTLIST.ASP, and TESTHEADLINESLOADER.ASP from <drive:>\Program Files\Microsoft Commerce Server\SDK\Samples\Marketing\Headlines\Web to <drive:>\Inetpub\wwwroot\CSFHeadlines.

  3. In the Confirm File Replace dialog box, click Yes to All.

  4. Copy the pipeline directory and the files within it from <drive:>\Program Files\Microsoft Commerce Server\SDK\Samples\Marketing\Headlines\SQL\Web to <drive:>\Inetpub\wwwroot\CSFHeadlinesBizDesk.

For more information about unpacking a site, see Adding a Site. The file to unpack, Blank.pup, is located in the <drive:>\Program Files\Microsoft Commerce Server\PuP Packages directory.


Step 2: Preparing SQL Server for the CSF Headlines Sample

To prepare Microsoft SQL Server for the CSF Headlines sample, perform the following procedure. The CSF Headlines sample must be installed before continuing.

To prepare SQL Server for the CSF Headlines sample

  1. Click Start, point to Programs, point to Microsoft SQL Server, and then click Query Analyzer.

  2. In the Connect to SQL Server dialog box, do the following:
    Use this | To do this
    SQL Server | Type the name of the SQL Server.
    Connect using | Select SQL Server authentication.
    Login Name | Type your SQL Server login name.
    Password | Type your SQL Server password.

  3. Click OK.

  4. In the SQL Query Analyzer screen, on the Query menu, click Change Database.

  5. In the Select Database dialog box, select CSFHeadlines_commerce, and then click OK.

  6. On the File menu, click Open.

  7. In the Open Query File dialog box, navigate to <drive:>\Program Files\Microsoft Commerce Server\SDK\Samples\Marketing\Headlines\SQL, select headlines_config.sql, and then click Open.

  8. On the Query menu, click Execute.

  9. On the File menu, click Open.

  10. In the Open Query File dialog box, navigate to <drive:>\Program Files\Microsoft Commerce Server\SDK\Samples\Marketing\Headlines\SQL, select sample_headlines.sql, and then click Open.

  11. On the Query menu, click Execute.

  12. On the File menu, click Exit.

See Also

Step 1: Installing the CSF Headlines Sample


Step 3: Preparing the CSF Components for the CSF Headlines Sample

To prepare the Content Selection Framework (CSF) components for the CSF Headlines sample, perform the following procedures. The CSF Headlines sample must be installed and SQL Server must be prepared before performing these procedures.

To prepare the CSF components for the CSF Headlines sample in Visual C++

  1. Click Start, point to Programs, point to Microsoft Visual Studio 6.0, and then click Microsoft Visual C++.

  2. On the File menu, click Open.

  3. In the Open dialog box, navigate to <drive:>\Program Files\Microsoft Commerce Server\SDK\Samples\Marketing\Headlines\Components\Scoring, select CSFScoreHeadlines.dsw, and then click Open.

  4. In the CSFScoreHeadlines - Microsoft Visual C++ screen, on the Build menu, click Build.

  5. After the project has been built, on the File menu, click Save Workspace.

  6. On the File menu, click Exit.

To prepare the CSF components for the CSF Headlines sample in Visual Basic

  1. Click Start, point to Programs, point to Microsoft Visual Studio 6.0, then click Microsoft Visual Basic 6.0.

  2. In the New Project screen, on the Existing tab, navigate to <drive:>\Program Files\Microsoft Commerce Server\SDK\Samples\Marketing\Headlines\Components\CacheLoader, select HeadlineLoader.vbp, and then click Open.

  3. Build the project.

  4. After the project has been built, on the File menu, click Save Project.

  5. On the File menu, click Exit.

See Also

Step 1: Installing the CSF Headlines Sample

Step 2: Preparing SQL Server for the CSF Headlines Sample


Step 4: Running the CSF Headlines Sample

To run the CSF Headlines sample, complete the following procedure. The CSF Headlines sample must be installed, and both SQL Server and the Content Selection Framework (CSF) components must be prepared before performing this procedure.

To run the CSF Headlines sample

  1. Click Start, point to Programs, and then click Internet Explorer.

  2. In the Address box, type http://<server name>/csfheadlines/default.asp, and then press ENTER.

The CSF Headlines Web page appears.

The targeted headlines appear on the page, as well as debugging and tracing information about the data processed in the pipeline and the data stored in the cache. Click the Refresh button on your browser to see the changing headlines.

You can try changing the headline dates and priorities in the headline table in Microsoft SQL Server and watch the effect on the headline scores. While no Commerce Server Business Desk module is provided for managing headlines, you can create advertisements and then convert them to headlines by adding corresponding records to the Headline table and changing the Guid_campitem_type column in the Campaign_item table to match the globally unique identifier (GUID) for headline type content (retrieve this GUID from the Campitem_types table).

See Also

Step 1: Installing the CSF Headlines Sample

Step 2: Preparing SQL Server for the CSF Headlines Sample

Step 3: Preparing the CSF Components for the CSF Headlines Sample


Content Selection Framework Component Reference

The Content Selection Framework (CSF) contains many object-specific components. This section contains a list of CSF pipeline and CacheManager object components and links to them in the Programmer's Reference.

This section contains:

  • CacheManager Components

  • Content Selection Framework Pipeline Components

  • Framework Components


CacheManager Components

The following components are the Content Selection Framework (CSF) components used by the CacheManager object for loading caches and writing out campaign results:

  • CSFLoadAdvertisements

  • CSFLoadDiscounts

  • CSFWriteEvents


Content Selection Framework Pipeline Components

The Content Selection pipeline and the Event Processing pipeline use the Content Selection Framework (CSF) pipeline components for determining targeted content and processing navigational user events. The following table lists the components and their recommended pipeline(s) and stage.

Component | Pipeline | Stage
AdvertisingNeedOfDelivery | Content Selection | Initial Score
EvalTargetGroups | Content Selection | Scoring
FilterContent | Content Selection | Filter
FormatTemplate | Content Selection | Format
HistoryPenalty | Content Selection | Scoring
IISAppendToLog | Content Selection and Event Processing | Record
InitCSFPipeline | Content Selection | Load Context
LoadHistory | Content Selection | Load Context
RecordEvent | Content Selection and Event Processing | Record
RecordHistory | Content Selection | Record
SaveHistory | Content Selection | Record
ScoreDiscounts | Content Selection | Scoring
SelectWinners | Content Selection | Select


Framework Components

The components listed in the following table are not pipeline components, although they may be created or used by pipeline components.

Component | C++ link | Visual Basic link
CacheManager | C++ | Visual Basic
ContentList | C++ | Visual Basic
ContentListFactory | C++ | Visual Basic
ContentSelector | C++ | Visual Basic
ExpressionEval | C++ | Visual Basic


Creating Custom Reports

This section describes the methods for creating custom reports. Reports are implemented as either static or dynamic. Static reports are based on either structured query language (SQL) or multidimensional expression (MDX) queries of an SQL or online analytical processing (OLAP) databases, respectively. Dynamic reports are based on an Extensible Markup Language (XML) framework that includes either an SQL query or a reference to a cube.

Static report definitions consist of a query and parameter definitions. When a static report is run, the parameters are presented to the operator and then passed to a rendering component. The rendering component generates an HTML document from the query results. Completed static reports are stored as HTML files on the computer that houses Commerce Server Business Desk. These reports can be opened through Business Desk and are displayed in Microsoft Internet Explorer.

Dynamic report definitions are stored as queries, and the pivot table view is stored in XML format in the Data Warehouse. Query results are displayed in the Microsoft Office 2000 Web Components (OWC) Pivot Table component.

Definitions for the pre-defined reports are contained in the file CSReports.sql found in the Commerce Server installation directory. The CSReports.sql file populates the Report tables in the Data Warehouse. A Data Transformation Services (DTS) Report preparation task is available to process OLAP cubes and execute stored procedures to prepare imported data for reporting.

You use Business Desk to run reports and display query results.

The Commerce Server 2000 Software Development Kit (SDK), which is included with Commerce Server 2000, contains four SQL script files that enable you to create the four report types. The script files to create these reports are located in the installation folder under \Microsoft Commerce Server\SDK\Samples\Business Analytics\Scripts.

This section contains:

  • Creating Static Reports Using SQL. Describes creating static reports using parameterized SQL query statements.

  • Creating Static Reports Using MDX. Describes creating static reports using parameterized MDX query statements.

  • Creating Dynamic Reports. Describes creating dynamic reports using the XML framework.

See Also

Analysis/Reporting Schema

Analysis/Reporting XML Structures

AsyncRpt Object

ReportRender Object

Running Reports


Creating Static Reports Using SQL

The steps involved in creating a static SQL report are described as a running example in the following sections:

  1. Write the SQL query of interest. For details on this step, see Writing the SQL Query.

  2. Add parameter tags to the query. For details on this step, see Adding SQL Parameterization.

  3. Create the base report definition as a set of INSERT statements (one of which is for the query) into the Report table. For details on this step, see Creating the SQL Base Report Definition.

  4. Insert the dimensions for the report into the ReportDimension table. For details on this step, see Adding the SQL Report Dimensions.

  5. Add the report parameters corresponding to the query parameter tags into the ReportParam table. For details on this step, see Adding the SQL Report Parameters.

  6. Run and display or export the report. For details on this step, see Displaying and Exporting the SQL Report.

This running example creates a static report of site visitors with the following attributes:

  • Registration occurred between 3/1/2000 and 3/30/2000.

  • The UserType equals 1.

  • An e-mail address was provided during registration.

After the steps have been successfully executed, the report will be listed in the Reports module in Commerce Server Business Desk.

Once the report is run, it will display the UserID, DateCreated, DateRegistered, Email, FirstName, LastName, TelephoneNumber, UserTitle, and UserType attributes of the first 25 matched users sorted by Email address.


Writing the SQL Query

Create a standard SQL query to return the wanted information.

Step 1

SQL Query =

"SELECT top 25 UserId rcp_guid, DateCreated, DateRegistered, Email rcp_email,

FirstName, LastName, TelephoneNumber, UserTitle, UserType

FROM RegisteredUser

WHERE (DateRegistered >= '03/01/2000' AND DateRegistered <=

'03/30/2000') AND UserType = 1 AND Email is not Null

ORDER BY rcp_email ASC"


Adding SQL Parameterization

In the SQL query created in Step 1, add parameter tags using the [$paramName] syntax. The ReportRender object treats these parameters as macros. Note the added INTO clause.

For more information about the available parameters, see Analysis/Reporting Schema.

Step 2

SQL Query =

"SELECT [$TopCount] UserId rcp_guid, DateCreated, DateRegistered, Email

rcp_email, FirstName, LastName, TelephoneNumber, UserTitle, UserType

INTO [$ResultTable]

FROM RegisteredUser

WHERE [$DateRange] AND [$Expression] AND [$SingleValue]

ORDER BY rcp_email ASC"


Creating the SQL Base Report Definition

Create the base report definition using a set of INSERT statements into the Report table. The SQL query created in Step 2, is inserted into the [Query] field.

The DmExport and UpmExport bits are set so the report can be exported to Direct Mailer (which uses the rcp_email attribute) and User Profile Management (which uses the rcp_guid attribute).

The ReportType is set to Static_SQL (2). The Protected bit is cleared (set to 0) which allows the report to be overwritten or deleted.

For more information about the Report table, see Analysis/Reporting Schema.

Step 3

DECLARE @ReportID int

DECLARE @ReportStatusID int

INSERT INTO [dbo].[Report] ([DisplayName], [Description], [ReportType],

[Category], [Query], [DmExport], [UpmExport], [CreatedBy], [Protected])

VALUES ('Registered Users', 'Registered Users', @Static_SQL, 'Users',

SQL String, 1, 1, 'the almighty creator', 0)

SELECT @ReportID = @@identity


Adding the SQL Report Dimensions

Create the displayable report dimensions using a set of INSERT statements into the ReportDimension table.

Specify the fields to display and the dimension type (column, row, or measure). Fields that are specified in the SELECT statement but are not inserted into the ReportDimension table can be exported, but not displayed.

For more information about the ReportDimension table, see Analysis/Reporting Schema.

Step 4

INSERT INTO [dbo].[ReportDimension] ([ReportID], [DimensionType],

[DisplayName], [FieldName], [Ordinal])

VALUES (@ReportID, 0, "Email", "rcp_email", 1)

INSERT INTO [dbo].[ReportDimension] ([ReportID], [DimensionType],

[DisplayName], [FieldName], [Ordinal])

VALUES (@ReportID, 0, "UserId", "rcp_guid", 2)

INSERT INTO [dbo].[ReportDimension] ([ReportID], [DimensionType],

[DisplayName], [FieldName], [Ordinal])

VALUES (@ReportID, 0, "FirstName", "FirstName", 3)

INSERT INTO [dbo].[ReportDimension] ([ReportID], [DimensionType],

[DisplayName], [FieldName], [Ordinal])

VALUES (@ReportID, 0, "LastName", "LastName", 4)

INSERT INTO [dbo].[ReportDimension] ([ReportID], [DimensionType],

[DisplayName], [FieldName], [Ordinal])

VALUES (@ReportID, 0, "DateCreated", "DateCreated", 5)

INSERT INTO [dbo].[ReportDimension] ([ReportID], [DimensionType],

[DisplayName], [FieldName], [Ordinal])

VALUES (@ReportID, 0, "DateRegistered", "DateRegistered", 6)


Adding the SQL Report Parameters

Create the report parameters using a set of INSERT statements into the ReportParam table.

The parameterizations are of the form:

   [ Operand1   Value1   Operand2   Value2   FieldName ]

An expression equivalent to the parameterization is given immediately following each VALUES clause, first in the above format, and second, if necessary, in a more understandable format.

For more information about the ReportParam table and the various parameters, see Analysis/Reporting Schema.

Step 5

INSERT INTO [dbo].[ReportParam] (ReportID, ParamName, ParamDescription, ParamType, DataType, Opnd1, Val1, Opnd2, Val2, FieldName, Ordinal)

VALUES (@ReportID, '[$TopCount]', 'Number of users', ParamType_SelectOrder, DataType_integer, SelectOrderOpnd_Top, '25', 0, '0', "", 1)

         [ Select Top, 25, 0, 0, "" ]

INSERT INTO [dbo].[ReportParam] (ReportID, ParamName, ParamDescription, ParamType, DataType, Opnd1, Val1, Opnd2, Val2, FieldName, Ordinal)

VALUES (@ReportID, '[$DateRange]', 'User registration date', ParamType_DateRange, DataType_date, DateRangeOpnd_From, '3/1/2000', 0, '3/30/2000', "DateRegistered", 2)

         [ Date From, 3/1/2000, 0, 3/30/2000, DateRegistered ]
         [ 3/1/2000 <= DateRegistered <= 3/30/2000 ]

INSERT INTO [dbo].[ReportParam] (ReportID, ParamName, ParamDescription, ParamType, DataType, Opnd1, Val1, Opnd2, Val2, FieldName, Ordinal)

VALUES (@ReportID, '[$Expression]', 'User type', ParamType_Expression, DataType_integer, ExpOpnd_Equals, '1', 0, '0', "UserType", 3)

         [ =, 1,  0, 0, UserType ]
         [ UserType = 1 ]

INSERT INTO [dbo].[ReportParam] (ReportID, ParamName, ParamDescription, ParamType, DataType, Opnd1, Val1, Opnd2, Val2, FieldName, Ordinal)

VALUES (@ReportID, '[$SingleValue]', 'Email qualifier', ParamType_SingleValue, DataType_text, 0, 'And Email is not Null', 0, 0, "", 4)

         [ 0, Email <> Null, 0, 0, "" ]


Displaying and Exporting the SQL Report

After you have completed steps 1 through 6 (see Creating Static Reports Using SQL for information about the preceeding steps) successfully, the report will appear in the Reports module in Commerce Server Business Desk. The next step is to run or export the report from Business Desk. For information about running or exporting this report, see Business Desk Analysis.

After the report is run, it can be viewed from Business Desk or you can programmatically display or export the report using the ReportRenderer or AsyncRpt objects. For information about programmatically displaying or exporting the report, see ReportRenderer Object and AsyncRpt Object.

A SQL script file is included in the SDK which creates a static SQL report. The file is located in the installation folder under \Microsoft Commerce Server\SDK\Samples\Business Analytics\Scripts.


Creating Static Reports Using MDX

The steps involved in creating a static MDX report are described as a running example in the following sections:

  1. Write the MDX query of interest. For details on this step, see Writing the MDX Query.

  2. Add parameter tags to the query. For details on this step, see Adding MDX Parameterization.

  3. Create the base report definition as a set of INSERT statements (one of which is for the query) into the Report table. For details on this step, see Creating the MDX Base Report Definition.

  4. Add the report parameters corresponding to the query parameter tags into the ReportParam table. For details on this step, see Adding the MDX Report Parameters.

  5. Run and display the report.

The report dimensions are inherent to the query and do not have to be inserted into the ReportDimension table. After the steps have been successfully executed, the report will be listed in the Reports module in Commerce Server Business Desk.

  • The running example creates a static report of the top 100 referring domains by visit.


Writing the MDX Query

Create a standard MDX query.

Step 1

MDX Query =

"SELECT {[Measures].[Visits], [Measures].[Requests]} ON COLUMNS,

TopCount({[Referrer].[Referrer Domain Name].members}, 100,

[Measures].[Visits]) ON ROWS

FROM [Web Usage]

WHERE ([Retail])"


Adding MDX Parameterization

In the MDX query created in Step 1, add parameter tags using the [$paramName] syntax. The ReportRender object treats these parameters as macros.

For more information about the available parameters, see Analysis/Reporting Schema.

Step 2

MDX Query =

"SELECT {[Measures].[Visits], [Measures].[Requests]} ON COLUMNS,

[$TopCount]({[Referrer].[Referrer Domain Name].members}, [$TopCount],

[Measures].[Visits]) ON ROWS

FROM [Web Usage]

WHERE ([$SiteName])"


Creating the MDX Base Report Definition

Create the base report definition using a set of INSERT statements into the Report table. The MDX query created in Step 2 is inserted into the [Query] field.

The ReportType is set to Static_MDX (3). The Protected bit is cleared (set to 0) which allows the report to be overwritten or deleted.

For more information about the Report table, see Analysis/Reporting Schema.

Step 3

DECLARE @ReportID int

DECLARE @ReportStatusID int

INSERT INTO [dbo].[Report] ([DisplayName], [Description], [ReportType],

[Category], [Query], [CreatedBy], [Protected], [Definition])

VALUES ('Visits by Referrer', 'Visits by Referrer', @Static_MDX, 'Web Usage',

MDX Query, 'the almighty creator', 0, "Long report description goes here")

SELECT @ReportID = @@identity


Adding the MDX Report Parameters

Create the report parameters using a set of INSERT statements into the ReportParam table.

For more information about the ReportParam table and the various parameters, see Analysis/Reporting Schema.

Step 4

INSERT INTO [dbo].[ReportParam] (ReportID, ParamName, ParamDescription,

ParamType, DataType, Opnd1, Val1, Ordinal)

VALUES (@ReportID, '[$TopCount]', 'Number of referrer domains',

@ParamType_SelectOrder, @DataType_integer, @SelectOrderOpnd_Top,

100, 1)

INSERT into [dbo].[ReportParam] (ReportID, ParamName, ParamDescription,

ParamType, DataType, Opnd1, Val1, Ordinal)

VALUES (@ReportID, '[$SiteName]', 'Site Name', @ParamType_SiteName,

@DataType_text, @SiteNameOpnd_Equals, 'Retail', 2)

After you have completed steps 1 through 4 (see Creating Static Reports Using MDX for information about the preceeding steps) successfully, the report will appear in the Reports module in Commerce Server Business Desk. The next step is to run or export the report from Business Desk. For more information, see Business Desk Analysis.

After the report is run, it can be viewed from Business Desk or you can programmatically display or export the report using the ReportRenderer or AsyncRpt objects. For information about programmatically displaying or exporting the report, see ReportRenderer Object.

A SQL script file is included in the SDK which creates a static MDX (OLAP) report. The file is located in the installation folder under \Microsoft Commerce Server\SDK\Samples\Business Analytics\Scripts.


Creating Dynamic Reports

This topic describes creating dynamic reports using an XML framework which contains either an SQL query or a reference to a cube. New dynamic reports can be created from existing dynamic reports by running the existing report, editing the pivot view, and saving the result as a new report. If the new report requires a different SQL query or cube than any existing report, a SQL script must be run. Scripts are provided that can be modified to create both types of dynamic reports. These scripts are located in the installation folder under \Microsoft Commerce Server\SDK\Samples\Business Analytics\Scripts.

New dynamic reports are created by following these steps:

  1. Run the modified SQL script to create the basic report.

  2. Open the newly created report or an existing dynamic report.

  3. Modify the report using the features of the pivot control.

  4. Save the customized report as a new report.

When the above steps have been successfully completed, the new report will appear in the Reports module of Commerce Server Business Desk.

This section contains:

  • Creating Dynamic Reports Using SQL. Describes creating dynamic reports using an XML framework containing an SQL query.

  • Creating Dynamic Reports Using Cubes. Describes creating dynamic reports using an XML framework containing a reference to a cube.


Creating Dynamic Reports Using SQL

New dynamic SQL reports are described as a running example in the following sections. To create the report, follow these steps:

  1. Create the SQL query. For details on this step, see Create the Dynamic SQL Query.

  2. Create the XML framework which includes the query. For details on this step, see Create the XML Framework.

  3. Insert the XML and other report parameters into the Report table. For details on this step, see Create the Base Report Definition.

  4. The report shows up in the Reports section of the Analysis module of the Business Desk where it is modified using the pivot control and saved.

A SQL script file, "Analysis - New dynamic SQL report script.sql", is included in the SDK. This script includes the XML framework and can be modified to create the report. The file is located in the installation folder under \Microsoft Commerce Server\SDK\Samples\Business Analytics\Scripts.


Create the Dynamic SQL Query

Create the query string.

Step 1

SQL Query =

"SELECT top 25 UserId rcp_guid, DateCreated, DateRegistered, Email rcp_email,

FirstName, LastName, TelephoneNumber, UserTitle, UserType

FROM RegisteredUser

WHERE (DateRegistered >= '03/01/2000' AND DateRegistered <=

'03/30/2000') AND UserType = 1 AND Email is not Null

ORDER BY rcp_email ASC"


Create the XML Framework

The following shows the XML framework required for the report. Note that the values of the Data Source and Initial Catalog attributes are not specified in the connection string. These values are obtained from the Administration database at report run time.

Insert the SQL query from Step 1 between the CommandText tags.

For more information about the XML structure, see Analysis/Reporting XML Structures.

Step 2

XMLString =
'<xml xmlns:x=''urn:schemas-microsoft-com:office:excel''>
<x:PivotTable>
   <x:OWCVersion>9.0.0.3821</x:OWCVersion>
   <x:DisplayFieldList/>
      <x:FieldListTop>300</x:FieldListTop>
      <x:FieldListLeft>800</x:FieldListLeft>
      <x:FieldListBottom>700</x:FieldListBottom>
      <x:FieldListRight>1000</x:FieldListRight>
   <x:CacheDetails/>
   <x:ConnectionString>Provider=SQLOLEDB;Integrated Security=SSPI;
      Initial Catalog=;Data Source=</x:ConnectionString>
   <x:CommandText>SQL Query</x:CommandText>
</x:PivotTable>
</xml>'


Create the Base Report Definition

Insert the required parameters into the Report table including the XMLString created in Step 2 into the XMLData field.

Step 3

INSERT INTO [dbo].[Report] ([DisplayName], [Description], [ReportType], [Category], [CreatedBy], [Protected], [ShowPivot], [ShowChart], [XMLData], [Definition])

VALUES ('Registered Users', 'Registered Users', 0, 'Visits', 'user', 0, 1, 0, XMLString, "Use this report to view information on the registered users of the site.")

When the above steps have been successfully completed, the report will appear in the Reports module of Commerce Server Business Desk. The next step is to run the report from Business Desk. For more information, see Running Reports.

Note

  • Do not modify the XML structure after the report is initially created. Make any modifications to the report using the pivot table component in the Analysis category in Business Desk. The pivot table view and layout changes are automatically persisted in the XML for the report when it is saved.


Creating Dynamic Reports Using Cubes

New dynamic report OLAP reports are described as a running example in the following sections. To create the report, follow these steps:

  1. Create the XML framework. For details on this step, see Create the XML Framework.

  2. Insert the XML and other report parameters into the Report table. For details on this step, see Create the Base Report Definition.

  3. The report shows up in the Reports section of the Analysis module of the Business Desk where it is modified using the pivot control.

A SQL script file, "Analysis - New dynamic OLAP report script.sql", is included in the SDK. This script includes the XML framework and can be modified to create the report. The file is located in the installation folder under \Microsoft Commerce Server\SDK\Samples\Business Analytics\Scripts.


Create the XML Framework

The following shows the XML framework required for the report. Note that values for the Data Source and Initial Catalog attributes are not specified in the connection string. These values are obtained from the Administration database at the time the report is run.

The name of the cube is specified between the DataMember tags.

For more information about the XML structure, see Analysis/Reporting XML Structures.

Step 1

XMLString =

'<xml xmlns:x=''urn:schemas-microsoft-com:office:excel''>
<x:PivotTable>
   <x:OWCVersion>9.0.0.3821</x:OWCVersion>
   <x:DisplayFieldList/>
      <x:FieldListTop>300</x:FieldListTop>
      <x:FieldListLeft>800</x:FieldListLeft>
      <x:FieldListBottom>700</x:FieldListBottom>
      <x:FieldListRight>1000</x:FieldListRight>
   <x:CacheDetails/>
   <x:ConnectionString>Provider=MSOLAP;Data Source=;Initial Catalog=;
      Client Cache Size=25;Auto Synch Period=10000</x:ConnectionString>
   <x:DataMember>CubeName</x:DataMember>
</x:PivotTable>
</xml>'


Create the Base Report Definition

Insert the required parameters into the Report table including the XMLString created in Step 1 into the XMLData field.

Step 2

INSERT INTO [dbo].[Report] ([DisplayName], [Description], [ReportType],

[Category], [CreatedBy], [Protected], [ShowPivot], [ShowChart], [XMLData],

[Definition])

VALUES ('Dynamic OLAP Report', 'Dynamic OLAP Report', 1, 'Advertising', 'user',

0, 1, 0, XMLString, "Use this report to view advertising information.")

When the above steps have been successfully completed, the report will appear in the Reports module of Commerce Server Business Desk. The next step is to run the report from Business Desk. For more information, see Business Desk Analysis.

Note

  • Do not modify the XML structure after the report is initially created. Make any modifications to the report using the pivot table component in the Analysis category in Business Desk. The pivot table view and layout changes are automatically persisted in the XML for the report when it is saved.


Working with the Data Warehouse

This topic describes working with the Commerce Server 2000 Data Warehouse. Information is provided on the basic structures and primary business categories of the logical schema. Procedures to extend the logical schema and import custom data into the Data Warehouse are also presented.

This section contains:

  • Basic Structures of the Logical Schema. Defines the conceptual infrastructure of the Data Warehouse in terms of the class, data member, key, and relation.

  • Relations. Describes the logical relation types through examples.

  • Primary Business Categories. Explains the conceptual division of the logical schema into primary business categories: Campaigns, Catalog, Transactions, Profile Management, Web Log Import, and Web Topology. Each category may involve multiple business processes. These categories provide the conceptual entry points into the logical schema.

  • Extending the Data Warehouse. Provides examples of extending the Data Warehouse logical schema.

  • Importing Data into the Data Warehouse. Discusses the process of importing custom data into the Data Warehouse.

See Also

Data Warehouse Schema

OLE DB Provider for Commerce Server


Basic Structures of the Logical Schema

The Commerce Server Data Warehouse uses a logical schema to isolate applications from the underlying physical database. The logical schema defines the conceptual infrastructure of the Data Warehouse. The basic structures of the logical schema are the class, data member, key, and relation.

Class

The class is fundamental to the Data Warehouse logical schema. A class is a logical collection of data members. An instance of a class represents the user data imported into the Data Warehouse.

Data member

A data member stores a piece of data. A class contains an arbitrary number of data members that define the logical scope of the class. New data members may be added at any time after the class is created.

Key

A key is a data member or set of data members that uniquely identifies instances of a class. In the previous example, the key for the OrderFormLineItems class is a combination of the private lineitem_id data member and the inherited OrderForm_Id and OrderGroup_Id data members. This means that instances of an OrderFormLineItems class include a unique identifier for the line item plus unique identifiers for the OrderFormHeader and OrderGroup classes.

Relation

A relation connects two classes in a parent-child association. This relation defines the number of instances of each class. In the Commerce Server 2000 Data Warehouse, nearly all relations are one-to-many. This means that zero or more children may exist for each parent. For example, an individual order form has precisely one instance of the OrderFormHeader class. The order form may have multiple line items represented by multiple instances of the OrderFormLineItems class associated with the single OrderFormHeader class instance.

A relation provides the mechanism for sharing data members between classes. A parent class may have zero or more data members defined as inheritable. An inheritable data member is copied to any child class when the relation is created. Notice that this is a logical inheritance defined by the schema, and not inheritance from a C++ point of view.

For example, the OrderFormLineItems class inherits three data members from its parent class, OrderFormHeader. One of these data members, OrderForm_Id, is used to identify the order form containing the line item.

The ID and key of a parent class are always inherited by the child class. The ID is persisted in the child class, but to save space, the key and any other inherited members are not. The parent class ID stored in the child is used to retrieve the parent class key and the other inherited members.


Relations

This topic provides examples of the logical relation types and describes the background steps taken by the OLE DB Provider for Commerce Server to store the classes. The examples will model the relation types as applying to the relationship between a dog and a dog owner. The two classes are pseudo-defined as follows:

Class DogOwner
  {
  [Key] DogOwnerName
  DogOwnerAddress
  }

Class Dog
  {
  [Key] DogName
  DogBreed
  }

This section contains:

  • One-to-Many Relation. Models a one-to-many relation where each dog can have only one owner but each owner can have multiple dogs.

  • Many-to-Many Relation. Models a many-to-many relation where each dog can belong to multiple owners and each owner can have multiple dogs.

  • One-to-Many with Inheritance Relation. Similar to a one-to-many relation, however the dog can see and populate its owners members.


One-to-Many Relation

Logically, if you define a one-to-many (1:M) relation between a DogOwner (parent) class and a Dog (child) class, then a single DogOwner can have multiple Dogs.

Physically, the table representing the Dog will have a foreign key to the DogOwner.

When you insert data, you have two options:

  1. Relation Example 1. Insert only into the child.

  2. Relation Example 2A. First, insert into the parent.

    Relation Example 2B. Second, insert into the child.

Relation Example 1

Logical View

Insert into the child of a 1:M relation on a blank database.

Insert Dog(DogName="Spot", DogBreed="Cocker Spaniel",
 DogOwnerName="Bob")

Logically, when you instantiate the Dog class, you populate members DogName, DogBreed, and DogOwnerName. With a 1:M relation, you cannot see the non-key members of the parent (that is, DogOwnerAddress). You can later instantiate the DogOwner class separately to update the DogOwnerAddress.

Physical View

Physically, since the row backing the parent key (DogOwnerName) is not present, a new row is inserted into the DogOwner table.

The steps the provider performs for this insert to happen are roughly the following. All this is done automatically by the provider, and is transparent to the user.

  1. Search the parent table (DogOwner) by the given key (Bob). (That is, SELECT FROM DogOwner WHERE DogOwnerName='Bob'.)

  2. Since the parent record does not exist, insert the parent record, with the given key. (That is, INSERT INTO DogOwner (DogOwnerID, DogOwnerName) VALUES (1000, 'Bob'). )

  3. Insert the child record, with the other given values. (That is, INSERT INTO Dog (DogID, DogName, DogBreed, DogOwnerID) VALUES (1000, 'Spot', 'Cocker Spaniel', 1000.)

Table Dog

DogID | DogName | DogBreed | DogOwnerID
1000 | Spot | Cocker Spaniel | 1000

Table DogOwner

DogOwnerID | DogOwnerName | DogOwnerAddress
1000 | Bob | NULL

Relation Example 2A

Logical View

First, insert into the parent of a 1:M relation on a blank database.

Insert DogOwner (DogOwnerName="Bob", DogOwnerAddress="Redmond")

Logically, when you instantiate the DogOwner class (parent), you populate members DogOwnerName and DogOwnerAddress.

Physical View

Physically, a new unique ID (DogOwnerID) is assigned and the members populated. (That is, INSERT INTO DogOwner (DogOwnerID, DogOwnerName, DogOwnerAddress) VALUES (1000, 'Bob', 'Redmond'). ).

Filling in the parent class does not affect the child class.

Table Dog

DogID | DogName | DogBreed | DogOwnerID

Table DogOwner

DogOwnerID | DogOwnerName | DogOwnerAddress
1000 | Bob | Redmond

Relation Example 2B

Logical View

Second, insert into the child of the 1:M relation.

Insert Dog (DogName="Spot", DogBreed="CockerSpaniel",
 DogOwnerName="Bob")

Physical View

Physically, since the row backing the parent key (DogOwnerName) is present, a new row is not inserted into the DogOwner table.

The steps the provider performs are roughly the following.

  1. Search the parent table (DogOwner) by the given key (Bob). (That is, SELECT FROM DogOwner WHERE DogOwnerName='Bob'.)

  2. Since the parent record exists, take the DogOwnerID and place it into the child table.

  3. Insert the child record, with the other given values. (That is, INSERT INTO Dog (DogID, DogName, DogBreed, DogOwnerID) VALUES (1000, 'Spot', 'Cocker Spaniel', 1000.)

Table Dog

DogID | DogName | DogBreed | DogOwnerID
1000 | Spot | CockerSpaniel | 1000

Table DogOwner

DogOwnerID | DogOwnerName | DogOwnerAddress
1000 | Bob | Redmond


Many-to-Many Relation

Logically, if you define a many-to-many (M:M) relation between the DogOwner (parent) class and the Dog (child) class, then a dog can belong to multiple owners, and an owner can have multiple dogs.

Physically, there will be a table representing DogOwner and Dog, and a separate link table that contains the foreign keys to each table.

When you insert data, you have two options:

  1. Relation Example 3. Insert only into the child.

  2. Relation Example 4A. First, insert into the parent.

    Relation Example 4B. Second, insert into the child.

Relation Example 3

Insert into the child of a M:M relation on a blank database.

Insert Dog (DogName="Spot", DogBreed="Cocker Spaniel",
 DogOwnerName="Bob", "Jane")

Logically, when inserting into a class participating in an M:M relation, the child class should be instantiated. In the child class, there is a column which represents the key of the parent (DogOwnerName) – the same as in the 1:M case. However, the key of the parent in a M:M relationship is a multi-value member. Therefore a SAFEARRAY or VECTOR data type can be used when populating the data for this member.

As with the 1:M relation, the non-key members of the parent (DogOwnerAddress) are not visible when instantiating and populating the child class.

Table Dog (child)

DogID | DogName | DogBreed
1000 | Spot | Cocker Spaniel

Table LinkDogDogOwner

DogID | DogOwnerID
1000 | 1000
1000 | 1001

Table DogOwner (parent)

DogOwnerID | DogOwnerName | DogOwnerAddress
1000 | Bob | NULL
1001 | Jane | NULL

Relation Example 4A

First, insert into the parent of a M:M relation on a blank database.

Insert DogOwner (DogOwnerName="Bob", DogOwnerAddress="Redmond")
Insert DogOwner (DogOwnerName="Jane", DogOwnerAddress="Bellevue")

Table Dog (child)

DogID | DogName | DogBreed

Table LinkDogDogOwner

DogID | DogOwnerID

Table DogOwner (parent)

DogOwnerID | DogOwnerName | DogOwnerAddress
1000 | Bob | NULL
1001 | Jane | NULL

Relation Example 4B

Second, insert into the child of the M:M relation on a blank database.

Insert Dog (DogName="Spot", DogBreed="Cocker Spaniel",
 DogOwnerName="Bob", "Jane")

Table Dog (Child)

DogID | DogName | DogBreed
1000 | Spot | Cocker Spaniel

Table LinkDogDogOwner

DogID | DogOwnerID
1000 | 1000
1001 | 1001

Table DogOwner (Parent)

DogOwnerID | DogOwnerName | DogOwnerAddress
1000 | Bob | NULL
1001 | Jane | NULL


One-to-Many with Inheritance Relation

A one-to-many with inheritance relation is similar to the 1:M relation; however, it allows the child to see and populate all the members of the parent.

Relation Example 5

Insert into the child of 1:M with inheritance relation on a blank database.

Insert Dog (DogName="Spot", DogBreed="Cocker Spaniel",
 DogOwnerName="Bob", DogOwnerAddress="Redmond")

Table Dog

DogID | DogName | DogBreed | DogOwnerID
1000 | Spot | Cocker Spaniel | 1000

Table DogOwner

DogOwnerID | DogOwnerName | DogOwnerAddress
1000 | Bob | Redmond


Primary Business Categories

This topic describes the division of the logical schema into primary business categories. Each category contains a group of related classes used for a common business purpose. Some classes serve in more than one category.

The diagrams depicting the business categories show how the classes relate to one another through parent-child associations, or relations. Arrows connecting the classes denote these class relations. The arrows point from the parent classes to the child classes. A solid black arrow denotes a one-to-many relation. A white arrow indicates a one-to-many with inheritence relation. For more information about relations, see Relations.

The classes are colored to match the Data Warehouse Schema Diagram poster included with the product. Uncolored classes are not typically considered part of the business category they are shown in. These classes show some of the connections between the category and other related classes in the schema.

This section contains:

  • Campaigns. Describes the classes involved in marketing operations.

  • Catalog. Describes the catalog classes.

  • Transactions. Describes the basket and purchase order classes involved in making an online transaction.

  • Profile Management. Describes the classes used for managing user profiles.

  • Web Log Import. Describes the classes involved with recording Web events.

  • Web Topology. Describes the classes that define Web structure and access.


Campaigns

This topic describes the classes used to collect and describe marketing data. Marketing data includes custom advertisements, scheduled advertising content, and advertising campaigns. The individual classes are described after the logical diagram. For more information about these classes, see Data Warehouse Classes.

The following diagram shows the major classes used for campaign management and their relationships.

Campaign Classes

Industry
Code
Commerce
Event
Customer
Event
Type
Target
Target
Group
Xref
PageGroup
Xref
Campaign
Event
Campaign
ItemEvents
ByDate
AndUser
RegisteredUser
URI
Date
LogUser
Site
PageGroup
Target
Group
AdItem
DrnItem
Order
Discount
Campaign
Item
Campaign
Creative
Size
Creative
Type
Xref
Creative
Creative
Type
Campaign
Item
Types

AdItem

This class represents scheduled advertising content for a Web page. The class contains data members describing when the advertisement runs and codes linking the advertisement to the products it represents. The IndustryCode class provides a classification of the type of advertisement contained in the AdItem object.

Campaign

This class defines the business process involved in running a marketing campaign for an advertiser. The Campaign class associates a customer (advertiser) with a set of CampaignItem objects (advertisements, discounts, direct mailings, or related sell items). A Campaign object is associated with an EventType object, which describes the marketing event.

A Customer object may have multiple Campaign objects associated with it; this represents multiple advertising campaigns for the customer over time. A Campaign may contain multiple sets of content items (CampaignItem objects). Each set of content items, in turn, may have multiple items (for example, AdItem objects), and may target multiple user groups. Finally, a Web page may contain multiple content items, and a content item may be included in multiple, distinct pages. All of these possibilities are represented through the one-to-many relations between classes.

CampaignEvent

This class stores event information for marketing campaigns. An event for a marketing campaign includes hits on CampaignItem objects and business transactions involving CampaignItem objects.

CampaignItem

This class represents the content included in a marketing campaign (a Campaign object) and/or a scheduled advertisement (a Creative object). The content is represented by one or more of the following objects: AdItem, DmItem, or OrderDiscount.

A CampaignItem object may belong to a specific type of campaign item, specified by a link to a CampaignItemTypes object.

The content items may target specific groups of users; if this occurs, the CampaignItem object links to one or more TargetGroupXRef objects. The TargetGroupXRef class cross-references custom content items with targeted user groups.

Finally, the content items may be part of a Web page presenting multiple groups of custom content. A PageGroupXRef object cross-references the CampaignItem object with the page or pages containing the items.

A CampaignItem object may have multiple content items (for example, AdItem objects), and may target multiple user groups. A Web page may contain multiple content items, and a content item may be included in multiple, distinct pages. All of these possibilities are represented through the one-to-many relationships between classes.

CampaignItemTypes

This class represents categories for custom Web page content.

Creative

This class defines the business process involved in scheduling Web content for a customer (for example, an advertiser). The type of content is recorded by a link to a CreativeType object. One or more CampaignItem objects describe the scheduled content; this content includes advertisements, discounts, related sell items, or direct mailings. A CreativeSize object defines the area of the Web page used to contain the content.

A Customer object may have multiple Creative objects associated with it; this represents multiple advertisements for the customer over time. A Creative advertisement may contain multiple sets of content items (CampaignItem objects). Each set of content items, in turn, may have multiple items (for example, AdItem objects), and may target multiple user groups. Finally, a Web page may contain multiple content items, and a content item may be included in multiple, distinct pages. All of these possibilities are represented through the one-to-many relationships between classes.

CreativeSize

This class represents the size of custom content on a Web page.

CreativeType

This class categorizes custom content for Web pages.

CreativeTypeXRef

This class categorizes custom content for Web pages.

Customer

This class defines a customer who uses advertising through a Commerce Server 2000 Web site. A Customer object associates with an IndustryCode object, which defines the category of industry the customer belongs to. A link to one or more Campaign objects records the marketing campaigns for the customer. A link to one or more Creative objects records any custom advertisements for the customer.

DmItem

This class represents scheduled direct mailing items. The class contains data members detailing the direct mail content, including address and format information.

EventType

This class represents a categorization of marketing events. An EventType object describes a marketing event, and associates with one or more Campaign objects representing the marketing campaigns in the event.

IndustryCode

This class categorizes the type of industry a customer or advertising item represents.

OrderDiscount

This class represents discounted sale items. The class contains data members describing the items and conditions of the sale.

PageGroup

This class represents a group of custom content items used on a Web page for a marketing campaign. The page is part of one or more marketing campaign events; a link from the PageGroup object to one or more CampaignEvent objects represents this information. CampaignItem objects represent the custom content items, and link to the PageGroup object through one or more PageGroupXRef objects.

PageGroupXRef

This class cross-references custom Web page content with the Web page or logical set of Web pages that contain the content. A PageGroupXRef associates a CampaignItem object, which describes the custom content, with a PageGroup object. The PageGroup object represents a Web page or logical set of Web pages that contains custom content.

A single piece of custom content may span multiple Web pages; this is represented by a CampaignItem object linked to multiple PageGroupXRef objects. A single Web page or logical set of Web pages may have multiple separate content items; this is represented by a PageGroup object linked to multiple PageGroupXRef objects.

Target

This class defines a target for marketing and custom Web content, such as a particular type of user. A TargetGroup object links to one or more Target objects to form target groups. The custom content for the group of targets links to the TargetGroup object through a TargetGroupXRef object.

TargetGroup

This class defines a group of targets for marketing and custom Web content. One or more Target objects linked with a TargetGroup object forms a target group. A target group links to the content for the group through a TargetGroupXRef object.

TargetGroupXRef

This class cross-references a target group with the custom content for the target group. Target objects form target groups by linking with a TargetGroup object. The custom content, represented by a CampaignItem object, links to the TargetGroup object through the TargetGroupXRef object.


Catalog

This topic describes the classes used to represent catalogs and products. For more information about the individual classes, see Data Warehouse Classes.

CatalogGlobal

This class represents a global catalog which stores other catalogs.

Category

The class represents a category of a sales catalog.

CatHierarchy

The class represents a level of a hierarchical sales catalog.

Products

This class represents the products contained in a sales catalog.


Transactions

This topic describes the classes used to represent an online transaction. The transaction may be through a shopping basket or through a purchase order. The individual classes are described after the logical diagram. For more information about these classes, see Data Warehouse Classes.

The following diagram shows the major classes used for online sales and their relationships.

Transaction Classes

Products
Basket
Order
OrderForm LineItems
OrderForm Header
OrderGroup Addresses
Order
Group
EventType LogUser
URI
RegisteredUser Site

Basket

This class represents the business transaction involved in adding or removing a product from a shopping basket.

Order

This class stores requests to save or submit purchase orders.

OrderFormHeader

This class represents the header information for an order form. An OrderFormHeader object has contact information, buyer information, and other data necessary to process an order form. An OrderFormHeader object links to zero or more OrderFormLineItems objects, representing the ordered items. An OrderGroup object, representing a purchase order, links to zero or more OrderFormHeader objects.

OrderFormLineItems

This class represents the items in an order form. An OrderFormHeader object, representing the information used to process the order form, links to zero or more OrderFormLineItems objects.

OrderGroup

An OrderGroup object describes purchase order information. Specifically, the OrderGroup object links to one or more OrderFormHeader objects, and one or more OrderGroupAddresses objects. The OrderFormHeader class represents control information for the purchase order such as billing codes, tax codes, and other data required to process the purchase order. The OrderFormHeader object links to one or more OrderFormLineItems objects, which describe the specific products to be purchased. The OrderGroupAddresses object represents mailing and shipping information for purchase orders.

OrderGroupAddresses

This class represents mailing and shipping information for purchase orders.


Profile Management

This section describes the classes used to represent users of Commerce Server 2000 sites. Some of the business processes that use profiles are the tracking of visits and basket events. For more information about the individual classes, see Data Warehouse Classes.

Address

This class stores user and organization addresses. By default, the Commerce Server 2000 User profile data import DTS task imports profile data into this class.

RegisteredUser

This class represents an anonymous or registered user of a Commerce Server 2000 Web site. By default, the Commerce Server 2000 User profile data import DTS task imports UserObject profile data into this class.


Web Log Import

This section describes the classes used to store Web log import data. This data includes visits to a Web site, order form requisitions, and shopping basket transactions. The individual classes are described after the following figure. For more information about these classes, see Data Warehouse Classes.

The following figure shows the major classes used for log import and their relationships.

Web Log Import Classes

Web Log Import Classes
UriQuery
HitsInfo
Win32
Status
Http
Status
Request
OpenUser
Visit
Visit
Info
Referrer
Domain
User
Agent
Visit
URI
LevelNDir
LogUser
Task History
Hostname
Ref
IpRef
Referrer
Import
Options

HitsInfo

This class represents summary information about hits on a Web site.

HostnameRef

This class represents the host name reference for an IP address.

HttpStatus

This class represents the HTTP status codes as codes as stored in the Web log file.

ImportOptions

The class represents the options for import.

IPRef

This class represents an IP reference for a LogUser object. An IPRef object contains information on the IP address, number of look-ups associated with the address, and the status of the reference.

An IPRef object associates with a HostNameRef object, describing the host associated with the IP address.

LevelNDir

This symbolizes the six classes used to represent the six levels in a hierarchical directory structure. Each level contains a directory name and a link to a URI object.

LogUser

This class stores information on user interactions with a Commerce Server 2000 Web site. It is the primary link between the RegisteredUser class and the actions taken during a visit to the Web site.

Someone who visits a Commerce Server 2000 Web site is called a user. A LogUser object is created for every user and used to record information about that user (such as cookie data, user name, and so on). A Visit object is created every time the user visits the Web site. The new Visit object is linked to the LogUser object for that user. A LogUser object may represent an anonymous user, a user who is part of an organization, or a user who is registered on the Commerce Server 2000 Web site.

The IP information for the user is stored in an IPRef object associated with the LogUser object. A HostNameRef object stores host name information for the IPRef object.

OpenUserVisit

This class represents a visit to a Web site that was open when the containing log files were imported. This allows the open visit to be connected and closed in the following log imports. Once a visit is completed (closed), the OpenUserVisit object is deleted and a VisitInfo object is instantiated.

Referrer

This class represents the referring URL for a request.

ReferrerDomain

This class represents the referring domain for a request.

Request

A request is made in the context of a visit. A Request object connects to information describing the user and other details of the visit.

A request may be a part of a URI, in which case a URI object is linked to the Request object. The query string contained in the URI is represented by a URIQuery object linked to the Request object.

Alternatively, a Request may be made through a site URL. The site URL is represented by a SiteURL object linked to the Request object via a URI object. The SiteURL object may represent an actual Web site or a virtual server. If the Request object involves query strings through the site, the SiteURL object will have one or more LinkSVQStringName or LinkMVQStringName objects linking the SiteURL object to the query strings.

TaskHistory

This class tracks DTS task execution and the outcome of the execution. It maintains a history of all the imports (and deletes) that have occurred within the Data Warehouse.

URI

This class represents Uniform Resource Identifiers (URI) used to distinguish a URL, as well as make queries and transactions on Commerce Server 2000 Web sites. A URI object associates with the Commerce Server 2000 Web site through a SiteURL object.

A site is identified by a SiteURL object which stores the first portion, or top level, (for example, domain name) of a site and a linked URI object which stores the remainder of the URL for the site. If the URI object represents a hierarchical directory structure, it will be linked to the appropriate LevelNDir objects.

A business transaction may occur through a URI query; this is represented by a link between one or more Request objects and the URI object.

A URI object only represents a page, not graphics, banners, etc.

URIQuery

This class represents a URI query associated with one or more transaction requests.

UserAgent

This class represents the software infrastructure, such as the operating system and browser, used by a user in a visit to a Web site.

Visit

A Visit object records information describing user activity on a Commerce Server 2000 Web site. A Visit object is associated with a LogUser object and a Site object. The LogUser object contains information on the user. A Visit object describes the context of a visit, including the time and date of the visit.

VisitInfo

This class represents information about a completed visit to a Web site. If a visit has not been completed at log import time, an OpenUserVisit object is instantiated instead.

The VisitInfo class is the primary structure for recording user activity on a Commerce Server 2000 Web site. Someone who interacts with a Commerce Server 2000 Web site is called a user. The VisitInfo class records information describing user activity.

A VisitInfo object is associated with a LogUser object and a UserAgent object. The LogUser object contains information on the user. The UserAgent object contains information describing the software and computer the user is using.

A VisitInfo object describes the context of a visit, including the time and date of the visit. The VisitInfo object links to a Date structure that contains date information.

Win32Status

This class represents the Win32 status codes as stored in the Web log file.


Web Topology

This topic describes the classes used to represent Web configuration data, such as Web sites, virtual servers, and URLs/URIs. Web configuration data is associated with events such as visits and requests for business transactions. The individual classes are described after the following figure. For more information about these classes, see Data Warehouse Classes.

The following figure shows the major classes used for web topology and their relationships.

Web Topology Classes

Web Topology Classes
MVQString
Name
SVQString
Name
URI
SiteURL
Virtual
Server
Crawler
Site
Summary
Site
Server
Binding
Server
Group

Crawler

This class represents a Web crawler associated with a site.

MVQStringName

This class represents the names for custom multi-value query strings.

ServerBinding

This class represents a binding to a server for a virtual server.

ServerGroup

This class represents server groups.

Site

This class represents a Commerce Server 2000 Web site. All logged information pertaining to the use of a Commerce Server 2000 Web site is stored in or connected to a Site object. The URL for the site is a composition of a SiteURL object and a URI object.

The site may be part of a virtual server group. If this occurs, the site connects to a VirtualServer object through a SiteURL object. A business transaction may occur through a URI query; this is represented by a link between one or more Request objects and the URI object. Any visits to the site are linked through one or more Visit objects. If the site has a crawler associated with it, a Crawler object is created and linked to the Site object.

SiteSummary

This class stores summary information, such as total visits and total hits, pertaining to a site.

SiteURL

This class represents a URL-based connection between sites and virtual servers. The relationship between Web site and virtual server is represented by a link to a Site object and a link to a VirtualServer object.

The SiteURL object stores the first portion, or top level, (for example, domain name) of a site. If needed, a URI object is linked to the SiteURL object to form the entire URL for the site.

If there are any query strings (SVQStringName or MVQStringName objects) associated with the site URL, they will be linked to the SiteURL object via the LinkSVQStringName or LinkMVQStringName objects.

SVQStringName

This class represents custom single-valued query strings associated with a URL.

VirtualServer

This class represents a virtual server, which logically binds independent Web sites to one or more servers.

The Web sites associated with the virtual server are represented through a set of SiteURL objects. The binding to a server occurs through association with one or more ServerBinding objects.

The VirtualServer object may be a part of a larger group of servers. If this occurs, the VirtualServer objects will be linked through a ServerGroup object.

If business transactions are made through a URI to the virtual server, a Request object is linked through the appropriate SiteURL and URI objects.


Extending the Data Warehouse

This topic discusses extending the Commerce Server 2000 Data Warehouse logical schema. The architecture of the logical schema is governed by the Data Warehouse meta-model. Extending the logical schema requires detailed knowledge of the meta-model. For more information, see Data Warehouse Meta-model.

Caution

  • Wherever possible, use existing Data Warehouse structures to store data. Deletion from the logical schema is not supported under this version of Commerce Server 2000.

  • The SQL script csdwschema.sql, found in the root installation directory of Commerce Server, creates the logical schema. The script must be run on an empty database. If the schema needs to be reinstalled, delete the previous database, create a new database, and re-run the script.

The distinct steps involved in extending the Data Warehouse are:

  1. Connect to the Data Warehouse and turn on the schema change mode. For details on this step, see Data Warehouse, Analysis, and OLE DB.

  2. Create the classes. For details on this step, see Creating a New Class.

  3. Populate the classes with the appropriate data members. For details on this step, see Creating a New Class Data Member.

  4. If needed, explicitly create a key for the class. A class key can be implicitly created for a single member key. For details on this step, see Creating a New Class Key.

  5. If needed, explicitly create key members for the class. For details on this step, see Creating a New Class Key Member.

  6. If needed, create relations between the classes. If the new structure is to be linked to the existing logical schema, relations have to be created between the new classes and existing Data Warehouse classes. For details on this step, see Creating a New Class Relation.

  7. If needed, create data relation members between the classes. For details on this step, see Creating a New Class Relation Member.

A running example is provided to demonstrate these steps using an existing Data Warehouse class. An existing class is used to provide insight into how the structure fits into the logical schema. The class to be created is the existing OrderFormHeader class. A purchase order is made up of the OrderFormHeader class, representing the information required by an organization to process the order, and the OrderFormLineItems class detailing the purchases. For simplicity, this example will ignore the detailed line items and concentrate on creating the OrderFormHeader class and linking the OrderFormHeader class to an existing OrderGroup class.

The example does not show error checking or certain other formalities required for functional code.

Following this example, the process of filtering is discussed.

This section contains:

  • Creating a New Class

  • Creating a New Class Data Member

  • Creating a New Class Key

  • Creating a New Class Key Member

  • Creating a New Class Relation

  • Creating a New Class Relation Member

  • Creating a Summarization Class Using Filtering


Creating a New Class

This topic describes how to create a new class in the Data Warehouse. A class is created by inserting a new instance in the Class Definition (ClsDef) table, populating the attributes, and saving the changes. For information on the Class Definition table, see Class Definition Meta-data.

To begin the example, create the 'new' OrderFormHeader class, which represents header information required for the processing of order forms. For details on the existing class, see the OrderFormHeader class.

By default, a Binary (6) unique ID is automatically generated for the class.

Since the OrderFormHeader class has a multi-membered key, the GenerateKeyDef attribute is set to False (0). This attribute can be set to True for classes with a single key member (along with setting the IsPrimaryKey attribute to True on the Member definition corresponding to the key) to have the OLE DB Provider for Commerce Server automatically generate the key. For more information about creating a class key, see Creating a New Class Key.

The following table lists the attributes and values in the Class Definition table for the OrderFormHeader class. Unspecified optional attributes are not shown. In the R/O column, R = required, O = optional.

Attribute Name | Attribute Value | Type | R/O | Purpose
ClassDefName | "OrderFormHeader" | String | R | Uniquely identifies the class in the Data Warehouse logical schema.
SourceDefName | "DataSource" | String | R | Identifies the data source for storing instances of the class.
Description | "Header data for a order form." | String | O | Describes the logical class.
GenerateKeyDef | 0 | Integer | O | Do not generate the key automatically. The key will be specified manually using the "ClsKeyDef" meta-data component.
IsActive | 1 | Integer | O | The class is active (instances may be added).
IsPersistent | 1 | Integer | O | Persist instance data.

Running Example - Steps 1 and 2

Connect to the Data Warehouse and create the OrderFormHeader class.

'Create an ADO connection object
   Dim cnnConnection
   Set cnnConnection = CreateObject("ADODB.Connection")

'Create an ADO command object.
   Dim cmdCommand
   Set cmdCommand = CreateObject("ADODB.Command")

'Create an ADO record object.
   Dim recNew
   Set recNew = CreateObject("ADODB.Record")

'Open a connection (bind) to the provider.
   cnnConnection.Open "URL=mscop://InProcConnect/Server=MyServer:" _ &
    "Catalog=DWSchema:Database=Retail_dw:User=admin:Password=*****:" _ &
    "FastLoad=True"

'Set the connection in the command object
   Set cmdCommand.ActiveConnection = cnnConnection

'Turn on "Schema Change" mode
   cmdCommand.CommandText = "SchemaMode=1"
   cmdCommand.Execute

'Create an instance in the Class Definition table.
   recNew.Open "ClsDef/OrderFormHeader", cnnConnection, _
    adModeWrite, adCreateOverwrite

'Set the attributes
   recNew("SourceDefName") = "DataSource"
   recNew("Description") = "Header data for a order form."

'Create our own key
   recNew("GenerateKeyDef") = 0
   recNew("IsActive") = 1
   recNew("IsPersistent") = 1

'Save the new row.
   recNew("__Commit") = 1
   recNew.Fields.Update

Now that the new class exists, populate the class with data members.


Creating a New Class Data Member

This section describes how to create a new data member for a class in the Data Warehouse. The class must exist prior to creating the data member.

A class member is created by inserting a new instance in the Member Definition (MemDef) table, populating the attributes, and saving the changes. For information on the Member Definition table, see Member Definition Meta-data.

The running example (which originates in Creating a New Class) continues by creating the OrderForm_Id and ordergroup_id members of the OrderFormHeader class. For details on the existing class, see the OrderFormHeader class. Additional class members are created in the same way.

The following table lists the attributes and values in the Member Definition table for the OrderForm_Id member. Unspecified optional attributes are not shown. In the R/O column, R = required, O = optional.

Attribute Name | Attribute Value | Type | R/O | Purpose
MemberDefName | "OrderForm_Id" | String | R | Uniquely identifies the data member for the class.
ClassDefName | "OrderFormHeader" | String | R | Stores the name of the containing class.
TypeName | "UUID" | String | R | Identifies the data type of the data member.
Description | "Identifier for an order form." | String | O | Describes the logical concept underlying the data member.
IsActive | 1 | Integer | O | This is an active data member (that is, instances may be added).
IsPersistent | 1 | Integer | O | Persist instances of this data member in the underlying data store.
IsPrimaryKey | 0 | Integer | O | This attribute is set to True (1) when the GenerateKeyDef attribute is True in the Class definition to have the Provider automatically generate the class key. This is not allowed for multi-membered keys.
IsRequired | 1 | Integer | O | This data member is required.

The following table lists the attributes and values in the Member Definition table for the ordergroup_id member. Unspecified optional attributes are not shown.

Attribute Name | Attribute Value | Type | R/O | Purpose
MemberDefName | "ordergroup_d" | String | R | Uniquely identifies the data member for the class.
ClassDefName | "OrderFormHeader" | String | R | Stores the name of the containing class.
TypeName | "UUID" | String | R | Identifies the data type of the data member.
Description | "Unique identifier for the OrderGroup class." | String | O | Describes the logical concept underlying the data member.
IsActive | 1 | Integer | O | This is an active data member (that is, instances may be added).
IsPersistent | 1 | Integer | O | Persist instances of this data member in the underlying data store.
IsPrimaryKey | 0 | Integer | O | This attribute is set to True (1) when the GenerateKeyDef attribute is True in the Class definition to have the Provider automatically generate the class key. This is not allowed for multi-membered keys.
IsRequired | 1 | Integer | O | This data member is required.

Running Example - Step 3

Create the new OrderForm_Id and ordergroup_id data members for the OrderFormHeader class.

'Create an instance in the Member Definition table for the first member.
   recNew.Open "MemDef/OrderFormHeader/OrderForm_Id", cnnConnection, _
    adModeWrite, adCreateOverwrite

'Set the attributes
   recNew("ClassDefName") = "OrderFormHeader"
   recNew("TypeName") = "UUID"
   recNew("Description") = "Identifier for an order form."
   recNew("IsActive") = 1
   recNew("IsPersistent") = 1
   recNew("IsPrimaryKey") = 0
   recNew("IsRequired") = 1

'Save the new row.
   recNew("__Commit") = 1
   recNew.Fields.Update

'Create an instance in the Member Definition table for the second member.
   recNew.Open "MemDef/OrderFormHeader/ordergroup_id", cnnConnection, _
    adModeWrite, adCreateOverwrite

'Set the attributes.
   recNew("ClassDefName") = "OrderFormHeader"
   recNew("TypeName") = "UUID"
   recNew("Description") = "Identifier for an order form."
   recNew("IsActive") = 1
   recNew("IsPersistent") = 1
   recNew("IsPrimaryKey") = 0
   recNew("IsRequired") = 1

'Save the new row.
   recNew("__Commit") = 1
   recNew.Fields.Update

The next step in the example is to create the key used to uniquely identify an instance of the OrderFormHeader class.


Creating a New Class Key

This section describes how to create a key as the unique identifier for a class. The class must exist prior to creating the key. Keys may be single or multi-membered.

For a single valued key there are two methods of creation.

  • Implicitly create the key by setting the value of the GenerateKeyDef attribute of the Class Definition table and the IsPrimaryKey attribute of the Member Definition corresponding to the key both equal to True (1). Explicitly creating a new instance in the Class Key Definition table is then unnecessary.

  • Explicitly create the key in a two step process. The first step is to insert a new instance in the Class Key Definition (ClsKeyDef) table, populating the attributes, and saving the changes. For information about the Class Key Definition table, see Key Definition Meta-data. The second step is to define the member of the key through the Class Key Member (KeyMem) table. For information about this step, see Creating a New Class Key Member.

For multi-membered keys, only the second method is available.

We continue our example (which originated in Creating a New Class) by creating the (multi-membered) key for the OrderFormHeader class.

The following table lists the attributes and values of the Class Key Definition table for the OrderFormHeader class. Unspecified optional attributes are not shown. In the R/O column, R = required, O = optional.

Required Attribute Name | Attribute Value | Type | R/O | Purpose
ClassKeyDefName | "OrderFormHeaderKey" | String | R | Uniquely identifies the class key.
ClassDefName | "OrderFormHeader" | String | R | The name of the class for the key.
Description | "Unique key for the OrderFormHeader Class." | String | O | Describes the logical concept underlying the key.

Running Example - Step 4

Create a new key for the OrderFormHeader class.

'Create an instance in the Class Key Definition table.
   recNew.Open "ClsKeyDef/OrderFormHeaderKey", cnnConnection, _
    adModeWrite, adCreateOverwrite

'Set the attributes.
   recNew("ClassDefName") = "OrderFormHeader"
   recNew("Description") = "Unique key for the OrderFormHeader class."

'Save the new row.
   recNew("__Commit") = 1
   recNew.Fields.Update

The next step is to define the members of this key.


Creating a New Class Key Member

This topic describes how to define class member(s) to form an explicit single or multi-membered key for a class. The class for the key member(s) must already exist with a defined class key. The class must already contain the indicated data member(s).

A key member is created by inserting a new instance in the Key Member (KeyMem) table, populating the attributes, and saving the changes. For information on the Class Key Member table, see Key Member Definition Meta-data.

The following table lists the attributes and values of the Class Key Member table for the first member, "ordergroup_id", of the OrderFormHeader class key. Unspecified optional attributes are not shown. In the R/O column, R = required, O = optional.

Attribute Name | Attribute Value | Type | R/O | Purpose
KeyDefName | "OrderFormHeaderKey " | String | R | Name of the class key.
MemDefName | "ordergroup_id" | String | R | Identifies the data member that is part of the class key.
OrdinalPosInKey | 0 | Integer | R | The position of the data member in the key composition, starting with 0 (zero). The key is guaranteed unique only when the data members are processed in a specific order.
Description | "First member of OrderFormHeaderKey." | String | O | Describes the key member.

The following table lists the attributes and values of the Class Key Member table for the second member, "OrderForm_Id", of the OrderFormHeader class key. Unspecified optional attributes are not shown.

Attribute Name | Attribute Value | Type | R/O | Purpose
KeyDefName | "OrderFormHeaderKey " | String | R | Name of the class key.
MemDefName | "OrderForm_Id" | String | R | Identifies the data member that is part of the class key.
OrdinalPosInKey | 1 | Integer | R | The position of the data member in the key composition, starting with 0 (zero).
Description | "Second member of OrderFormHeaderKey." | String | O | Describes the key member.

Running Example - Step 5

Create the members of the OrderFormHeader class key.

'Create an instance in the Key Member table for the first member.
   recNew.Open "KeyMem/OrderFormHeaderKey/ordergroup_id", _
    cnnConnection, adModeWrite, adCreateOverwrite

'Set the attributes for the first key member.
   recNew("MemDefName") = "ordergroup_id"
   recNew("OrdinalPosInKey") = 0
   recNew("Description") = "First member of OrderFormHeaderKey."

'Save the new row.
   recNew("__Commit") = 1
   recNew.Update

'Create an instance in the Key Member table for the second member.
   recNew.Open "KeyMem/OrderFormHeaderKey/OrderForm_Id", _
    cnnConnection, adModeWrite, adCreateOverwrite

'Set the attributes for the second key member.
   recNew("MemDefName") = "OrderForm_Id"
   recNew("OrdinalPosInKey") = 1
   recNew("Description") = "Second member of OrderFormHeaderKey."

'Save the new row.
   recNew("__Commit") = 1
   recNew.Fields.Update

The next step is to create a relation between the 'new' OrderFormHeader class and the existing OrderGroup class.


Creating a New Class Relation

This section describes how to create a parent-child relation between classes in the Data Warehouse. The classes for the relation and the key for the parent class must exist prior to creating the relation. The relation name must be unique.

Notes

  • Member names in inheritance type relations should not be duplicated in the parent and child classes since all the parent class members are visible in the child class.

  • For one-to-many relations, the parent key member names should not be duplicated in the child class for the same reason.

  • Two classes should only have one relation defined between them.

  • If the IsPersistent attribute of a class is set to zero (0), and the class is then defined to be a parent class, the value of the IsPersistent attribute of the class is changed to one (1) by the Provider.

A class relation is created by inserting a new instance in the Relation Definition (RelDef) table, populating the attributes, and saving the changes. For information on the Relation Definition table, see Relation Definition Meta-data.

We continue our example (which originated in Creating a New Class) by creating a one-to-many (type 2) relation between the existing OrderGroup class and the 'new' OrderFormHeader class. For details on these classes, see the OrderGroup and OrderFormHeader classes. By creating this relation to an existing Data Warehouse class, we are linking to the logical schema. Linking to the existing logical schema is not necessary for extending the Data Warehouse.

The following table lists the attributes and values in the Relation Definition table for the relation between the OrderGroup and OrderFormHeader classes. Unspecified optional attributes are not shown. In the R/O column, R = required, O = optional.

Attribute Name | Attribute Value | Type | R/O | Purpose
RelDefName | "OrderGroupToOrderFormHeader" | String | R | Uniquely identifies the relation between the classes.
RelType | 2 | Integer | R | Defines the type of relation. The most common is type "2", which is one-to-many.
ParentClassName | "OrderGroup" | String | R | Identifies the parent class in the parent-child relation.
ParentClassKey | "OrderGroupKey" | String | R | Identifies the key for the parent class.
ChildClassName | "OrderFormHeader" | String | R | Identifies the child class in the parent-child relation.
Description | "OrderGroup to OrderFormHeader relation." | String | O | Describes the logical concept underlying the relation.

Running Example - Step 6

Create a relation linking the OrderFormHeader class to the OrderGroup class.

'Create an instance in the Relation Definition table.
   recNew.Open "RelDef/OrderGroupToOrderFormHeader", cnnConnection, _
     adModeWrite, adCreateOverwrite

'Set the required attributes
   recNew("ParentClassName") = "OrderGroup"
   recNew("ParentClassKey") = "OrderGroupKey"
   recNew("ChildClassName") = "OrderFormHeader"
   recNew("RelType") = 2
   recNew("Description") = "OrderGroup to OrderFormHeader relation."

'Save the new row.
   recNew("__Commit") = 1
   recNew.Fields.Update

Repeat the process above to add relations between the OrderFormHeader class and other classes (such as the Date class for the existing logical schema). The next step is to create a member relation between specific data members in the parent and child classes to be used as the foreign key for the OrderFormHeader class.


Creating a New Class Relation Member

This section describes how to map a member of a parent class to a member of its child class. This allows the mapped parent class member to be seen and populated by the child class. When a class relation is created, a key from the parent class is automatically mapped to the child class (as a non-key member) but not persisted in the child class. In this example, since the implicitly mapped parent class key is also used as part of the child class key, and all members of a key must be persisted, this behavior must be overridden. Explicitly creating the relation member allows the persistence of the member to be set.

The relation between the classes must already be defined. In addition, the classes must contain the respective data members prior to creating the relation member.

A relation member is created by inserting a new instance in the Relation Member (RelMem) table, populating the attributes, and saving the changes. For information on the Relation Member table, see Relation Member Definition Meta-data.

Our running example (which originated in Creating a New Class) concludes by creating a new relation member mapping the ordergroup_id data members of the OrderFormHeader and OrderGroup classes.

The following table lists the required attributes and values in the Relation Member table for the ordergroup_id member relation. Optional attributes are not shown. In the R/O column, R = required, O = optional.

Attribute Name | Attribute Value | Type | R/O | Purpose
RelationName | "OrderGroupToOrderFormHeader " | String | R | Identifies the class relation.
ParentMemName | "ordergroup_id" | String | R | Identifies the name of the parent class member.
ChildMemName | "ordergroup_id" | String | R | Identifies the name of the child class member.
Description | "OrderGroup.ordergroup_id to OrderFormHeader.ordergroup_id relation member." | String | O | Describes the logical concept underlying the relation.

Running Example - Step 7

Create a relation member mapping the ordergroup_id members of the OrderFormHeader and OrderGroup classes and save the updated schema.

'Create an instance in the Relation Member Definition table.
   recNew.Open _
   "RelMem/OrderGroupToOrderFormHeader/ordergroup_id/ordergroup_id", _
    cnnConnection, adModeWrite, adCreateOverwrite

'Set the attributes
   recNew("ParentMemName") = "ordergroup_id"
   recNew("ChildMemName") = "ordergroup_id"
   recNew("Description") = "OrderGroup.ordergroup_id to " & _
    "OrderFormHeader.ordergroup_id relation member."

'Save the new row.
   recNew("__Commit") = 1
   recNew.Fields.Update

'Commit the changes to the Data Warehouse schema.
   cmdCommand.CommandText = "CommitSchema"
   cmdCommand.Execute

'Turn off "Schema Change" mode.
   cmdCommand.CommandText = "SchemaMode=0"
   cmdCommand.Execute

'Close the connection.
   cnnConnection.Close

'Release the objects.
   Set recNew = Nothing
   Set cmdCommand = Nothing
   Set cnnConnection = Nothing

This completes the example of extending the Data Warehouse to include the OrderFormHeader class.

If the OrderFormHeader class was not a pre-existing Data Warehouse class, custom log import tasks would have to be created to populate the new class with user data. Additionally, custom calculations would have to be created to access the new structures for reporting.


Creating a Summarization Class Using Filtering

This topic describes how to create a summarization class using filtering. Filtering allows the summarization to filter out data based on the value of a member of the base class.

For a summarization class, the ClassType attribute of the class definition is set to "3". The InstExclusionExpr attribute of the class definition contains the expression string to filter on. The filtering feature supports the IN and NOT IN operators using the following syntax:

   Exclusion string = "BaseClassMemberName IN(value)"
   Exclusion string = "BaseClassMemberName NOT IN(value)"

Because the steps to extend the schema were shown in the previous sections, the following examples will just show the particular steps for creating the summarizations with filtering.

Example 1

'Set the class name
   Set recNew = CreateObject("ADODB.Record")
   recNew("ClassDefName") = "NewRequestAgg"

'Set the class type to aggregation
   recNew("ClassType") = 3

'Set the name of the base class to use for data
   recNew("BaseClassName") = "Request"

'Set the exclusion string (filter)
'This excludes all data from the aggregation where IsRequest = 1
   recNew("InstExclusionExpr") = "IsRequest IN(1)"

Example 2

'Set the class name
   recNew("ClassDefName") = "NewHTTPStatustAgg"

'Set the class type to aggregation
   recNew("ClassType") = 3

'Set the name of the base class to use for data
   recNew("BaseClassName") = "Request"

'Set the exclusion string (filter)
'This excludes all hits that have an HTTPStatus not in the given set
   recNew("InstExclusionExpr") = _
    "HttpStatus NOT IN(0,200,202,203,204,304)"


Importing Data into the Data Warehouse

This section describes how to import custom data into the Data Warehouse using Microsoft Visual Basic Scripting Edition script (VBScript).

There are five steps to the custom import process:

  1. Reduce the import data set to include only essential data by clearly defining the purpose of the data import. The import time is directly proportional to the amount of data. See the Planning a custom import task topic.

  2. Match the essential data in the line-of-business (LOB) store or log file to existing structures in the Data Warehouse. For example, if user data is required, use the RegisteredUser class to hold the data. See the Planning a custom import task topic.

  3. Extend the Data Warehouse schema to incorporate LOB data not available in existing structures. For example, if the purpose of the data import is to analyze the favorite ice cream flavors of registered users, then a fav_flavor_code data member can be added to the RegisteredUser class. Only extend the existing schema if absolutely necessary. See the Preparing the Data Warehouse topic.

  4. Parse the LOB data into an intermediate form. This is called staging the data. It increases the reliability of the import and reduces the time spent interacting with the Data Warehouse server. Extract the essential data and place it in a format conducive to direct import into the Data Warehouse schema. See the Staging the data topic.

  5. Create a process to import the data from the staging area into the Data Warehouse. Use the Commerce Server 2000 OLE DB provider to import the data into the Data Warehouse schema. See the Executing the custom import task topic.

A running example is used to explain this process. The example involves an ice cream company with a volume of user data. The goal is to use the Data Warehouse to analyze the regional distribution of favorite ice cream flavors.

This section contains:

  • Planning a custom import task

  • Preparing the Data Warehouse

  • Staging the data

  • Executing the custom import task

See Also

Extending the Data Warehouse


Planning a custom import task

This topic discusses the first two steps in the process of importing custom data into the Commerce Server 2000 Data Warehouse.

A running example is used to explain this process. The example involves an ice cream company with a volume of user data in log files. They want to extract information about customers who registered on their Web site over the last year. Part of the registration process involved answering a questionnaire about their favorite flavor of ice cream. To enhance local promotions, the company wants to analyze the regional distribution of favorite flavors.

The log files contain the following data:

Data Property Name | Example Values
Title | "Mr" "Ms" "Dr"
FullName | "Kevin Verboort"
Email_Address | "kevinv@microsoft.com
TelNum | "800 123-4567x123"
FaxNum | "800 123-4567x321"
AddressLine1 | "Public's Animal Shelter"
AddressLine2 | "223 Normal Coast Way, #85"
City | "Everytown"
State | "WA"
ZipCode | "98434-3424"
Fav_Flavor_Code | 34
Fav_Flavor_Comments | "Can never get enough chocolate!"

The goal is to analyze the regional distribution of favorite flavors. This will require, at minimum, the State and Fav_Flavor_Code data. Because the company wants a more granular distribution, the City data must also be included.

To promote their product, the names and e-mail addresses of the registered users are required. This will allow the company to send customized direct mailings to their customers.

The resulting list of essential data contains:

Data Property Name | Data Type
Title | String
FullName | String
Email_address | String
City | String
State | String
Fav_Flavor_Code | Integer (unsigned)

This completes the first step.

The second step involves finding a structure in the Data Warehouse schema that fits this data. The RegisteredUser structure in the Profiles category of the Data Warehouse logical schema is the closest match.

The RegisteredUser class contains data members for title (UserTitle), name (FirstName, LastName), and e-mail address (Email). It does not contain data members for city, state, or favorite ice cream flavor. The following table shows the match between the log data and the Data Warehouse structure.

Source Data | RegisteredUser Data Member
Commerce.GenID object | UserID
Log data: Title | UserTitle
Log data: FullName | FirstName, LastName
Log data: Email_Address | Email
Log data: City | New Data Member: City
Log data: State | New Data Member: State
Log data: Fav_Flavor_Code | New Data Member: Fav_Flavor_Code

The final essential data member is the unique key for the RegisteredUser class. This key is the UserId data member, which is a UUID. In order to fit custom data into the Commerce Server 2000 Data Warehouse, this key must be correctly assigned. Commerce Server 2000 provides a UUID generator. The Commerce.GenID object creates the UUIDs used by Commerce Server 2000 Profiling System to identify users. Using this object to create the UserID keys for the import data guarantees compatibility with any existing data or future data imported into the Data Warehouse. This completes the data required to create valid RegisteredUser objects containing the necessary information.

For the next step, see Preparing the Data Warehouse.


Preparing the Data Warehouse

This topic discusses the third step in the process of importing custom data into the Commerce Server 2000 Data Warehouse. For the previous two steps, see Planning a Custom Import Task. In the second step, it was determined that the RegisteredUser class must be extended to encompass line-of-business (LOB) data. Specifically, three new data members are needed: City, State, and Fav_Flavor_Code.

Caution

  • Extend the existing Data Warehouse schema only if absolutely necessary. Any changes made to the Data Warehouse are irreversible.

The process of adding data members to an existing class is detailed in Creating a New Class Data Member. The MemDef meta-data attribute settings are summarized in the following table.

MemDef Attribute | City | State | Fav_Flavor_Code
MemDefName | "City" | "State" | "Fav_Flavor_Code"
TypeName | "String" | "String" | "ULONG"
IsPrimaryKey | 0 | 0 | 0
IsExported | 0 | 0 | 0
IsActive | 0 | 0 | 0
IsPersistent | 1 | 1 | 1
GenerateColumnDef | 1 | 1 | 1
Description | "User Loc:City" | "User Loc:State" | "Ice Cream Flavor"

The new data members have now been added to the RegisteredUser class. For the next step, see Staging the Data.


Staging the Data

This topic discusses the fourth step in the process of importing custom data into the Commerce Server 2000 Data Warehouse. For the previous step, see Preparing the Data Warehouse.

The main task in staging the data involves extracting the pertinent information from the data source. This information is formatted for direct import into the Data Warehouse schema structure.

The following table summarizes the source, process, and destination for the data.

Source Data (Existing Log file or Commerce Object) | Processing | Destination (New Staged Data file)
Title (string) | Copy | UserTitle (string)
Fullname (string) | Parse First Name | FirstName (string)
FullName (string) | Parse Last Name | LastName (string)
Email_address (string) | Copy | Email (string)
City (string) | Copy | City (string)
State (string) | Copy | State (string)
Fav_Flavor_Code (Integer) | Convert to ULONG | Fav_Flavor_Code (ULONG)

As the input log file is processed, keep track of the number of entries. This will help to simplify the last step in the import process.

For the running example, the data in the staged data file is grouped by user. The final step requires a function that can extract the next data value from the staged data file. No effort is made in this example to optimize the processing.

The data is now staged and ready for import. For the final step, see Executing a Custom Import Task.


Executing the Custom Import Task

This topic discusses the final step in the process of importing custom data into the Commerce Server 2000 Data Warehouse. For the previous step, see Staging the Data.

This step involves creating a custom ADO script to read data from the staged data file and insert it into the Data Warehouse schema structure. It relies on the OLE DB provider to ensure the correct mapping of data. This process is not optimized. The use of a script is not recommended for very large import tasks; it appears here for demonstration purposes only.

The use of the following ADO script requires the existence of a parser function, GetNextValue, to extract the next value from the staged data file. The format of the staged file is assumed to fit the following pattern:

#users
user1title user1fname user1lname user1email user1city user1state user1ffc
user2title user2fname user2lname ...

The ADO script uses the OLE DB Provider for Commerce Server. The provider creates the necessary key values for each entry in the database; it also properly formats and partitions the data to the underlying data store. Use of the provider is highly recommended instead of manipulating the data store directly.

'Create the ADO DB record object.
   Dim rec
   Set rec = CreateObject("ADODB.Record")

'Create the ADO DB Connection object.
   Dim cnnConnection
   Set cnnConnection = CreateObject("ADODB.Connection")

'Create the connection string.
'The "fastload=true:" option is required.
   Dim strConn
   strConn = "URL=mscop://InProcConnect/Server=DWServer:" & _
    "catalog=dwschema:database=Retail_dw:user=admin:" & _
    "password=*****:fastload=true:"

'Connect to the Data Warehouse.
   cnnConnection.Open strConn

'Retrieve the number of users to process.
   Dim nUsers
   nUsers = GetNextValue()

'Instantiate the commerce GUID generator.
   Dim oGenID
   Set oGenID = CreateObject("Commerce.GenID")

'Iterate through the users.
   Dim i
   For i = 0 to nUsers

      'Create a new blank RegisteredUser row.
      rec.Open "instance/registereduser", cnnConnection, _
       adModeWrite, adCreateCollection

      'Create the GUID.
      rec("UserID") = oGenID.GenGUIDString()

      'Get user title.
      rec("title") = GetNextValue()

      'Get user first name.
      rec("firstname") = GetNextValue()

      'Get user last name.
      rec("lastname") = GetNextValue()

      'Repeat for email, city, and state.

      'Get fav_flavor_code.
      rec("fav_flavor_code") = GetNextValue()

      'Bookkeeping.
      rec("UserIDChangedBy") = "DW Custom Import"
      rec("DateCreated") = Cdate(Now())
      rec("DateLastChanged") = Cdate(Now())

      'Save the new row.
      rec("__Commit") = 1
      rec.Fields.Update

      'Done with current user.
      rec.Close
   Next

'Close the connection and release the objects.
   cnnConnection.Close
   Set oGenID = Nothing
   Set cnnConnection = Nothing


Integrating with Passport

Microsoft Passport delivers the following two services, either of which may be integrated into a Microsoft Commerce Server Web site. These services may be integrated separately, or they may both be integrated into the same site:

  • Passport Single Sign In. Passport offers an authentication service that allows Passport users to use a single user name and password for authenticated access to any Web site that employs Passport authentication.

  • Passport Express Purchase. Passport offers a wallet service that allows Passport users to store their credit card and address information with Passport, and then have that information made available to any Web site that employs the Passport wallet.

Customers benefit from Passport integration because they only have a single user name and password to remember, they can avoid entering credit card and address information for every electronic purchase they make, and their sensitive information is maintained in fewer locations. Furthermore, Web sites that want to use Passport are required to adhere to a standardized privacy policy.

Merchants benefit from Passport integration because the improved user experience should encourage more customers to join a Web site as registered users, and should result in fewer abandoned shopping carts. The standardized privacy policy should also result in your users displaying a greater willingness to share personal information.

This section discusses these two integration opportunities separately.

This section contains:

  • Integrating Passport Single Sign In. Describes the Passport authentication service and the ways in which it can be integrated into a Commerce Server Web site.

  • Integrating Passport Express Purchase. Describes the Passport wallet service and the ways in which it can be integrated into a Commerce Server Web site.

  • Next Steps in Integrating with Passport. Provides information about where to continue the process of learning more about Passport and how to integrate it into a Commerce Server Web site.


Integrating Passport Single Sign In

Microsoft Commerce Server 2000 provides for the separation of authentication and profiles. Commerce Server profiles can be used subsequent to the authentication process, even if Commerce Server is not used for authentication. This separation allows you to integrate the Microsoft Passport Single Sign In authentication service, replacing the built-in authentication modes supplied with Commerce Server, while still preserving the integrated capabilities of the Commerce Server Profile service.

Passport Authentication Processing Steps

Passport authentication involves the following steps:

  1. An unauthenticated user attempts to access a protected page on a merchant Web site.

  2. Code on the page calls the Passport Manager object, which re-directs the user's browser to the logon page on the Passport Web site. The re-direction URL includes a query string that contains, among other items, a return URL.

  3. The user supplies their standard Passport credentials on the logon page on the Passport Web site.

  4. Assuming that the credentials of the user are accepted, the Passport Web site re-directs the user's browser back to the merchant Web site, including encrypted Passport profile data in the query string.

  5. The Passport Manager object parses and cleans the query string data, and sends a session cookie to the user's browser.

  6. Session or persistent cookies are set depending on the login preferences of the user.

  7. Subsequent authentication to the protected merchant pages is based on the Passport cookies.

Recommended Integration Strategy

The recommended approach for Passport authentication integration involves integrated use of the Commerce Server Profile service with the Passport Single Sign In authentication service. This approach preserves the benefits of the built-in integration between the Commerce Server Profile service and the other features of Commerce Server.

Once a user is successfully authenticated through Passport, their corresponding user profile is retrieved from the Commerce Server Profile service and is used for the remainder of their session. In order to accomplish this type of integration, the following methodology is recommended:

  • The user profile will need to be modified to include a new property called PassportID. This property will be set to the 64-bit unique user ID employed by the Passport service, known as the Pairwise Unique ID (PUID). For more information about PUIDs, see the Passport SDK documentation.

  • After Passport has successfully authenticated a user, retrieve the MemberIDHigh and MemberIDLow properties from the Passport core profile and calculate the corresponding PUID using the following formula:
    dim sPassportKey, sHex
sHex = Hex(nMemberIDHigh)
sPassportKey = String(8 - len(sHex), "0") & sHex
sHex = Hex(nMemberIDLow)
sPassportKey = sPassportKey & String(8 - len(sHex), "0") & sHex

    For more thorough examples of calculating the PUID, see the Passport Web site at www.passport.com/business/.

  • Use the calculated PUID to retrieve the corresponding Commerce Server user profile, using code that looks something like this:
    Dim csUserProfile
Set csUserProfile = ProfileService.GetProfileByKey( _
                                      "PassportID", _
                                      sPassportKey, _
                                        "UserObject")
  • Set the ticket type and user ID for this user using the AuthManager object. The following two lines of code, from the function LogOnUser in the file Include\Profilelib.asp of the Passport Sitelet in the Commerce Server SDK, demonstrate how these values can be set:
    objAuthMgr.SetAuthTicket strUserName, fCookieSupport, strTimeout
objAuthMgr.SetUserID enumMSCS_ProfileTicketType, _
                     objProfile.Fields(USER_ID).Value

    For more information, see AuthManager.SetAuthTicket and AuthManager.SetUserID, respectively.

  • If the corresponding Commerce Server user profile is not found, one should be created for the new user, storing their PUID in the PassportID property, using a test that looks something like this:
    If ( csUserProfile Is Nothing ) Then
    ' Use your standard method for creating new
    ' user profiles here, probably involving calls
    ' to GenID.GenGUIDString and ProfileService.CreateProfile.
    ' Don't forget to store the PUID so that the proper
    ' profile can be stored next time. For example:
    CreateNewUserProfile(sPassportKey)
End If
  • If the corresponding Commerce Server user profile is found, you may want to consider synchronizing the latest Passport profile data with the corresponding data in the Commerce Server profile. In this way, the user will get the expected results — that changes to their personal data on the Passport Web site is used by participating Passport merchant Web sites.

    The Passport profile contains a ProfileVersion property that allows you to determine if the user's profile data has changed since their last visit.

You could also develop an authentication solution that offers Passport Single Sign In for Passport users, and uses the Commerce Server authentication mechanisms for non-Passport users.


Integrating Passport Express Purchase

Microsoft Passport includes a wallet feature that allows a user to provide the data required to make electronic purchases, such as credit card numbers and shipping addresses, to a single, central location: the Passport Web site. Merchants who participate in the Passport program can retrieve this information from the Passport wallet Web site, saving the user from entering the same data every time they make a purchase. Unlike the Passport Single Sign In authentication service, the Passport Express Purchase service does not require any Passport-specific Component Object Model (COM) objects to be installed on the merchant Web server. Merchants can use the Passport Express Purchase service either with or without using Passport Single Sign In for authentication.

Passport Express Purchase Processing Steps

Passport Express Purchase use involves the following steps:

  1. A user chooses Passport Express Purchase checkout on a merchant Web site page.

  2. The user's browser is re-directed to the Wallet page on the Passport Web site. The re-direction URL includes a query string that contains a return URL, credit card preference, and co-branding data.

  3. If not already signed into Passport, the user is asked to supply their standard Passport credentials.

  4. On the Wallet page, the user makes choices regarding the credit card to use, the billing and shipping addresses, and so on. The user can enter new credit card information or a different shipping address, or edit entries already in their wallet.

  5. The Passport Web site re-directs the user's browser back to the merchant Web site, posting a form that includes the chosen Wallet information, formatted using Electronic Commerce Markup Language (ECML).

  6. The merchant Web site makes use of the returned Wallet data to complete the purchase.

Recommended Integration Strategy

The recommended approach for Passport Express Purchase integration involves streamlining the purchase process as much as possible. Since the user has already reviewed their credit card and address data on the wallet page, you should avoid asking the user to explicitly review their personal data again on your Web site. Validate the data returned to you by the Passport wallet site in whatever manner you have chosen, collect any additional information you require, and then display an order summary page on which the user can provide final approval of their order. Information supplied by the Passport wallet site can be displayed again on the summary page (the complete credit card number is a possible exception) for implicit review.

Important

  • Avoid using the data returned by the Passport wallet site to do nothing more than provide default information on a form page that the user cannot avoid. This defeats much of the "express purchase" purpose of using Passport in the first place.

You should seriously consider co-branding the Passport pages so that they blend seamlessly into your Web site. When you register with Passport, you can supply the URL of a customizable style sheet (.CSS) file in which you can define the colors and properties of almost all elements on the Passport login, registration, and wallet pages. You can also inject your own content onto most wallet pages, including your own site-specific questions. Using this mechanism, you can collect whatever additional information you require to complete the purchase on the Passport wallet page, which allows your users to go directly to an order summary page when they return to your Web site.


Next Steps in Integrating with Passport

In order to successfully integrate Passport Single Sign In authentication service or the Passport Express Purchase service into a Commerce Server Web site, you will need to do the following:

  • Use the Passport Web site to learn more about Passport and the services it provides. The site has white papers, demonstrations, implementation guides, sample code, as well as information about the Passport discussion group and how to direct questions to the Passport team.

  • Sign up as a Passport site at www.passport.com/business. After you have done this, you can download the Passport Software Development Kit (SDK) and study its capabilities in more detail.

  • Make sure your Web site conforms to the standards required for participation in Passport Web sites. These standards concern privacy, security, and so on.

  • If you intend to use the Passport Express Purchase service, obtain a certificate from an authorized Certification Authority. Since the Passport Express Purchase service uses Secure Socket Layer (SSL) technology for security, a certificate is required.

  • Study the Passport Sitelet source code supplied in the Commerce Server SDK. For more information, see the SDK Road Map.


Programmer's Reference

This section provides reference documentation about programming with the Microsoft Commerce Server 2000 platform. This includes information about the Component Object Model (COM) objects you can invoke, the COM interfaces you can implement, the supplied pipeline components, XML structures, database schemas, Business Desk utilities, and so on.

This section contains:

  • Object Reference. Provides reference documentation for the COM objects supplied with Commerce Server, and for each of their properties and methods. These are the objects that you will explicitly create and invoke. There are parallel reference pages that describe the objects from the perspective of two different programming languages:
    • Microsoft Visual Basic/Microsoft Visual Basic Scripting Edition (VBScript)

    • C++
  • Interface Reference. Provides reference documentation for the COM interfaces that you can implement so that your objects can be invoked by Commerce Server. These include the pipeline interfaces that you implement to create your own pipeline components, and the Site Packager interface that allows you to build objects that can be invoked by Site Packager and Commerce Server Manager.

  • Pipeline Component Reference. Provides reference documentation for the pipeline components supplied with Commerce Server.

  • OLE DB Provider for Commerce Server. Provides reference documentation for the OLE DB Provider that provides access to the Profile Service and the Data Warehouse within Commerce Server.

  • Business Desk Reference. Provides reference documentation for the Commerce Server Business Desk, including the details of the events, properties, and methods of the HTML Components (HTCs), as well as details about the constants, global variables and utility routines provided by Business Desk.

  • XML Reference. Provides reference documentation for the structure of various XML documents used within Commerce Server.

  • Schema Reference. Provides reference documentation about various database schemas used in key areas of Commerce Server where detailed knowledge of the schema is important.

  • Database Table Reference. Provides information about many Commerce Server databases and the tables they contain. This information can be useful when establishing SQL replication.

  • Style Sheet Reference. Provides information about the Cascading Style Sheets (CSS) used by Commerce Server Business Desk.


Object Reference

This section provides detailed information about the Component Object Model (COM) objects supplied with Microsoft Commerce Server 2000. Parallel reference pages are provided to describe the objects from the perspective of two different programming languages:

  • Microsoft Visual Basic/Microsoft Visual Basic Scripting Edition (VBScript)

  • C++

Note

  • Access to the Commerce Server objects from Java and Microsoft JScript is not supported.

This section contains:

  • Managing COM Parameter Memory. Provides information about ownership of COM parameter memory before and after invoking COM objects.

  • Standard COM Errors. Provides information about the standard COM errors used by many of the Commerce Server COM objects to communicate failures to their callers.

  • Visual Basic Invocation. Describes the Commerce Server COM objects from the perspective of Microsoft Visual Basic and VBScript.

  • C++ Invocation. Describes the Commerce Server COM objects from the perspective of C++.


Managing COM Parameter Memory

This topic provides some high-level information about memory ownership issues as they pertain to parameters passed into and out of the properties and methods of Component Object Model (COM) objects.

Additional, more detailed information can be found at http://msdn.microsoft.com.

Parameter Direction Summary

The following general statements apply to the various types of non-scalar parameters, such as objects, and to strings, when passed into and out of the methods and properties of a COM object:

  • For [in] parameters, the caller allocates memory and is also responsible for freeing the memory after the call has returned.

  • For [out] parameters, the method or property allocates the memory and the caller is responsible for freeing the memory.

  • For [in, out] parameters, the caller allocates memory, the method or property can optionally deallocate and reallocate it, and the caller is finally responsible for deleting the memory.

Visual Basic

If you are programming in either Microsoft Visual Basic (VB) or Visual Basic Scripting Edition (VBScript), you need to remember that if a method or property returns an object and you assign a reference to that object to a variable, then you should set the variable to Nothing when you are done with it. For example:

' Assume object oCalledObject already exists.
Dim oRetObject
oCalledObject.GetAnObject(oRetObject)

' Do something with the returned object.
oRetObject.DoSomething

' Release the reference to the returned object.
Set oRetObject= Nothing

C++

If you are programming in C++, keep in mind the following issues:

  • When passing a string to a method (including get_ and put_ property methods), as a BSTR, you own the BSTR both before and after the call. If the object needs to remember the string, it will make a copy. Allocate and deallocate BSTRs from the special heap designed for that purpose, using the SysAllocString and SysFreeString family of functions.

  • When a string is returned from a method (including get_ and put_ property methods), using the BSTR pointer you provide, you now own the returned BSTR and are responsible for deallocating it using the SysFreeString family of functions. Note that the method allocated the BSTR and you are going to deallocate it.

  • Simple scalar types are passed by value, so there is nothing special to do with respect to their associated memory.

  • When a COM object (a pointer to one of its interfaces) is passed as a parameter to a method, the normal COM AddRef and Release mechanism is used to manage the lifetime of that object. The caller of the method should have called the AddRef method (perhaps indirectly) prior to the method call, and should call the Release method whenever it no longer needs to reference the object, presumably sometime after the method call has returned.

    If the object needs to retain a reference to the object beyond the return of the method call, it will call the AddRef method to record its ongoing reference. This way, even if the caller of the method calls the Release method after the method returns, the object will retain its reference and the object will not be deleted.

  • When a COM object (a pointer to one of its interfaces) is returned from a method, using the provided address of an interface pointer, the method will have called the AddRef method on behalf of the caller prior to returning. The caller need only worry about calling the Release method when they are finished with the object.

  • SAFEARRAYs need to be allocated using the special OLE allocators from the SafeArrayCreate family of routines that are provided for this purpose. For scriptable objects, the contents of the safe arrays need to be variants, not other scalars like BSTRs.

  • VARIANTs have special helper functions in the VariantInit/VariantClear family of functions to help with the handling and freeing of values.


Standard COM Errors

Many, but not all, of the properties and methods of the Commerce Server objects use standard Component Object Model (COM) HRESULT return values to communicate whether the operation was successful or not.

In C++, these values are the actual return values from the methods themselves (including property get_ and put_ methods). The program must explicitly perform error checking by examining these return values, or use some variation of structured error handling.

In Microsoft Visual Basic (VB), and in Visual Basic Scripting Edition (VBS) as used in Active Server Pages (ASP), these values are placed in the Number property of the global Err object. Error handling is either handled automatically, displaying a standard error dialog box, or explicitly by the program, checking the value of the Number property of the global Err object. The On Error Resume Next command disables automatic error handling, thereby enabling explicit error handling.

The following table shows the most common standard COM errors returned by the properties and methods of the Commerce Server objects.

Constant | Value (32-bit) | Description
S_OK | 00000000 | The standard return value used to communicate successful completion.
S_FALSE | 00000001 | An alternate success value, typically used to communicate successful, but non-standard completion. The precise meaning depends on the method or property in question.
E_UNEXPECTED | 8000FFFF | Catastrophic failure error.
E_NOTIMPL | 80004001 | Not implemented error.
E_OUTOFMEMORY | 8007000E | Out of memory error.
E_INVALIDARG | 80070057 | One or more arguments are not valid error.
E_NOINTERFACE | 80004002 | Interface not supported error.
E_POINTER | 80004003 | Pointer not valid error.
E_HANDLE | 80070006 | Handle not valid error.
E_ABORT | 80004004 | Operation aborted error.
E_FAIL | 80004005 | Unspecified error.
E_ACCESSDENIED | 80070005 | General access denied error.

Additional information may be available using the global Err object. In Visual Basic, the Description property of the Err object may contain a text description of the error.

In C++, call the API function GetErrorInfo to retrieve the most recently set IErrorInfo pointer in the current logical thread. The GetDescription method of that interface may return a text description of the error.


Visual Basic Invocation

This section describes the Component Object Model (COM) objects supplied with Commerce Server 2000 and how to invoke their properties and methods from Microsoft Visual Basic and Microsoft Visual Basic Scripting Edition (VBScript). The following table lists each object and provides a brief description of its purpose.

Object | Description
AdminEventLog | Writes error, informational, warning, and success messages to the event log.
AdminFiles | Provides read-only access to server-side binary and text files.
AdminSite | Provides read/write access to site configuration properties and allows site administration. This object is supplied for backward compatibility purposes only.
AdminWebServer | Allows enumeration of Web sites and their properties.
AppConfig | Allows retrieval of country, region codes, and names from the site configuration store.
AppFrameWork | Provides formatting and validation methods that simplify forms processing in Active Server Pages (ASP).
AsyncRpt | Provides asynchronous rendering and exporting of static reports.
Auction | Provides methods for supporting auctions.
AuthManager | Provides a secure, standardized, and extensible way to manage authentication of users.
BizDeskSecurity | Allows specific Commerce Server Business Desk modules to be hidden from particular users.
CacheManager | Provides generic caching services.
CatalogManager | Allows management of catalogs across the entire Product Catalog System.
CatalogSets | Allows filtering of multiple custom catalogs for different users and organizations.
CatalogToVendorAssociation | Allows a catalog to be associated with particular vendor.
Category | Allows management of a product hierarchy within a particular catalog.
ContentList | Contains a representation of each content item eligible for a given request for content. Also provides services to Content Selection Framework (CSF) components such as filtering and sorting.
ContentListFactory | Allows creation of ContentList objects, and stores data shared by those objects.
ContentListSchema | Allows manipulation of the schema for a ContentListFactory object.
ContentSelector | Allows specification and retrieval of page content.
DataFunctions | Provides methods to perform locale-based data type handling and value range checking.
DBStorage | Provides methods for mapping Dictionary and SimpleList objects to and from a database, primarily for the storage of receipt and order information.
Dictionary | Supports the creation, storage, and retrieval of name/value pairs in memory.
DictionaryXMLTransforms | Transforms data in a Dictionary object into Extensible Markup Language (XML), and XML data into a Dictionary object.
EuroDisplay | Converts and formats currency amounts for use where multiple currencies must be displayed.
ExpressionEval | Allows selection and evaluation of one or more expressions against a set of profiles.
ExpressionStore | Provides methods to create, save, modify, and retrieve expressions.
ExprEvalContext | Stores a specific evaluation context (set of profiles) that can be used for multiple expression evaluation operations.
ExprFltrQueryBldr | Translates an expression in XML form into a SQL filter query string.
GenID | Provides methods to generate globally unique identifiers (GUIDs), and to create and maintain multiple, global sequential counters which are persisted in a database.
GlobalConfig | Provides methods for the configuration management of global resources.
ListManager | Provides methods to create, destroy, manage, and manipulate lists.
LRUCache | Provides a least recently used (LRU) cache for the CacheManager object. It stores a limited number of entries and sorts them according to the least recently used element.
MessageManager | Stores text strings in multiple languages. One popular usage involves the Order Processing pipeline (OPP) components describing error conditions generated during order form processing.
MicroPipe | Runs a single pipeline component from an ASP page without using a pipeline configuration file (.pcf).
MtsPipeline | Executes a non-transacted Microsoft Commerce Server 2000 pipeline.
MtsTxPipeline | Executes a transacted Microsoft Commerce Server 2000 pipeline.
OrderForm | Provides in-memory storage of user and purchase information.
OrderGroup | Allows management of complex orders, such as those containing items from different suppliers, and multiple shipments.
OrderGroupManager | Provides methods to manage OrderGroup and OrderForm objects.
OrderPipeline | Runs a Microsoft Commerce Server 2000 pipeline, and is particularly useful in the Content Selection Framework.
Page | Provides formatting and validation methods that simplify forms processing in ASP pages. This object is supplied for backward compatibility purposes only.
PooledPipeline | Executes a non-transacted Microsoft Commerce Server 2000 pipeline that uses COM+ object pooling for better performance.
PooledTxPipeline | Executes a transacted Microsoft Commerce Server 2000 pipeline that uses COM+ object pooling for better performance.
PredictorClient | Provides methods for downloading prediction models, setting prediction context, and performing predictions.
PredictorServiceAdmin | Allows retrieval of prediction models and prediction model configurations.
PredictorServiceSiteAdmin | Allows management of prediction models and prediction model configurations.
PredModelBuilder | Provides properties and methods to control multiple build threads of prediction models.
Product | Allows manipulation of the relationships between a product variant and a product category.
ProductCatalog | Allows creation, deletion, and modification of catalog data.
ProfileObject | Provides run-time read/write access to profile property data and read-only access to property attributes.
ProfileService | Allows creation, deletion, and retrieval of instances of profile schemas.
ReportRenderer | Provides synchronous rendering and exporting of static reports.
RowCollection | Allows enumeration of the rows returned from the ActiveRows and AllRows properties, and the Search method, of a ContentList object, and from the AllRows property and the Search method of a ContentListFactory object.
Shipping | Creates shipping cost preview information.
ShippingMethodManager | Allows management of multiple shipping methods.
SimpleFindResultInfo | Allows the specification of search criteria when using the OrderGroup and OrderGroupManager objects.
SimpleFindSearchInfo | Allows the specification of search criteria when performing search and delete operations using the OrderGroup and OrderGroupManager objects.
SimpleList | Allows creation of an array of Variants that supports enumeration.
SiteConfig | Provides for configuration management of site resources.
SiteConfigReadOnly | Provides methods to read global and site configuration values from the Administration database.
StandardSManager | Facilitates the run time creation and retrieval of user IDs. This object is supplied for backward compatibility purposes only.


AdminEventLog Object

Use this object to write error, informational, and warning messages to the event log.

ProgID: | Commerce.AdminEventLog (Externally creatable)
COM Class Name: | AdminEventLog
Type Library Name: | Commerce Admin 1.0 Type Library
DLL Name: | MSCSadmin.dll
Threading Model: | Both

The methods of the AdminEventLog object are shown in the following table.

Method | Description
Initialize | Initializes the site, the source, and the event server for writing events.
WriteErrorEvent | Writes error messages (such as resource problems, missing files, and so on) to the Commerce Server event log.
WriteInformationalEvent | Writes informational messages (such as names of logged-on users) to the Commerce Server event log.
WriteWarningEvent | Writes warning messages (such as low memory levels) to the Commerce Server event log.


AdminEventLog.Initialize

Use this method to initialize the object.

Definition

Sub Initialize(
bstrServer As String
)

Parameters

bstrServer

A String that contains the server name.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oAdminEventLog is a Commerce.AdminEventLog object.

oAdminEventLog.Initialize("ServerName")

See Also

AdminEventLog Object


AdminEventLog.WriteErrorEvent

Use this method to write an error event to the Commerce Server event log.

Definition

Sub WriteErrorEvent(
String bstrSiteName,
String bstrMessage
)

Parameters

bstSiteName

A String that contains the site name.

bstrMessage

A String that contains the error event message string.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oAdminEventLog is a Commerce.AdminEventLog object.

oAdminEventLog.WriteErrorEvent("MySite", _
                               "Database does not exist")

See Also

AdminEventLog Object

AdminEventLog.WriteInformationalEvent

AdminEventLog.WriteWarningEvent


AdminEventLog.WriteInformationalEvent

Use this method to write an informational event to the Commerce Server event log.

Definition

Sub WriteInformationalEvent(
String bstrSiteName,
String bstrMessage
)

Parameters

bstSiteName

A String that contains the site name.

bstrMessage

A String that contains the informational event message string.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oAdminEventLog is a Commerce.AdminEventLog object.

oAdminEventLog.WriteInformationalEvent("MySite", _
                         "Database accessed successfully")

See Also

AdminEventLog Object

AdminEventLog.WriteErrorEvent

AdminEventLog.WriteWarningEvent


AdminEventLog.WriteWarningEvent

Use this method to write a warning event to the Commerce Server event log.

Definition

Sub WriteWarningEvent(
String bstrSiteName,
String bstrMessage
)

Parameters

bstSiteName

A String that contains the site name.

bstrMessage

A String that contains the warning event message string.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oAdminEventLog is a Commerce.AdminEventLog object.

oAdminEventLog.WriteWarningEvent("MySite", _
                                 "Low Memory Availability")

See Also

AdminEventLog Object

AdminEventLog.WriteErrorEvent

AdminEventLog.WriteInformationalEvent


AdminFiles Object

Use this object for read-only access to server-side files. Different methods are provided to access binary and text files, respectively.

ProgID: | Commerce.AdminFiles (Externally creatable)
COM Class Name: | CAdminFiles
Type Library Name: | Commerce Admin 1.0 Type Library
DLL Name: | MSCSadmin.dll
Threading Model: | Both

The methods of the AdminFiles object are shown in the following table.

Method | Description
ReadFromBinaryFile | Reads the content of the specified binary file.
ReadFromFile | Reads the content of the specified text file.

See Also

General Purpose Objects


AdminFiles.ReadFromBinaryFile

Use this method to read the contents of the specified binary file. The file can contain any type of data, such as a numeric data or a bitmap.

Definition

Function ReadFromBinaryFile(
bstrFileName As String
) As Variant

Parameters

bstrFileName

A String that specifies the path and file name to read.

Return Values

If this method completes successfully, it returns a Variant containing the file contents.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' The following example opens the specified file and
' then uses the Response.BinaryWrite method to download
' the file to a browser.
' oFile is a Commerce AdminFiles object.
' vFileContents is a variable of type Variant.
vFileContents = oFile.ReadFromBinaryFile("c:\temp\postcard.jpg")
Response.ContentsType = "image/jpeg"
Response.BinaryWrite vFileContents

See Also

AdminFiles Object

AdminFiles.ReadFromFile


AdminFiles.ReadFromFile

Use this method to return the contents of the specified text file. The contents of the file are returned as a text string.

Definition

Function ReadFromFile(
bstrFileName As String
) As String

Parameters

bstrFileName

A String that specifies the path and file name to read.

Return Values

If this method completes successfully, it returns a String containing the file contents.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oFile is a reference to a Commerce AdminFiles object.
' sFileContents is a varaible of type String.
sFileContents = oFile.ReadFromFile("c:\temp\newfile.asp")

See Also

AdminFiles Object

IAdminFiles::ReadFromBinaryFile


AdminSite Object

Use this object to gain centralized access to the Site Server 3.0 Commerce Edition site configuration, so that you can configure and maintain the site.

Important

  • You cannot use this object with Commerce Server 2000 sites. It is included only for backwards compatibility with Site Server 3.0 Commerce Edition.
ProgID: | Commerce.AdminSite (Externally creatable)
COM Class Name: | AdminSite
Type Library Name: | Commerce Admin 1.0 Type Library
DLL Name: | MSCSadmin.dll
Threading Model: | Both

The properties of the AdminSite object are shown in the following table.

Property | Type | Description
Directory | String | Stores the currently registered Site Server 3.0 Commerce Edition site physical directory. This property is read/write.
Status | Variant | Stores the open/closed status of a Site Server 3.0 Commerce Edition site. This property is read/write.
Version | Long | Stores the Site Server 3.0 Commerce Edition version number. This property is read-only.

The methods of the AdminSite object are shown in the following table.

Method | Description
Create | Creates a Site Server 3.0 Commerce Edition site.
Delete | Deletes a Site Server 3.0 Commerce Edition site.
Initialize | Initializes the AdminSite object to load information related to the Site Server 3.0 Commerce Edition site.
InitializeFromMDPath | Initializes the AdminSite object from a metabase path.
IsValidName | Determines whether a given text string is a valid short name for a Site Server 3.0 Commerce Edition site.
ReadDefaultProperties | Reads the properties from the Site.csc file and returns a Dictionary object containing these properties.
ReadManagerProperties | Reads the properties from the Site\Manager\Config\Site.csc file and returns a Dictionary object (the site dictionary) containing these properties.
Reload | Resets all application and session objects for the Site Server 3.0 Commerce Edition site.
WriteDefaultProperties | Writes the properties from the specified site dictionary to the Site.csc file.
WriteManagerProperties | Writes the properties from the specified site dictionary to the Site\Manager\Config\Site.csc file.

Remarks

The AdminSite object provides methods for administering a site, such as specifying data sources and user accounts. The object keeps a number of properties related to the configuration in the site dictionary, which is an implementation of a Dictionary object called MSCSSite. These properties include the short and long names of the site, the secure host, the non-secure host, and the names of other Dictionary objects such as lists of named connection strings and named queries.

See Also

Backward Compatibility Objects


AdminSite.Create

Use this method to create a Site Server 3.0 Commerce Edition site and to optionally create an application and the Config\SQL\SqlSvr and Config\SQL\Oracle subdirectories.

Definition

Sub Create(
bstrInstance As String,
bstrVDir As String,
bstrDir As String,
nAuthorization As Long,
bIsApplication As Boolean,
bIsCommerceSite As Boolean
)

Parameters

bstrInstance

A numeric value expressed as a String representing a Web site. For the default Web site, use (1).

bstrVDir

A String that contains the Site Server 3.0 Commerce Edition site short name (virtual directory).

bstrDir

A String that specifies the physical directory in which to create the site.

nAuthorization

A Long that contains site authorization type.

bIsApplication

A Boolean that controls whether an application is created for the site. If set to True, an application is created for the site. Otherwise no application is created. This setting must be True for a Site Server 3.0 Commerce Edition site.

bIsCommerceSite

A Boolean that controls whether SQL Server and Oracle subdirectories are created for the site. When set to True, the method marks the site for administration by Site Server 3.0 Commerce Edition and creates the Directory\Config\SQL\SqlSvr and Directory\Config\SQL\Oracle subdirectories (where Directory is the value passed in the bstrDir parameter). When set to False, the method creates the top level Directory directory only.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

An AdminSite object must be initialized before most of its other methods can be called (the Create and IsValidName methods are exceptions). An object that has been created by the Create method of the AdminSite object is automatically initialized and does not need an explicit call to its Initialize method.

The valid characters and length for a Web site name are determined by the restrictions on the names of Microsoft SQL Server tables. In addition, a short name must not conflict with another short name on the server.

Before you actually create a site, use the IsValidName method to ensure that the short name of the site is valid. The name must conform to several rules for forming valid names in many environments. For example, Commerce Server appends the short name of a site to database tables and to generated pages.

Example

' oAdminSite is a Commerce.AdminSite object
' The szSite argument contains the site short name,
'  and szSiteRoot contains the physical directory.
AdminSite.Create ("1", szSite, NULL, szSiteRoot, true, true)

See Also

AdminSite Object

AdminSite.Delete

AdminSite:Initialize

AdminSite.IsValidName


AdminSite.Delete

Use this method to delete a Site Server 3.0 Commerce Edition site. The Delete method removes attributes of the site from the Internet Information Services (IIS) metabase (directories and databases are not removed).

Definition

Sub Delete()

Parameters

None.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

An AdminSite object must be initialized before most of its other methods can be called (the Create and IsValidName methods are exceptions). An object that has been created by the Create method of the AdminSite object is automatically initialized and does not need an explicit call to its Initialize method.

See Also

AdminSite Object

AdminSite.Create


AdminSite.Directory

The Directory property is a read/write string that contains the currently registered Site Server 3.0 Commerce Edition site physical directory.

Definition

Property Directory As String

Parameters

None.

Error Values

This property sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The valid characters and length for a Web site name are determined by the restrictions on the file system.

See Also

AdminSite Object

AdminSite.InitializeFromMDPath


AdminSite.Initialize

Use this method to initialize the AdminSite object so that information related to the Site Server 3.0 Commerce Edition site can be loaded. The site is uniquely identified using the site short name and the server instance. The ReadDefaultProperties method uses this information to load the site properties.

Definition

Sub Initialize(
bstrInstance As String,
bstrVDir As String
)

Parameters

bstrInstance

A numeric value, expressed as a String that represents a Web site.

bstrVDir

A String that contains the Site Server 3.0 Commerce Edition site short name (virtual directory).

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

You must initialize an AdminSite object before you can use any other methods of the object (except Create and IsValidName). An object created by the Create method of the AdminSite object is initialized automatically and does not need an explicit call to the Initialize method.

See Also

AdminSite Object

AdminSite.ReadDefaultProperties

AdminSite.Create

AdminSite.IsValidName


AdminSite.InitializeFromMDPath

Use this method to initialize the AdminSite object from a specified Internet Information Services (IIS) metabase path. The metabase path can be retrieved using a call to the Request.ServerVariables method.

Definition

Sub InitializeFromMDPath(
bstrMDPath As String
)

Parameters

bstrMDPath

A String that contains the metabase path. The metabase path can be retrieved using a call to the Request.ServerVariables method.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Unlike the Initialize method, which requires that a server instance and virtual directory be specified separately, this method requires a metabase path to be specified.

Example

' The following example initializes an AdminSite object
' for the application's metabase path:
' oAdmSite is a Commerce.AdminSite object
' The szSite argument contains the site short name,
'  and szSiteRoot contains the physical directory.
AdminSite.Create ("1", szSite, szSiteRoot, true, true)

Call oAdmSite.InitializeFromMDPath(Request.ServerVariables("APPL_MD_Path"))

' The Request.ServerVariables("APPL_MD_Path") expression returns
'  the metabase path in the form /LM/W3SVC/1/mySite , where
'  LM refers to the Local Machine, W3SVC refers to the
' Internet Service, 1 is the server instance, and mySite is the
' root of the Web site. This method works only if the application
' is created at the virtual directory (not a sub-directory).

See Also

AdminSite Object

AdminSite.Initialize


AdminSite.IsValidName

Use this method to determine the validity of a site name. The IsValidName method returns a value of True if the specified Site Server 3.0 Commerce Edition site short name is valid, and False otherwise.

Definition

Function IsValidName(
bstrName As String,
bstrInstance As String
) As Boolean

Parameters

bstrName

A String that specifies the short name to be tested.

bstrInstance

A String that specifies the Web server instance. To obtain a list of server instances, use the GetWebSites method. For the default Web site, use "1".

Return Values

If this method completes successfully, it returns a Boolean. A value of True indicates that the short site name is valid. A value of False indicates that the short site name is not valid.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The valid characters and length for a Web site name are determined by the restrictions on the names of Microsoft SQL Server tables. In addition, a short name must not conflict with any other short name on the server.

Before you actually create a site, use this method to ensure that the short name of the site is valid. The name must conform to several rules for forming valid names in many environments. For example, Commerce Server appends the short name of a site to database tables and to generated pages.

The IsValidName method of an object can be called without calling the Initialize or Create methods of the object.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oAdminSite is a Commerce.AdminSite object
' The szSite argument contains the site short name
' bResult is a Boolean
bResult = oAdminSite.IsValidName(szSite,"1")

See Also

AdminSite Object

AdminSite.Initialize


AdminSite.ReadDefaultProperties

Use this method to read the properties from the Site.csc file and return a site dictionary containing these properties.

Definition

Function ReadDefaultProperties() As Object

Parameters

None.

Return Values

If this method completes successfully, it returns a reference to a Dictionary object that contains the site properties read from the Site.csc file.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The Site.csc file for the Site Server 3.0 Commerce Edition site resides in the site\Config directory, and the Site.csc file for the manager site resides in the site\Manager\Config directory.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

AdminSite Object

AdminSite.WriteDefaultProperties

AdminSite.ReadManagerProperties

AdminSite.Initialize


AdminSite.ReadManagerProperties

Use this method to read the properties from the configuration file of the management page (site\Manager\Config\Site.csc) and to return a site dictionary containing these properties.

Definition

Function ReadManagerProperties() As Object

Parameters

None.

Return Values

If this method completes successfully, it returns a reference to a Dictionary object that contains the properties read from the configuration file of the management page.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The manager site dictionary properties are DefaultConnectionString and ConnectionStringMap. These properties are distinct from the corresponding properties in the main site configuration.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

AdminSite Object

AdminSite.WriteManagerProperties

AdminSite.ReadDefaultProperties


AdminSite.Reload

Use this method to reset all application and session objects for the Site Server 3.0 Commerce Edition site.

Definition

Sub Reload()

Parameters

None.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

After a reload, the next browser request will load the Global.asa file.

See Also

AdminSite Object


AdminSite.Status

The Status property is a read/write Boolean that indicates whether or not the Site Server 3.0 Commerce Edition site is open or closed. In addition, the Status property either opens or closes the Site Server 3.0 Commerce Edition site, when the value is set.

Definition

Property Status As Boolean

Parameters

None.

Error Values

This property sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Changing this property sets a value in the site configuration to the text "Open" or "Closed." When the site is reloaded, this value is read by the Global.asa file into the com_compref_frnc.htm value of the site Dictionary object. Each page in the Site Server 3.0 Commerce Edition site then determines whether or not to redirect the browser by checking the value of the Site.Status property. If the text does not equal "Open," then the browser is redirected to the address specified by the Site.CloseRedirectURL property.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

AdminSite Object


AdminSite.Version

The Version property is a read-only integer used to return the version of Site Server 3.0 Commerce Edition in use.

Definition

Property Version As Long

Parameters

None.

Error Values

This property sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

See Also

AdminSite Object


AdminSite.WriteDefaultProperties

Use this method to write the properties from the specified site Dictionary object to the Site.csc file.

Definition

Sub WriteDefaultProperties(
pIDictProp As Object
)

Parameters

pIDictProp

A reference to the Dictionary object that contains the properties to be written to the Site.csc file.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

See Also

AdminSite Object

AdminSite.ReadDefaultProperties

AdminSite.WriteManagerProperties


AdminSite.WriteManagerProperties

Use this method to write the properties from the specified site Dictionary object to the configuration file of the management page (site\Manager\Config\Site.csc).

Definition

Sub WriteManagerProperties(
pIDictProp As Object
)

Parameters

pIDictProp

A reference to a Dictionary object that contains the properties to be written to the configuration file management page.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The manager site dictionary properties are DefaultConnectionString and ConnectionStringMap. These properties are distinct from the corresponding properties in the main site configuration. This means that the password and user name information required to access site management pages can be different from those used in user pages.

See Also

AdminSite Object

AdminSite.ReadManagerProperties

AdminSite.WriteDefaultProperties


AdminWebServer Object

Use this object to enumerate all Web sites on a server, to obtain the properties of those Web sites, and to enumerate all Commerce sites on a Web site.

ProgID: | Commerce.AdminWebServer (Externally creatable)
COM Class Name: | AdminWebServer
Type Library Name: | Commerce Admin 1.0 Type Library
DLL Name: | MSCSadmin.dll
Threading Model: | Both

The methods of the AdminWebServer object are shown in the following table.

Method | Description
GetCommerceSites | Given a server instance of a Web Site, enumerates all Site Server 3.0 Commerce Edition sites under that Web site.
GetWebSiteProperties | Given a server instance, returns the properties of the site as name/value pairs in a Dictionary object.
GetWebSites | Enumerates all Web sites. Returns an array of numbers representing all Web sites (server instances).

Remarks

Active Server Pages (ASP) scripts that access the Microsoft Internet Information Services (IIS) metabase require administrator privileges on the computer on which IIS is running. When you execute these scripts from a remote computer, you must connect through a secure connection, such as the Microsoft Windows NT Challenge/Response Authentication method. You can create a server or directory for your administrative .asp files and set the directory security authentication method to Windows NT Challenge/Response for the server or directory.

See Also

Configuration Objects


AdminWebServer.GetCommerceSites

Use this method to enumerate all Commerce Server sites associated with the specified Web site. The method returns an array of numbers that represents all Commerce Server site instances.

This method does not work with Commerce Server 2000 sites. It is included only for backward compatibility with Site Server 3.0 Commerce Edition sites.

Definition

Function GetCommerceSites(
bstrInstance As String
) As Variant

Parameters

bstrInstance

A numeric value, expressed as a String, that represents a server instance for a site.

Return Values

This method returns a Variant that contains an array of numbers that represent all Commerce Server site instances.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The GetCommerceSites method determines whether a site is a Commerce Server site by examining a reserved key in the metabase.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oAdminWebServer is a Commerce.AdminWebServer object
' The following example enumerates all the Web sites on a server and
' displays the number of each server instance. Then for each Web site, it
' enumerates all the Commerce Server sites within that Web site:
' Create AdminWebServer object
Set objWebServer = CreateObject("Commerce.AdminWebserver")
' Get Web sites
WebSites = objWebServer.GetWebSites
For WebInstance = LBound(WebSites, 1) To UBound(WebSites, 1)
   ' For each web site, get all Commerce sites in an array of instances
        CommerceSites = objWebServer.GetCommerceSites(WebSites(WebInstance))
   ' Enumerate all Commerce sites
      For CSite = LBound(CommerceSites, 1) To UBound(CommerceSites, 1)
         Response.Write "<br>" + CommerceSites(CSite)
      Next
 Next

See Also

AdminWebServer Object


AdminWebServer.GetWebSiteProperties

Use this method to retrieve, given a server instance, the properties of a site as name/value pairs in a Dictionary object.

Definition

Function GetWebSiteProperties(
bstrInstance As String
) As Object

Parameters

bstrInstance

A numeric value, expressed as a String, representing a server instance for a site.

Return Values

This method returns a reference to a Dictionary object containing the properties of the specified site.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

<%
' Create AdminWebServer object
Set objWebServer = CreateObject("Commerce.AdminWebServer")

' Get Web sites
WebSites = objWebServer.GetWebSites
For WebInstance = LBound(WebSites, 1) To UBound(WebSites, 1)
    ' Return its properties in a dictionary
    Set objDict = objWebServer.GetWebSiteProperties(WebSites(WebInstance))

    ' Enumerate and display the dictionary
   For Each property in objDict
      Response.Write  property & " = " & objDict.value(property) & "<br>"
    next
Next

' Destroy objects
Set objDict = Nothing
Set objWebServer = Nothing
%>

See Also

AdminWebServer Object


AdminWebServer.GetWebSites

Use this method to enumerate all Web sites. The method returns an array of numbers that represent the server instance number for each Web site.

Definition

Function GetWebSites() As Variant

Parameters

None.

Return Values

This method returns a Variant containing an array of numbers representing all server instances.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The pvarInstances parameter contains valid data only if the method returns successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

AdminWebServer Object


AppConfig Object

Use this object to retrieve site configuration settings from the site configuration store. Also, use this object to retrieve the names and codes of various countries and regions from the site configuration store.

ProgID: | Commerce.AppConfig (Externally creatable)
COM Class Name: | AppCfg
Type Library Name: | Microsoft Commerce 2000 App Helper Type Library
DLL Name: | AppHelper.dll
Threading Model: | Both

The methods of the AppConfig object are shown in the following table.

Method | Description
DecodeStatusCode | Decodes the specified status code.
GetCountryCodeFromCountryName | Returns the country code for the specified country name.
GetCountryNameFromCountryCode | Returns the country name for the specified country code.
GetCountryNamesList | Returns an alphabetical list of country names.
GetOptionsDictionary | Returns a Dictionary object that maps site configuration keys to site configuration values.
GetRegionCodeFromCountryCodeAndRegionName | Returns the region code for the specified country code and region name.
GetRegionNameFromCountryCodeAndRegionCode | Returns the region name for the specified country code and region code.
GetRegionNamesListFromCountryCode | Returns an alphabetical list of region names for the specified country code.
Initialize | Initializes the AppConfig object.
RefreshCache | Refreshes the AppConfig object cache.

Remarks

This object is usually created once and initialized in the Global.asa file, for performance reasons. An instance of it is stored in the Application object and used on ASP pages as necessary.

The following example illustrates these steps:

Dim oAppConfig
Set oAppConfig = Server.CreateObject("Commerce.AppConfig")
Set Application("MSCSAppCfg") = oAppConfig

Country codes may or may not be the same as ISO Country codes, depending on what values have been added in the Business Desk.

See Also

Configuration Objects

Table of Country Names and Codes


AppConfig.DecodeStatusCode

Use this method to decode the specified status code.

Definition

Function DecodeStatusCode(
iStatusCode As Integer
) As String

Parameters

iStatusCode

An Integer that specifies the status code to be decoded.

Return Values

If this method completes successfully, it returns a String that contains the decoded status code. If the specified status code is not in the system, that same status code is returned.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Status codes are entered in the Commerce Server Business Desk.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

AppConfig Object


AppConfig.GetCountryCodeFromCountryName

Use this method to get the country code corresponding to the specified country name.

Definition

Function GetCountryCodeFromCountryName(
bstrCountryName As String
) As String

Parameters

bstrCountryName

A String that contains the name of the country for which the country code is being requested.

Return Values

If this method completes successfully, it returns a String that contains the country code. If the country code is not found, an empty string is returned.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

If the country code is not found, the method returns an empty string.

Country codes and country names may be set in Commerce Server Business Desk.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oAppConfig is a Commerce.AppConfig object
' sCode is a String
sCode = oAppConfig.GetCountryCodeFromCountryName("United States of _
America")

See Also

AppConfig Object

AppConfig.GetCountryNameFromCountryCode

AppConfig.GetCountryNamesList

Table of Country Names and Codes


AppConfig.GetCountryNameFromCountryCode

Use this method to get the country name corresponding to the specified country code.

Definition

Function GetCountryNameFromCountryCode(
bstrCountryCode As String
) As String

Parameters

bstrCountryCode

A String that contains the code of the country for which the country name is being requested.

Return Values

If this method completes successfully, it returns a String that contains the country name. If the name is not found, the country code is returned.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

If the country name is not found, the method returns the country code specified in the bstrCountryCode parameter.

Country codes and country names may be set in Commerce Server Business Desk.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

' oAppConfig is a Commerce.AppConfig object
' sCountryName is a String
sCountryName = oAppConfig.GetCountryNameFromCountryCode("us")

See Also

AppConfig Object

AppConfig.GetCountryCodeFromCountryName

AppConfig.GetCountryNamesList

Table of Country Names and Codes


AppConfig.GetCountryNamesList

Use this method to get an alphabetical list of the country names that are in the site configuration database.

Definition

Function GetCountryNamesList() As Object

Parameters

None.

Return Values

If this method completes successfully, it returns a reference to a SimpleList object. This object contains an alphabetical list of country names.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Country codes and country names may be set in Commerce Server Business Desk.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oAppConfig is a Commerce.AppConfig object
' listCountries is a SimpleList object
Set listCountries = oAppConfig.GetCountryNamesList()
For Each sCountry in listCountry
Response.Write sCountry
Next

See Also

AppConfig Object

AppConfig.GetCountryCodeFromCountryName

Table of Country Names and Codes


AppConfig.GetOptionsDictionary

Use this method to retrieve a Dictionary object that contains the site configuration information.

Definition

Function GetOptionsDictionary(
bstrUserID As String
) As Object

Parameters

bstrUserID

A String that contains an empty string ("").

Return Values

If this method completes successfully, it returns a reference to a Dictionary object that contains the site configuration information.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Some options dictionary keys, such as i_AuctionOptions, are reserved for future use. The following table lists the names of the keys in the Dictionary object returned by this method that are mapped in the Microsoft Management Console (MMC).

Programmatic Name | MMC Default Config Mapping
i_AddItemRedirectOptions | Add item redirect options
i_AddressBookOptions | Address Book Options
f_AltCurrencyConversionRate | Currency: Alternate currency conversion Rate
i_AltCurrencyLocale | Currency: Alternate currency locale
i_AltCurrencyOptions | Currency: Alternate currency options
i_BaseCurrencyLocale | Currency: Base currency locale
i_BillingOptions | Payment options: Billing options
i_BizTalkOptions | BizTalk Options
i_CookiePathCorrectionOptions | Cookie Path Correction Options
i_CurrencyDisplayOrderOptions | Currency: Currency display order options
i_DelegatedAdminOptions | Delegated admin options
i_FormLoginOptions | Form login options
i_FormLoginTimeOut | AuthManager Auth ticket Timeout
i_HostNameCorrectionOptions | Host Name Correction Options
i_PaymentOptions | Payment options
i_SitePrivacyOptions | Site privacy options
i_SiteRegistrationOptions | Site registration options
i_SiteTicketOptions | Site ticket options
s_AltCurrencySymbol | Currency: Alternate currency symbol
s_BaseCurrencySymbol | Currency: Base currency symbol
s_BizTalkCatalogDocType | BizTalk Catalog Doc Type
s_BizTalkConnString | BizTalk connection String
s_BizTalkOrderDocType | BizTalk PO Doc Type
s_BizTalkSourceQualifierID | BizTalk Source Org Qualifier
s_BizTalkSourceQualifierValue | BizTalk Org Qualifier Value
s_BizTalkSubmittypeQueue | BizTalk Submit type
s_PageEncodingCharset | Page encoding charset
s_SMTPServerName | SMTP server name
s_WeightMeasure | Unit of Measure for Weight

The following table lists keys in the Dictionary object returned by this method that are not mapped in the MMC.

Programmatic Name | Value or Description
i_IsFullTextSearchInstalled | Indicates whether SQL Server has full text search enabled
s_BizDataStoreConnectionString | Profile Service: s_BizDataStoreConnectionString
s_CampaignsConnectionString | Campaigns: connstr_db_Campaigns
s_CatalogConnectionString | Product Catalog: connstr_db_Catalog
s_CommerceProviderConnectionString | Profile Service: s_CommerceProviderConnectionString
s_NonSecureHostname | This value is set in the global.asa file to the non-secure host name of the application.
s_ProfileServiceConnectionString | Profile Service: s_ProfileServiceConnectionString
s_SecureHostname | This value is set in the global.asa file to the secure host name of the application.
s_SiteName | Name of the Site
s_TransactionConfigConnectionString | Transaction Config: connstr_db_TransactionConfig
s_TransactionsConnectionString | Transactions: connstr_db_Transactions

Example

' oAppConfig is a Commerce.AppConfig object
' dDictConfig is a Dictionary object
Set dictConfig = oAppConfig.GetOptionsDictionary("")
For Each sKey In dictConfig
    Response.Write sKey & "=" & dictConfig.Value(sKey)
Next

See Also

AppConfig Object


AppConfig.GetRegionCodeFromCountryCodeAndRegionName

Use this method to get a string that contains the region code for the specified country code and region name.

Definition

Function GetRegionCodeFromCountryCodeAndRegionName(
bstrCountryCode As String,
bstrRegionName As String
) As String

Parameters

bstrCountryCode

A String that contains the code of the country for which the region code is being requested.

bstrRegionName

A String that contains the name of the region within the specified country for which the region code is being requested.

Return Values

If this method completes successfully, it returns a String that contains the requested region code. An empty String indicates that the code was not found.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

This method returns an empty string if the region code was not found.

Country codes, country names, region codes, and region names may be set in Commerce Server Business Desk.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oAppCfg is a Commerce.AppConfig object, sResult is a string
sResult = oAppCfg.GetRegionCodeFromCountryCodeAndRegionName("us", "Utah")

See Also

AppConfig Object

AppConfig.GetCountryCodeFromCountryName

AppConfig.GetCountryNamesList

AppConfig.GetRegionNameFromCountryCodeAndRegionCode

AppConfig.GetRegionNamesListFromCountryCode

Table of Country Names and Codes


AppConfig.GetRegionNameFromCountryCodeAndRegionCode

Use this method to get the name of the region associated with the specified country code and region code.

Definition

Function GetRegionNameFromCountryCodeAndRegionCode(
bstrCountryCode As String,
bstrRegionCode As String
) As String

Parameters

bstrCountryCode

A String that contains the code of the country for which the region name is being requested.

bstrRegionCode

A String that contains the code of the region within the specified country for which the region name is being requested.

Return Values

If this method completes successfully, it returns a String that contains the region name. If the region name is not found, the String will contain the region code specified in the bstrRegionCode parameter.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

If the region name is not found, this method returns the region code specified in the bstrRegionCode parameter.

Country codes, country names, region codes, and region names may be set in Commerce Server Business Desk.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oAppCfg is a Commerce.AppConfig object, sResult is a String
sResult = oAppCfg.GetRegionNameFromCountryCodeAndRegionCode("us", "UT")

See Also

AppConfig Object

AppConfig.GetCountryCodeFromCountryName

AppConfig.GetCountryNamesList

AppConfig.GetRegionCodeFromCountryCodeAndRegionName

AppConfig.GetRegionNamesListFromCountryCode

Table of Country Names and Codes


AppConfig.GetRegionNamesListFromCountryCode

Use this method to retrieve an alphabetical list of region names associated with a specified country code.

Definition

Function GetRegionNamesListFromCountryCode(
bstrCountryCode As String
) As Object

Parameters

bstrCountryCode

A String that contains the code of the country for which a list of region names is being requested.

Return Values

If this method completes successfully, it returns a reference to a SimpleList object that contains an alphabetical list of region names associated with the specified country code.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Country codes, country names, region codes, and region names may be set in Commerce Server Business Desk.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oAppCfg is a Commerce.AppConfig object
' listRegions is a SimpleList object
Set listRegions = oAppConfig.GetRegionNamesListFromCountryCode("us")
For Each sRegion In listRegions
  Response.Write sRegion
Next
' The above example will provide a list of USA state names

See Also

AppConfig Object

AppConfig.GetCountryCodeFromCountryName

AppConfig.GetCountryNamesList

AppConfig.GetRegionCodeFromCountryCodeAndRegionName

Table of Country Names and Codes


AppConfig.Initialize

Use this method to initialize an AppConfig object.

Definition

Sub Initialize(
bstrSiteName As String
)

Parameters

bstrSiteName

A String that contains the name of the site with which this AppConfig object should be associated. This name is not case-sensitive.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The AppConfig object must be initialized before any other method on this object can be used. The initialization usually happens only once in Global.asa immediately after the object is created.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oAppCfg is a Commerce.AppConfig object
oAppCfg.Initialize("Retail")

See Also

AppConfig Object

AppConfig.RefreshCache


AppConfig.RefreshCache

Use this method to refresh the cache associated with the AppConfig object.

Definition

Sub RefreshCache()

Parameters

None.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Users can add and change country and region codes and other values from within Commerce Server Business Desk; the RefreshCache method allows you to programmatically incorporate those changes at any time.

See Also

AppConfig Object

AppConfig.Initialize


Table of Country Names and Codes

Country codes may or may not be the same as ISO Country codes, depending on what values have been added in the Business Desk. The following table contains country names with their corresponding codes.

Official Short Form | Official Long Form | ISO Code | ISO Short | ISO Long | UN Code | Capital/Major City
Afghanistan | Islamic State of Afghanistan | 4 | AF | AFG | 4 | Kâbul
Albania | Republic of Albania | 8 | AL | ALB | 8 | Tirana
Algeria | Democratic and Popular Republic of Algeria | 12 | DZ | DZA | 12 | Algiers
American Samoa | Territory of American Samoa | 16 | AS | ASM | 16 |
Andorra | Principality of Andorra | 20 | AD | AND | 20 | Andorra la Vella
Angola | Republic of Angola | 24 | AO | AGO | 24 | Luanda
Anguilla |  | 660 | AI | AIA | 660 |
Antarctica |  | 10 | AQ | ATA | 10 |
Antigua and Barbuda | Antigua and Barbuda | 28 | AG | ATG | 28 | St. John's
Argentina | Argentine Republic | 32 | AR | ARG | 32 | Buenos Aires
Armenia | Republic of Armenia | 51 | AM | ARM | 51 | Yerevan
Aruba |  | 533 | AW | ABW | 533 |
Australia | Commonwealth of Australia | 36 | AU | AUS | 36 | Canberra
Austria | Republic of Austria | 40 | AT | AUT | 40 | Vienna
Azerbaijan | Azerbaijani Republic | 31 | AZ | AZE | 31 | Baku
Bahamas, The | The Commonwealth of The Bahamas | 44 | BS | BHS | 44 | Nassau
Bahrain | State of Bahrain | 48 | BH | BHR | 48 | Manama
Bangladesh | People's Republic of Bangladesh | 50 | BD | BGD | 50 | Dhaka
Barbados |  | 52 | BB | BRB | 52 | Bridgetown
Belarus | Republic of Belarus | 112 | BY | BLR | 112 | Minsk
Belgium | Kingdom of Belgium | 56 | BE | BEL | 56 | Brussels
Belize |  | 84 | BZ | BLZ | 84 | Belmopan
Benin | Republic of Benin | 204 | BJ | BEN | 204 | Porto-Novo
Bermuda |  | 60 | BM | BMU | 60 |
Bhutan | Kingdom of Bhutan | 64 | BT | BTN | 64 | Thimphu
Bolivia | Republic of Bolivia | 68 | BO | BOL | 68 | Sucre
Bosnia and Herzegovina | Republic of Bosnia and Herzegovina | 70 | BA | BIH | 70 | Sarajevo
Botswana | Republic of Botswana | 72 | BW | BWA | 72 | Gaborone
Bouvet Island |  | 74 | BV | BVT | - |
Brazil | Federative Republic of Brazil | 76 | BR | BRA | 76 | Brasília
British Indian Ocean Territory | British Indian Ocean Territory | 86 | IO | IOT | - |
Brunei | Negara Brunei Darussalam | 96 | BN | BRN | 96 | Bandar seri Begawan
Bulgaria | Republic of Bulgaria | 100 | BG | BGR | 100 | Sofia
Burkina Faso |  | 854 | BF | BFA | 854 | Ouagadougou
Burundi | Republic of Burundi | 108 | BI | BDI | 108 | Bujumbura
Côte d'Ivoire | Republic of Côte d'Ivoire | 384 | CI | CIV | 384 | Yamoussoukro
Cambodia | Kingdom of Cambodia | 116 | KH | KHM | 116 | Phnom Penh
Cameroon | Republic of Cameroon | 120 | CM | CMR | 120 | Yaoundé
Canada |  | 124 | CA | CAN | 124 | Ottawa
Cape Verde | Republic of Cape Verde | 132 | CV | CPV | 132 | Praia
Cayman Islands |  | 136 | KY | CYM | 136 |
Central African Republic | Central African Republic | 140 | CF | CAF | 140 | Bangui
Chad | Republic of Chad | 148 | TD | TCD | 148 | N'Djamena
Channel Islands |  | - | GB-CHA | - | 830 |
Chile | Republic of Chile | 152 | CL | CHL | 152 | Santiago
China | People's Republic of China | 156 | CN | CHN | 156 | Beijing
Christmas Island | Territory of Christmas Island | 162 | CX | CXR | - |
Cocos (Keeling) Islands | Territory of Cocos (Keeling) Islands | 166 | CC | CCK | - |
Colombia | Republic of Colombia | 170 | CO | COL | 170 | Santa Fe de Bogotá
Comoros | Federal Islamic Republic of the Comoros | 174 | KM | COM | 174 | Moroni
Congo | Republic of the Congo | 178 | CG | COG | 178 | Brazzaville
Congo (DRC) | Democratic Republic of the Congo | 180 | CD | COD | 180 | Kinshasa
Cook Islands |  | 184 | CK | COK | 184 |
Coral Sea Islands | Coral Sea Islands Territory | - | AU | - | - |
Costa Rica | Republic of Costa Rica | 188 | CR | CRI | 188 | San José
Croatia | Republic of Croatia | 191 | HR | HRV | 191 | Zagreb
Cuba | Republic of Cuba | 192 | CU | CUB | 192 | Havana
Cyprus | Republic of Cyprus | 196 | CY | CYP | 196 | Nicosia
Czech Republic | Czech Republic | 203 | CZ | CZE | 203 | Prague
Denmark | Kingdom of Denmark | 208 | DK | DNK | 208 | Copenhagen
Djibouti | Republic of Djibouti | 262 | DJ | DJI | 262 | Djibouti
Dominica | Commonwealth of Dominica | 212 | DM | DMA | 212 | Roseau
Dominican Republic | Dominican Republic | 214 | DO | DOM | 214 | Santo Domingo
East Timor |  | 626 | TP | TMP | 626 | Dili
Ecuador | Republic of Ecuador | 218 | EC | ECU | 218 | Quito
Egypt | Arab Republic of Egypt | 818 | EG | EGY | 818 | Cairo
El Salvador | Republic of El Salvador | 222 | SV | SLV | 222 | San Salvador
Equatorial Guinea | Republic of Equatorial Guinea | 226 | GQ | GNQ | 226 | Malabo
Eritrea | State of Eritrea | 232 | ER | ERI | 232 | Asmara
Estonia | Republic of Estonia | 233 | EE | EST | 233 | Tallinn
Ethiopia | Federal Democratic Republic of Ethiopia | 231 | ET | ETH | 231 | Addis Ababa
Falkland Islands (Islas Malvinas) | Colony of the Falkland Islands | 238 | FK | FLK | 238 |
Faroe Islands |  | 234 | FO | FRO | 234 |
Fiji Islands | Republic of the Fiji Islands | 242 | FJ | FJI | 242 | Suva
Finland | Republic of Finland | 246 | FI | FIN | 246 | Helsinki
France | French Republic | 250 | FR | FRA | 250 | Paris
France, Metropolitan |  | 249 | FX | FXX | - |
French Guiana | Department of Guiana | 254 | GF | GUF | 254 |
French Polynesia | Territory of French Polynesia | 258 | PF | PYF | 258 |
French Southern and Antarctic Lands | Territory of the French Southern and Antarctic Lands | 260 | TF | ATF | - |
Gabon | Gabonese Republic | 266 | GA | GAB | 266 | Libreville
Gambia, The | Republic of The Gambia | 270 | GM | GMB | 270 | Banjul
Gaza Strip |  | - | PS | PSE | 275 |
Georgia | Republic of Georgia | 268 | GE | GEO | 268 | T'bilisi
Germany | Federal Republic of Germany | 276 | DE | DEU | 276 | Berlin
Ghana | Republic of Ghana | 288 | GH | GHA | 288 | Accra
Gibraltar |  | 292 | GI | GIB | 292 |
Greece | Hellenic Republic | 300 | GR | GRC | 300 | Athens
Greenland |  | 304 | GL | GRL | 304 |
Grenada |  | 308 | GD | GRD | 308 | St. George's
Guadeloupe | Department of Guadeloupe | 312 | GP | GLP | 312 |
Guam | Territory of Guam | 316 | GU | GUM | 316 |
Guatemala | Republic of Guatemala | 320 | GT | GTM | 320 | Guatemala
Guernsey | Balliwick of Guernsey | - | GB-GSY | - | - |
Guinea | Republic of Guinea | 324 | GN | GIN | 324 | Conakry
Guinea-Bissau | Republic of Guinea-Bissau | 624 | GW | GNB | 624 | Bissau
Guyana | Cooperative Republic of Guyana | 328 | GY | GUY | 328 | Georgetown
Haiti | Republic of Haiti | 332 | HT | HTI | 332 | Port-au-Prince
Heard Island and McDonald Islands | Territory of Heard Island and McDonald Islands | 334 | HM | HMD | - |
Honduras | Republic of Honduras | 340 | HN | HND | 340 | Tegucigalpa
Hong Kong SAR | Hong Kong Special Administrative Region | 344 | HK | HKG | 344 |
Hungary | Republic of Hungary | 348 | HU | HUN | 348 | Budapest
Iceland | Republic of Iceland | 352 | IS | ISL | 352 | Reykjavík
India | Republic of India | 356 | IN | IND | 356 | New Delhi
Indonesia | Republic of Indonesia | 360 | ID | IDN | 360 | Jakarta
Iran | Islamic Republic of Iran | 364 | IR | IRN | 364 | Tehran
Iraq | Republic of Iraq | 368 | IQ | IRQ | 368 | Baghdad
Ireland | Republic of Ireland | 372 | IE | IRL | 372 | Dublin
Israel | State of Israel | 376 | IL | ISR | 376 | Jerusalem
Italy | Italian Republic | 380 | IT | ITA | 380 | Rome
Jamaica |  | 388 | JM | JAM | 388 | Kingston
Japan |  | 392 | JP | JPN | 392 | Tokyo
Jersey | Balliwick of Jersey | - | GB-JSY | - | - |
Jordan | Hashemite Kingdom of Jordan | 400 | JO | JOR | 400 | Amman
Kazakhstan | Republic of Kazakhstan | 398 | KZ | KAZ | 398 | Astana
Kenya | Republic of Kenya | 404 | KE | KEN | 404 | Nairobi
Kiribati | Republic of Kiribati | 296 | KI | KIR | 296 | Bairiki
Korea | Republic of Korea | 410 | KR | KOR | 410 | Seoul
Kuwait | State of Kuwait | 414 | KW | KWT | 414 | Kuwait
Kyrgyzstan | Kyrgyz Republic | 417 | KG | KGZ | 417 | Bishkek
Laos | Lao People's Democratic Republic | 418 | LA | LAO | 418 | Vientiane
Latvia | Republic of Latvia | 428 | LV | LVA | 428 | Riga
Lebanon | Republic of Lebanon | 422 | LB | LBN | 422 | Beirut
Lesotho | Kingdom of Lesotho | 426 | LS | LSO | 426 | Maseru
Liberia | Republic of Liberia | 430 | LR | LBR | 430 | Monrovia
Libya | Socialist People's Libyan Arab Jamahiriya | 434 | LY | LBY | 434 | Tripoli
Liechtenstein | Principality of Liechtenstein | 438 | LI | LIE | 438 | Vaduz
Lithuania | Republic of Lithuania | 440 | LT | LTU | 440 | Vilnius
Luxembourg | Grand Duchy of Luxembourg | 442 | LU | LUX | 442 | Luxembourg
Macau SAR | Macau Special Administrative Region | 446 | MO | MAC | 446 |
Macedonia, Former Yugoslav Republic of | The Former Yugoslav Republic of Macedonia | 807 | MK | MKD | 807 | Skopje
Madagascar | Republic of Madagascar | 450 | MG | MDG | 450 | Antananarivo
Malawi | Republic of Malawi | 454 | MW | MWI | 454 | Lilongwe
Malaysia | Federation of Malaysia | 458 | MY | MYS | 458 | Kuala Lumpur
Maldives | Republic of Maldives | 462 | MV | MDV | 462 | Malé
Mali | Republic of Mali | 466 | ML | MLI | 466 | Bamako
Malta | Republic of Malta | 470 | MT | MLT | 470 | Valletta
Man, Isle of |  | - | GB-IOM | - | 833 |
Marshall Islands | Republic of the Marshall Islands | 584 | MH | MHL | 584 | Majuro
Martinique | Department of Martinique | 474 | MQ | MTQ | 474 |
Mauritania | Islamic Republic of Mauritania | 478 | MR | MRT | 478 | Nouakchott
Mauritius | Republic of Mauritius | 480 | MU | MUS | 480 | Port Louis
Mayotte | Territorial Collectivity of Mayotte | 175 | YT | MYT | - |
Mexico | United Mexican States | 484 | MX | MEX | 484 | Mexico City
Micronesia | Federated States of Micronesia | 583 | FM | FSM | 583 | Palikir
Moldova | Republic of Moldova | 498 | MD | MDA | 498 | Chiºinãu
Monaco | Principality of Monaco | 492 | MC | MCO | 492 | Monaco
Mongolia |  | 496 | MN | MNG | 496 | Ulaanbaatar
Montserrat |  | 500 | MS | MSR | 500 |
Morocco | Kingdom of Morocco | 504 | MA | MAR | 504 | Rabat
Mozambique | Republic of Mozambique | 508 | MZ | MOZ | 508 | Maputo
Myanmar | Union of Myanmar | 104 | MM | MMR | 104 | Yangon (Rangoon)
Namibia | Republic of Namibia | 516 | NA | NAM | 516 | Windhoek
Nauru | Republic of Nauru | 520 | NR | NRU | 520 | Yaren
Nepal | Kingdom of Nepal | 524 | NP | NPL | 524 | Kathmandu
Netherlands Antilles |  | 530 | AN | ANT | 530 |
Netherlands, The | Kingdom of the Netherlands | 528 | NL | NLD | 528 | Amsterdam
New Caledonia | Territory of New Caledonia and Dependencies | 540 | NC | NCL | 540 |
New Zealand |  | 554 | NZ | NZL | 554 | Wellington
Nicaragua | Republic of Nicaragua | 558 | NI | NIC | 558 | Managua
Niger | Republic of Niger | 562 | NE | NER | 562 | Niamey
Nigeria | Federal Republic of Nigeria | 566 | NG | NGA | 566 | Abuja
Niue |  | 570 | NU | NIU | 570 |
Norfolk Island | Territory of Norfolk Island | 574 | NF | NFK | 574 |
North Korea | Democratic People's Republic of Korea | 408 | KP | PRK | 408 | Pyongyang
Northern Mariana Islands | Commonwealth of the Northern Mariana Islands | 580 | MP | MNP | 580 |
Norway | Kingdom of Norway | 578 | NO | NOR | 578 | Oslo
Oman | Sultanate of Oman | 512 | OM | OMN | 512 | Masqaþ
Pakistan | Islamic Republic of Pakistan | 586 | PK | PAK | 586 | Islâmâbâd
Palau | Republic of Palau | 585 | PW | PLW | 585 | Koror
Panama | Republic of Panama | 591 | PA | PAN | 591 | Panama City
Papua New Guinea | Independent State of Papua New Guinea | 598 | PG | PNG | 598 | Port Moresby
Paraguay | Republic of Paraguay | 600 | PY | PRY | 600 | Asunción
Peru | Republic of Peru | 604 | PE | PER | 604 | Lima
Philippines | Republic of the Philippines | 608 | PH | PHL | 608 | Manila
Pitcairn Islands | Pitcairn, Henderson, Ducie, and Oeno Islands | 612 | PN | PCN | 612 |
Poland | Republic of Poland | 616 | PL | POL | 616 | Warsaw
Portugal | Portuguese Republic | 620 | PT | PRT | 620 | Lisbon
Puerto Rico | Commonwealth of Puerto Rico | 630 | PR | PRI | 630 |
Qatar | State of Qatar | 634 | QA | QAT | 634 | Doha
Reunion | Department of Reunion | 638 | RE | REU | 638 |
Romania |  | 642 | RO | ROM | 642 | Bucharest
Russia | Russian Federation | 643 | RU | RUS | 643 | Moscow
Rwanda | Rwandese Republic | 646 | RW | RWA | 646 | Kigali
São Tomé and Príncipe | Democratic Republic of São Tomé and Príncipe | 678 | ST | STP | 678 | São Tomé
Samoa | Independent State of Samoa | 882 | WS | WSM | 882 | Apia
San Marino | Republic of San Marino | 674 | SM | SMR | 674 | San Marino
Saudi Arabia | Kingdom of Saudi Arabia | 682 | SA | SAU | 682 | Riyadh
Senegal | Republic of Senegal | 686 | SN | SEN | 686 | Dakar
Seychelles | Republic of Seychelles | 690 | SC | SYC | 690 | Victoria
Sierra Leone | Republic of Sierra Leone | 694 | SL | SLE | 694 | Freetown
Singapore | Republic of Singapore | 702 | SG | SGP | 702 | Singapore
Slovakia | Slovak Republic | 703 | SK | SVK | 703 | Bratislava
Slovenia | Republic of Slovenia | 705 | SI | SVN | 705 | Ljubljana
Solomon Islands |  | 90 | SB | SLB | 90 | Honiara
Somalia | Somali Democratic Republic | 706 | SO | SOM | 706 | Mogadishu
South Africa | Republic of South Africa | 710 | ZA | ZAF | 710 | Pretoria
South Georgia and the South Sandwich Islands | South Georgia and the South Sandwich Islands | 239 | GS | SGS | - |
Spain | Kingdom of Spain | 724 | ES | ESP | 724 | Madrid
Sri Lanka | Democratic Socialist Republic of Sri Lanka | 144 | LK | LKA | 144 | Sri Jayawardenepura
St. Helena | Saint Helena | 654 | SH | SHN | 654 |
St. Kitts and Nevis | Federation of Saint Kitts and Nevis | 659 | KN | KNA | 659 | Basseterre
St. Lucia | Saint Lucia | 662 | LC | LCA | 662 | Castries
St. Pierre and Miquelon | Territorial Collectivity of Saint Pierre and Miquelon | 666 | PM | SPM | 666 |
St. Vincent and the Grenadines | Saint Vincent and the Grenadines | 670 | VC | VCT | 670 | Kingstown
Sudan | Republic of the Sudan | 736 | SD | SDN | 736 | Khartoum
Suriname | Republic of Suriname | 740 | SR | SUR | 740 | Paramaribo
Svalbard and Jan Mayen |  | 744 | SJ | SJM | 744 |
Swaziland | Kingdom of Swaziland | 748 | SZ | SWZ | 748 | Mbabane
Sweden | Kingdom of Sweden | 752 | SE | SWE | 752 | Stockholm
Switzerland | Swiss Confederation | 756 | CH | CHE | 756 | Bern
Syria | Syrian Arab Republic | 760 | SY | SYR | 760 | Damascus
Taiwan |  | 158 | TW | TWN | 158 | Taipei
Tajikistan | Republic of Tajikistan | 762 | TJ | TJK | 762 | Dushanbe
Tanzania | United Republic of Tanzania | 834 | TZ | TZA | 834 | Dar es Salaam
Thailand | Kingdom of Thailand | 764 | TH | THA | 764 | Bangkok
Togo | Togolese Republic | 768 | TG | TGO | 768 | Lomé
Tokelau |  | 772 | TK | TKL | 772 |
Tonga | Kingdom of Tonga | 776 | TO | TON | 776 | Nuku'alofa
Trinidad and Tobago | Republic of Trinidad and Tobago | 780 | TT | TTO | 780 | Port-of-Spain
Tunisia | Republic of Tunisia | 788 | TN | TUN | 788 | Tunis
Turkey | Republic of Turkey | 792 | TR | TUR | 792 | Ankara
Turkmenistan | Republic of Turkmenistan | 795 | TM | TKM | 795 | Ashgabat
Turks and Caicos Islands |  | 796 | TC | TCA | 796 |
Tuvalu |  | 798 | TV | TUV | 798 | Funafuti
U.S. Minor Outlying Islands | United States Minor Outlying Islands | 581 | UM | UMI | 581 |
Uganda | Republic of Uganda | 800 | UG | UGA | 800 | Kampala
Ukraine |  | 804 | UA | UKR | 804 | Kyiv
United Arab Emirates |  | 784 | AE | ARE | 784 | Abu Dhabi
United Kingdom | United Kingdom of Great Britain and Northern Ireland | 826 | GB | GBR | 826 | London
United States | United States of America | 840 | US | USA | 840 | Washington, D.C.
Uruguay | Oriental Republic of Uruguay | 858 | UY | URY | 858 | Montevideo
Uzbekistan | Republic of Uzbekistan | 860 | UZ | UZB | 860 | Toshkent
Vanuatu | Republic of Vanuatu | 548 | VU | VUT | 548 | Port-Vila
Vatican City | State of Vatican City | 336 | VA | VAT | 336 | Vatican City
Venezuela | Bolivarian Republic of Venezuela | 862 | VE | VEN | 862 | Caracas
Viet Nam | Socialist Republic of Vietnam | 704 | VN | VNM | 704 | Hanoi
Virgin Islands | Virgin Islands of the United States | 850 | VI | VIR | 850 |
Virgin Islands, British |  | 92 | VG | VGB | 92 |
Wallis and Futuna | Territory of the Wallis and Futuna Islands | 876 | WF | WLF | 876 |
Yemen | Republic of Yemen | 887 | YE | YEM | 887 | Sana'a
Yugoslavia | Federal Republic of Yugoslavia | 891 | YU | YUG | 891 | Belgrade
Zambia | Republic of Zambia | 894 | ZM | ZMB | 894 | Lusaka
Zimbabwe | Republic of Zimbabwe | 716 | ZW | ZWE | 716 | Harare


AppFrameWork Object

Use this object to simplify forms processing in Active Server Pages (ASP).

ProgID: | Commerce.AppFrameWork (Externally creatable)
COM Class Name: | AppFrameWork
Type Library Name: | AspLib 1.0 Type Library
DLL Name: | asplib.dll
Threading Model: | Both

The methods of the AppFrameWork object are shown in the following table.

Method | Description
Option | Generates an option tag on a page.
RequestDate | Retrieves a value from a URL query string or form post variable and converts it to a Date value (Date Variant).
RequestDateTime | Retrieves a value from a URL query string or form post variable and converts it to a DateTime value (Date Variant).
RequestFloat | Retrieves a value from a URL query string or form post variable and converts it to a floating-point value.
RequestMoneyAsNumber | Retrieves a value from a URL query string or form post variable and converts it as money, based on the specified locale.
RequestNumber | Retrieves a value from a URL query string or form post variable and converts it to a number.
RequestString | Retrieves a value from a URL query string or form post variable and performs string processing on it.
RequestTime | Retrieves a value from a URL query string or form post variable and converts it to a Time value (Date Variant).
VerifyWith | Generates hidden input fields that contain verification values.
VirtualDirectory | Returns the name of the virtual directory for the site.

Remarks

The AppFrameWork object methods fall mainly into the following categories:

  • Formatting. The Option method makes it possible for you to easily format HTML page items, and where applicable, to determine HTML item values based upon a run time evaluation of other variables used in your page.

  • Validation. These methods begin with Request, and are used to retrieve values from a URL query string, convert the values to given data types based on a locale value, and validate these values against a specified range.

Before you create this object, you must create the Commerce.DataFunctions object in Application scope.

See Also

Display Objects


AppFrameWork.Option

Use this method to generate an OPTION item in an HTML form selection list with the value and selection state that you specify.

Definition

Function Option(
vtVal1 As Variant,
vtVal2 As Variant
) As String

Parameters

vtVal1

A Variant that contains the value of the option in the selection list.

vtVal2

A Variant that contains a value that indicates whether the list option is the selected option. If the vtVal2 parameter is equal to the vtVal1 parameter, then the HTML keyword SELECTED is inserted in the definition of the option list.

Return Values

If this method completes successfully, it returns a String that contains the OPTION item.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oAppFrameWork is a Commerce.AppFrameWork object.
' The following example generates a selection field in an
' HTML form to enable the customer to select the expiration
' year of their credit card. The Option method generates
' <OPTION VALUE="> tags and marks the current year
' as selected:
<% iyear = Year(date) %>

<SELECT NAME="_cc_expyear">
    <% = oAppFrameWork.Option(2000, iyear) %> 2000
    <% = oAppFrameWork.Option(2001, iyear) %> 2001
    <% = oAppFrameWork.Option(2002, iyear) %> 2002
    <% = oAppFrameWork.Option(2003, iyear) %> 2003
</SELECT>
' Following is the HTML output that is produced,
' assuming that the current year is 2001:
<SELECT NAME="_cc_expyear">
    <OPTION VALUE="2000"> 2000
    <OPTION VALUE="2001" SELECTED> 2001
    <OPTION VALUE="2002"> 2002
    <OPTION VALUE="2003"> 2003
</SELECT>

See Also

AppFrameWork Object


AppFrameWork.RequestDate

Use this method to retrieve a value from a URL query string or form post variable and convert it to a Date value (Date Variant), based on the specified or default locale.

Definition

Function RequestDate(
bstrName As String,
Optional vtDefault As Variant,
Optional vtMin As Variant,
Optional vtMax As Variant,
Optional vtLocale As Variant
) As Variant

Parameters

bstrName

A String that contains the name of the URL query string or form post variable to retrieve.

vtDefault

A Variant that contains the date to return if the requested URL query string or form post variable does not exist or contains no value. If this parameter is not supplied, the method returns NULL. The default cannot contain DateTime or Time values. This parameter is optional.

vtMin

A Variant that contains a date value that specifies the low end of the range against which to validate the value of the bstrName parameter. The default value is NULL, indicating that this parameter is ignored. If the converted value is less than vtMin, then NULL is returned. This parameter is optional.

vtMax

A Variant that contains a date value that specifies the high end of the range against which to validate the value of the bstrName parameter. The default value is NULL, indicating that this parameter is ignored. If the converted value is greater than vtMax, then NULL is returned. This parameter is optional.

vtLocale

A Variant that that contains a number that specifies the locale to use to convert the date. If this value is not specified, the RequestDate method uses the value of the Locale property of the DataFunctions object. This parameter is optional.

Return Values

If this method completes successfully, it returns a Date Variant that contains the processed date value. If any validation fails, the return value will be NULL.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

This method converts the specified String based on the locale specified in the vtLocale parameter if the vtLocale parameter is specified; otherwise it uses the default locale found in the DataFunctions object. It validates the result of the conversion against the vtMin and vtMax parameters, if they are specified. If the validation fails this method returns NULL.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oAppFrameWork is a Commerce.AppFrameWork object.
' This example assumes that the date value is entered using
' the following form:
<FORM METHOD ="POST" ACTION="PROCESS.ASP">
<INPUT TYPE="Text" NAME="Date">
<INPUT TYPE="SUBMIT" NAME="ACTION" VALUE="Send Info">
</FORM>
' If the user enters the date into the form and clicks the
' Send Info button, the value of this form field can be
' retrieved by the RequestDate method as follows:
vDate = oAppFrameWork.RequestDate("Date", "2/27/01", "1/1/01", _
    "12/31/01",1033)

See Also

AppFrameWork Object

DataFunctions.Locale

AppFrameWork.RequestDateTime

DataFunctions.ConvertDateString

DataFunctions.Date


AppFrameWork.RequestDateTime

Use this method to retrieve a value from a URL query string or form post variable and convert it to a DateTime value (Date Variant), based on the specified or default locale.

Definition

Function RequestDateTime(
bstrName As String,
Optional vtDefault As Variant,
Optional vtMin As Variant,
Optional vtMax As Variant,
Optional vtLocale As Variant
) As Variant

Parameters

bstrName

A String that contains the name of the URL query string or form post variable to retrieve.

vtDefault

A Variant that contains the value to return if the requested URL query string or form post variable does not exist or contains no value. If this parameter is not supplied, the method returns NULL. The default cannot contain Time values. This parameter is optional.

vtMin

A Variant that contains a DateTime value that specifies the low end of the range against which to validate the value of the bstrName parameter. The default value is NULL, indicating that this parameter is ignored. If the converted value is less than vtMin, then NULL is returned. This parameter is optional.

vtMax

A Variant that contains a DateTime value that specifies the high end of the range against which to validate the value of the bstrName parameter. The default value is NULL, indicating that this parameter is ignored. If the converted value is greater than vtMax, then NULL is returned. This parameter is optional.

vtLocale

A Variant that contains the number that identifies the locale to be used to convert the date/time string. If this parameter is not specified, the RequestDateTime method uses the value of the Locale property of the DataFunctions object. This parameter is optional.

Return Values

If this method completes successfully, it returns a Variant that contains a DateTime value. If any validation fails, the return value will be NULL.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

This method converts the specified String based on the locale specified in the vtLocale parameter if the vtLocale parameter is specified; otherwise it uses the default locale found in the DataFunctions object. It validates the result of the conversion against the vtMin and vtMax parameters, if they are specified. If the validation fails this method returns NULL.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oAppFrameWork is a Commerce.AppFrameWork object.
' This example assumes that the DateTime value is entered using
' the following form:
<FORM METHOD ="POST" ACTION="PROCESS.ASP">
<INPUT TYPE="Text" NAME="DateTime">
<INPUT TYPE="SUBMIT" NAME="ACTION" VALUE="Send Info">
</FORM>
' If the user enters the date into the form and clicks
' the Send Info button, the value of this form field can
' be retrieved by the RequestDate method as follows:
vDate = oAppFrameWork.RequestDateTime("DateTime", _
    "1/1/01 12:00:01 AM", "1/1/01 12:00:01 AM", _
     "12/31/01 11:59:59 PM", 1033)

See Also

AppFrameWork Object

DataFunctions.Locale

AppFrameWork.RequestDate

DataFunctions.ConvertDateTimeString

AppFrameWork.RequestTime


AppFrameWork.RequestFloat

Use this method to retrieve a value from a URL query string or form post variable and convert it to a floating-point value, based on the specified or default locale.

Optionally, the RequestFloat method also checks the converted number against the specified range.

Definition

Function RequestFloat(
bstrName As String,
Optional vtDefault As Variant,
Optional vtMin As Variant,
Optional vtMax As Variant,
Optional vtLocale As Variant
) As Variant

Parameters

bstrName

A String that contains the name of the URL query string or form post variable to retrieve.

vtDefault

A Variant that contains the value to return if the requested URL query string or form post variable is not present or contains no value. If this parameter is not supplied, the method returns NULL. This parameter is optional.

vtMin

A Variant that contains the number that specifies the low end of the range of values against which to validate the converted value. The default value is NULL, indicating that this parameter is ignored. If the converted value is less than vtMin, then NULL is returned. This parameter is optional.

vtMax

A Variant that contains the number that specifies the high end of the range of values against which to validate the converted value. The default value is NULL, indicating that this parameter is ignored. If the converted value is greater than vtMax, then NULL is returned. This parameter is optional.

vtLocale

A Variant that contains the number that identifies the locale to use to convert the value. If this value is not specified, the RequestFloat method uses the value of the Locale property of the DataFunctions object. This parameter is optional.

Return Values

If this method completes successfully, it returns a Variant containing the floating-point value. If any validation fails, the return value will be NULL.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

This method converts the specified String based on the locale specified in the vtLocale parameter if the vtLocale parameter is specified; otherwise it uses the default locale found in the DataFunctions object. It validates the result of the conversion against the vtMin and vtMax parameters, if they are specified. If the validation fails this method returns NULL.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oAppFrameWork is a Commerce.AppFrameWork object.
' vFloat is a Variant.
' This example assumes that the float value is entered using
' the following form:
<FORM METHOD ="POST" ACTION="PROCESS.ASP">
<INPUT TYPE="Text" NAME="Float">
<INPUT TYPE="SUBMIT" NAME="ACTION" VALUE="Send Info">
</FORM>
' If the user enters the number into the form and clicks the
' Send Info button, the value of this form field can be
' retrieved by the RequestFloat method as follows:
vFloat = oAppFrameWork.RequestFloat("Float", 0, 0, 100, 1033)

See Also

AppFrameWork Object

DataFunctions.Locale

AppFrameWork.RequestNumber

DataFunctions.ConvertFloatString

DataFunctions.Float

DataFunctions.ValidateFloat


AppFrameWork.RequestMoneyAsNumber

Use this method to retrieve a value from a URL query string or form post variable and convert it as money, based on the specified locale.

Definition

Function RequestMoneyAsNumber(
bstrName As String,
Optional vtDefault As Variant,
Optional vtMin As Variant,
Optional vtMax As Variant,
Optional vtLocale As Variant
) As Variant

Parameters

bstrName

A String that contains the name of the URL query string or form post variable to retrieve.

vtDefault

A Variant that contains the value to return if the requested URL query string or form post variable is not present or contains no value. If this parameter is also not supplied, the method returns NULL. If the default value is a string value, it will be converted into the base monetary value; otherwise, it is assumed that the value is in base monetary units. This parameter is optional.

vtMin

A Variant that contains the monetary value that specifies the low end of the range against which to validate the converted value. A value in base monetary units is expected for the vtMin parameter. If the converted value is less than vtMin, then NULL is returned. This parameter is optional.

vtMax

A Variant that specifies the high end of the range against which to validate the converted value. A value in base monetary units is expected for the vtMax parameter. If the converted value is greater than vtMax, then NULL is returned. This parameter is optional.

vtLocale

A Variant that contains the number that specifies the locale to use to convert the bstrName parameter. If this parameter is not used, the RequestMoneyAsNumber method uses the value of the Locale property of the DataFunctions object. This parameter is optional.

Return Values

If this method completes successfully, it returns a Variant that contains a number in the base monetary units of the specified or default locale. If any validation fails, the return value will be NULL.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

If this method completes successfully it returns a number that represents the value of the specified string in the base monetary unit of the specified local. Thus, given a value in US dollars, it returns the number of cents in that value.

This method converts the specified String based on the locale specified in the vtLocale parameter if the vtLocale parameter is specified; otherwise it uses the default locale found in the DataFunctions object. It validates the result of the conversion against the vtMin and vtMax parameters, if they are specified. If the validation fails this method returns NULL.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oAppFrameWork is a Commerce.AppFrameWork object.
' In the following example, the value of a field on the purchase
' form (filled out by the customer) is read into the
' variable list_price.

<FORM METHOD ="POST" ACTION="PROCESS.ASP">
<INPUT TYPE="Text" NAME="list_price">
<INPUT TYPE="SUBMIT" NAME="ACTION" VALUE="Send Info">
</FORM>
' The vtMax argument is the upper limit
' of a Variant variable. Using this value as the upper limit and
' zero (0) as the lower limit of the range check ensures that
' the value is not negative:
list_price = oAppFrameWork .RequestMoneyAsNumber("list_price", 0, 0, _
    2147483647)

See Also

AppFrameWork Object

DataFunctions.Locale

DataFunctions.ConvertMoneyStringToNumber

DataFunctions.Money

AppFrameWork.RequestFloat

AppFrameWork.RequestNumber


AppFrameWork.RequestNumber

Use this method to retrieve a value from a URL query string or form post variable and convert it to a number based on the specified or default locale.

Optionally, the RequestNumber method checks the converted number against the specified range and validates it based on the specified locale.

Definition

Function RequestNumber(
bstrName As String,
Optional vtDefault As Variant,
Optional vtMin As Variant,
Optional vtMax As Variant,
Optional vtLocale As Variant
) As Variant

Parameters

bstrName

A String that contains the name of the URL query string or form post variable to retrieve.

vtDefault

A Variant that contains the value to return if the requested URL query string or form post variable is not present or contains no value. If this parameter is not supplied, the method returns NULL. This parameter is optional.

vtMin

A Variant that contains the number value that specifies the low end of the range against which to validate the converted value. If the converted value is less than vtMin, then NULL is returned. This parameter is optional.

vtMax

A Variant that contains the number value that specifies the high end of the range against which to validate the converted value. If the converted value is greater than vtMax, then NULL is returned. This parameter is optional.

vtLocale

A Variant that contains the number that specifies the locale to use to convert the bstrName parameter. If this parameter is not used, the RequestNumber method uses the value of the Locale property of the DataFunctions object. This parameter is optional.

Return Values

If this method completes successfully, it returns a Variant that contains the converted number. If any validation fails, the return value will be NULL.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

This method converts the specified String based on the locale specified in the vtLocale parameter if the vtLocale parameter is specified; otherwise it uses the default locale found in the DataFunctions object. It validates the result of the conversion against the vtMin and vtMax parameters, if they are specified. If the validation fails this method returns NULL.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oAppFrameWork is a Commerce.AppFrameWork object.
' In the following example, the value of a field on the purchase
' form (filled out by the customer) is read into the
' variable cc_expmonth.

<FORM METHOD ="POST" ACTION="PROCESS.ASP">
<INPUT TYPE="Text" NAME="_cc_expmonth">
<INPUT TYPE="SUBMIT" NAME="ACTION" VALUE="Send Info">
</FORM>
' Because the Default parameter is specified
' as 7, the RequestNumber method will return 7 if the field is empty
' or missing.
cc_expmonth = oAppFrameWork.RequestNumber("_cc_expmonth",7, 1, 12)

See Also

AppFrameWork Object

DataFunctions.Locale

AppFrameWork.RequestFloat

DataFunctions.ConvertNumberString

DataFunctions.Number

DataFunctions.ValidateNumber


AppFrameWork.RequestString

Use this method to retrieve a value from a URL query string or form post variable and perform string processing on it.

Definition

Function RequestString(
bstrName As String,
Optional vtDefault As Variant,
Optional vtMin As Variant,
Optional vtMax As Variant,
Optional vtStripWhite As Variant,
Optional vtStripReturn As Variant,
Optional vtCase As Variant,
Optional vtLocale As Variant
) As Variant

Parameters

bstrName

A String that contains the name of the URL query string or form post variable to retrieve.

vtDefault

A Variant that contains the string to return if the specified URL query string or form post variable does not exist or contains no value. If this parameter is not supplied, the method returns NULL. This parameter is optional.

vtMin

A Variant that contains the number that indicates the minimum length against which the length of the bstrName parameter must be validated. If the variant is of type vtMissing, the vtMin parameter value is not considered in the validation process. If this value is invalid or length of the bstrName/vtDefault parameters is not in range, the method returns NULL. This parameter is optional.

vtMax

A Variant that contains the number that indicates the maximum length against which the length of the bstrName parameter must be validated. If the variant is of type vtMissing, the vtMax parameter value is not considered in the validation process. If this value is invalid or length of the bstrName/vtDefault parameters is not in range, the method returns NULL. This parameter is optional.

vtStripWhite

A Variant that contains a Boolean value that indicates whether leading and trailing white spaces should be stripped from the string. The default value is True. This parameter is optional.

vtStripReturn

A Variant that contains a Boolean value that indicates whether carriage returns should be stripped from the string. The default value is True. This parameter is optional.

vtCase

A Variant that contains the number that indicates the case to which the string should be converted. The default value is zero (0), which results in no modification to the case of the string. If the vtCase parameter is one (1), the string is converted to uppercase. If the vtCase parameter is two (2), the string is converted to lowercase. This parameter is optional.

vtLocale

A Variant that contains the number that specifies the locale to be used as the basis of the conversion. If this value is not specified, the RequestString method uses the value of the Locale property of the DataFunctions object. This parameter is optional.

Return Values

If this method completes successfully, it returns a Variant that contains the processed string.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

This method can optionally perform several types of string processing. It can trim leading and trailing white space (space and tab characters) from the string. It can remove carriage returns from the string. It can convert the string to upper- or lowercase.

This method converts the specified String based on the locale specified in the vtLocale parameter if the vtLocale parameter is specified; otherwise it uses the default locale found in the DataFunctions object. It validates the result of the conversion against the vtMin and vtMax parameters, if they are specified.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oAppFrameWork is a Commerce.AppFrameWork object.
' vString is a Variant.
' This example assumes that the string value is entered using
' the following form:
<FORM METHOD ="POST" ACTION="PROCESS.ASP">
<INPUT TYPE="Text" NAME="String">
<INPUT TYPE="SUBMIT" NAME="ACTION" VALUE="Send Info">
</FORM>
' If the user enters the string into the form and clicks the
' Send Info button, the value of this form field can be
' retrieved by the RequestString method as follows:
vString = oAppFrameWork.RequestString("String", "Default String", _
    1, 100, True, True, 0, 1033)
' In this example, the string is checked to ensure that it contains
' between 1 and 100 characters; all leading and trailing white
' spaces are removed, all carriage returns are removed, no
' modification is made to character case, and the string is
' converted according to the locale 1033. If no string is
' input, the string "Default String" will be loaded into the
' variable vString.

See Also

AppFrameWork Object

DataFunctions.Locale


AppFrameWork.RequestTime

Use this method to retrieve a value from a URL query string or form post variable and convert the string to a Date Variant, based on the specified or default locale.

Definition

Function RequestTime(
bstrName As String,
Optional vtDefault As Variant,
Optional vtMin As Variant,
Optional vtMax As Variant,
Optional vtLocale As Variant
) As Variant

Parameters

bstrName

A String that contains the name of the URL query string or form post-variable to retrieve.

vtDefault

A Variant that contains the string to return if the specified URL query string or form post variable does not exist or contains no value. If this parameter is not supplied, the method returns NULL. The default cannot contain DateTime or Date values. This parameter is optional.

vtMin

A Variant that contains the time value that specifies the low end of the range against which to validate the bstrName parameter. The default is no low-end validation. This parameter is optional. If the converted value is less than vtMin, then NULL is returned.

vtMax

A Variant that contains the time value that specifies the high end of the range against which to validate the bstrName parameter. The default is no high-end validation. If the converted value is greater than vtMax, then NULL is returned. This parameter is optional.

vtLocale

A Variant that contains the number that specifies the locale to use to convert the DateTime value. If this value is not specified, the RequestTime method uses the value of the Locale property of the DataFunctions object. This parameter is optional.

Return Values

If this method completes successfully, it returns a Variant that contains the date. If any validation fails, the return value will be NULL.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

This method converts the specified String based on the locale specified in the vtLocale parameter if the vtLocale parameter is specified; otherwise it uses the default locale found in the DataFunctions object. It validates the result of the conversion against the vtMin and vtMax parameters, if they are specified. If the validation fails this method returns NULL.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oAppFrameWork is a Commerce.AppFrameWork object.
' This example assumes that the time value is entered using
' the following form:
<FORM METHOD ="POST" ACTION="PROCESS.ASP">
<INPUT TYPE="Text" NAME="Time">
<INPUT TYPE="SUBMIT" NAME="ACTION" VALUE="Send Info">
</FORM>
' If the user enters the date into the form and clicks
' the Send Info button, the value of this form field can
' be retrieved by the RequestTime method as follows:
vTime = oAppFrameWork.RequestTime("Time", "12:00:01 AM", _
    "12:00:01 AM", "11:59:59 PM", 1033)

See Also

AppFrameWork Object

DataFunctions.Locale

DataFunctions.ConvertTimeString

AppFrameWork.RequestDate


AppFrameWork.VerifyWith

Use this method to generate hidden input fields that contain verification values.

Definition

Function VerifyWith(
pdispOrder As Object
 pParams As Variant
) As Variant

Parameters

pdispOrder

An object reference to the OrderForm object that contains the fields to verify.

pParams

A variable list of arguments of type VARIANT, that contain the field names to verify in the supplied OrderForm object.

Return Values

If this method completes successfully, it returns a Variant that contains the HTML tags.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Use this method to output HTML tags in the form <INPUT TYPE="HIDDEN"> in an HTML form. These hidden fields contain specified values from the OrderForm object to be used to verify that an order has not been altered between presentation of the OrderForm object and final purchase.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oAppFrameWork is a Commerce.AppFrameWork object.
' The following example generates hidden fields containing
' the values stored in the _total_total,and _tax_total fields
' of the supplied OrderForm object:
<FORM METHOD="POST"
    ACTION="http://example.microsoft.com/xt_orderform_purchase.asp">
    <% = oAppFrameWork.VerifyWith(mscsOrderForm, "_total_total", _
 "_tax_total") %>
' When the page containing this call is loaded in the client
' browser, the document source for the page would contain the
' following HTML script (assuming a total of 138.95 and a tax
' of 8.75):
<FORM METHOD="POST"
ACTION="http://example.microsoft.com/xt_orderform_purchase.asp">
<INPUT TYPE=HIDDEN NAME="_VERIFY_WITH" VALUE="_total_total=13895">
<INPUT TYPE=HIDDEN NAME="_VERIFY_WITH" VALUE="_tax_total=875">

See Also

AppFrameWork Object

OrderForm Object


AppFrameWork.VirtualDirectory

Use this method to return the name of the virtual directory for the site.

Definition

Function VirtualDirectory() As String

Parameters

None.

Return Values

If this method completes successfully, it returns a String that contains the site virtual directory.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

See Also

AppFrameWork Object

StandardSManager Object


AsyncRpt Object

Use this object to render (display) or export a static report asynchronously.

ProgID: | Commerce.AsyncRpt (Externally creatable)
COM Class Name: | AsyncRpt
Type Library Name: | Microsoft Commerce 2000 Async Report Manager Type Library
DLL Name: | AsyncReport.dll
Threading Model: | Both

The methods of the AsyncRpt object are shown in the following table.

Method | Description
RunReport | Runs or exports the report.

Remarks

The AsyncRpt object renders or exports reports asynchronously.

The ReportRender object renders or exports reports synchronously.

The AsyncRpt object calls the ReportRender object passing it a string containing the rendering parameters. For more information about the rendering process, see ReportRender Object.

See Also

Analysis/Reporting Schema

Analysis/Reporting XML Structures

Creating Custom Reports

ListManager Object

ReportRenderer Object

Running Reports


AsyncRpt.RunReport

Use this method to initialize the AsyncRpt object and to render or export a static report asynchronously.

Definition

Sub RunReport(
bstrRepParam As String
)

Parameters

bstrRepParam

A String used to supply parameters to the AsyncRpt object.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to E_FAIL (&H80004005) to indicate failure. For more information about standard COM errors, see Standard COM Errors.

Remarks

The AsyncRpt object calls the ReportRender object, passing it the bstrRepParam parameter.

The bstrRepParam parameter is identical to the sParamString parameter of the Init method of the ReportRender object. For more information, see ReportRender Object.

See Also

AsyncRpt Object


Auction Object

Use this object to provide auction capabilities to a site. This object enables a site to auction products, accept bids, and determine winners, using rules ranging from simple to sophisticated. Users can set reserve prices, minimum bids, start and end dates, bid increments, and resolve bid conflicts. Users can also notify auction participants of important news via DHTML, HTML, or e-mail at any interval.

ProgID: | Commerce.Auction (Externally creatable)
COM Class Name: | Auction
Type Library Name: | Commerce Server 4.0 Auction Component
DLL Name: | auction.dll
Threading Model: | Apartment

The properties of the Auction object are shown in the following table.

Property | Type | Description
AuctionID | String | Stores the AuctionID GUID This property is read-only.
dtAMT | Date | Stores the date/time stamp used by the auction engine. This property is read/write.
objMessageManager | Object | Stores the MessageManager object used to generate error messages. This property is read/write.
szBidOrderBy | String | Stores the sort string used to resolve ties. This property is read/write.
szBidTableName | String | Stores the name of the Bid table in the database. This property is read/write.
szDSN | String | Stores the connection string for the database. This property is read/write.
szItemTableName | String | Stores the name of the Item table in the database. This property is read/write.
szLanguage | String | Stores the language used in by the MessageManager object when generating error messages. This property is read/write.

The methods of the Auction object are shown in the following table.

Method | Description
AuctionAddBid | Adds or updates a bid on an auction.
AuctionAddItem | Adds a new auction item to the Auction database.
AuctionBidNormalize | Normalizes a bid to the bid increment amount.
AuctionDeleteBid | Deletes a bid in an auction.
AuctionDeleteBids | Deletes all bids in a particular auction.
AuctionDeleteItem | Deletes an item and all bids on the item in a particular auction.
AuctionGetBid | Returns a rowset containing a bid from a specific user for a specific auction item.
AuctionGetBids | Returns a rowset containing all bids for an auction item.
AuctionGetItem | Returns a rowset for the item up for auction.
AuctionGetStatus | Returns a Dictionary object containing rowsets for the item up for auction.
AuctionInit | Initializes the Auction object.
AuctionRandomBids | Adds random bids to an auction to aid testing.
AuctionResolve | Resolves the auction based on the current settings and rules.
AuctionUpdateItem | Updates an auction item in the Auction database.

Remarks

The Auction object depends on the presence of the Item and Bid tables, stored in the site database, and a MessageManager object to hold the error messages. The tables must be created before using the Auction object for the first time. The MessageManager object must be properly initialized for the Auction object to pass error messages back to the user.


Auction.AuctionAddBid

Use this method to add or update a bid on an item. The bid is validated according to all the current rules for the auction.

Definition

Function AuctionAddBid(
szAuctionId As String,
szShopperId As String,
szBidName As String,
szEmail As String,
cyBidPrice As Currency,
nDesired As Long,
fTakeLess As Boolean,
cyMinimumBid As Currency,
objErrorList As Object,
Optional bResolve As Boolean
) As Long

Parameters

szAuctionId

A String that contains the unique auction ID.

szShopperId

A String that contains the unique ID of the unique bidder.

szBidName

A String that contains the name of the bidder.

szEmail

A String that contains the email address of the bidder.

cyBidPrice

A Currency that contains the bid amount.

nDesired

A Long that contains the number of wanted items.

fTakeLess

A Boolean that indicates whether the bidder will take less than the wanted number of items. A value of False indicates the bidder will not accept less than the wanted number of items.

cyMinimumBid

A Currency that contains the minimum bid.

objErrorList

A SimpleList object that contains a list of errors generated by the MessageManager object.

bResolve

A Boolean that indicates whether to call the AuctionResolve method. A value of True causes the method to be called with the bOptimize parameter of the method set to True. A value of False causes the Auction object to skip the automatic call to the AuctionResolve method. The default value is True.

Return Values

If this method completes successfully, it returns a Long that contains the number of error strings written to the objErrorList object.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

'lNumErrStrings is a Long
'szAuctionID is a String containing a GUID
'oErrorList is an object

lNumErrStrings = oAuction.AuctionAddBid(szAuctionID, "Bidder123456", szBidName, "Bidder123456@isp.com", 25.00, 5, FALSE, 19.99, oErrorList, TRUE)

See Also

Auction Object


Auction.AuctionAddItem

Use this method to add a new item to the auction system.

Definition

Function AuctionAddItem(
szSKU As String,
cyReservePrice As Currency,
nAvailable As Long,
cyBidIncrement As Currency,
nAuctionType As Long,
cyMinimumBid As Currency,
fSealedBid As Boolean,
fSealedInventory As Boolean,
fActive As Boolean,
dtStartDate As Date,
dtEndDate As Date,
nAutoCloseSeconds As Long,
objErrorList As Object
) As Long

Parameters

szSKU

A String that contains the unique ID for the item.

cyReservePrice

A Currency that contains the minimum price that the seller is willing to sell the item for. The reserve price must be greater than the minimum bid.

nAvailable

A Long that contains the number of items for sale.

cyBidIncrement

A Currency that contains the amount a bid must be raised in order to bid on the item.

nAuctionType

A Long that contains the auction type. For more information, see the table in the Remarks section.

cyMinimumBid

A Currency that contains the minimum opening bid.

fSealedBid

A Boolean that indicates whether to check a bid against the minimum bid. A value of True skips the minimum bid check.

fSealedInventory

A Boolean that indicates whether to check the wanted number of items in a bid against the number of items available for sale. A value of False indicates to check the items. A value of True skips the check (the fTakeLess parameter in the bid is ignored).

fActive

A Boolean that indicates whether the auction is active. A value of True indicates an active auction. A value of False suspends bidding on the auction.

dtStartDate

A Date that determines when bids will be accepted on the item.

dtEndDate

A Date that determines when the auction is closed and the items can be purchased.

nAutoCloseSeconds

A Long that indicates the number of seconds to wait after the last bid is received to close the auction. This can close an auction before the end date. A value of zero (0) indicates to ignore the time of the last bid and close the auction on the end date.

objErrorList

An IDispatch interface that contains the error list.

Return Values

If this method completes successfully, it returns a Long that contains the number of error strings written to the objErrorList object.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The auction type controls the method used to determine the winning bidder and the amount the winning bidder must pay. The following table describes the available auction types.

Auction Type | Value | Description | Example
Winning Price | 0 | Winning bidders receive the item they bid on for the amount bid. If there is more than one item, winning bidders receive the number requested at the amount they bid. | Two items are at auction. Bidder A bids $10.00, Bidder B bids $5.00, and Bidder C bids $3.00, and each bidder requests one item. Bidder A receives one item for $10.00 and Bidder B receives one item for $5.00. However, if Bidder A requested two items at $10.00 each, both items would be awarded to Bidder A.
Clear Price | 1 | Winning bidders receive the item they bid on for the lowest winning bid. | Same conditions as Winning Price auction type example. Bidder A and Bidder B each receive one item for $5.00.
Second Price | 2 | Winning bidders pay the lowest of the following: The highest losing bid plus the bid increment, the lowest winning bid, or the reserve price, assuming the number of bids above the reserve price is less than the number of available items. | Same conditions as Winning Price auction type example with a bid increment of $0.50. Bidder A and Bidder B each receive one item for $3.50.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

'lNumErrStrings is a Long
'dtStartDate is a Date
'dtEndDate is a Date
'oErrors is a list object

lNumErrStrings = oAuction.AuctionAddItem("123456", 2.50, 2, 0.50, 1, 1.50, False, False, True, dtStartDate, dtEndDate, 0, oErrors)

See Also

Auction Object


Auction.AuctionBidNormalize

Use this method to normalize a bid to a whole multiple of the bid increment.

Definition

Function AuctionBidNormalize(
cyBidAmount As Currency,
cyBidIncrement As Currency,
cyMinimumBid As Currency
) As Currency

Parameters

cyBidAmount

A Currency that contains the bid amount.

cyBidIncrement

A Currency that contains the bid increment.

cyMinimumBid

A Currency that contains the minimum bid allowed.

Return Values

If this method completes successfully, it returns a Currency that contains the normalized bid.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' currNormBid is a Currency, the bid amount is $10.50
currNormBid = oAuction.AuctionBidNormalize(10.50, 1.00, 8.00)
' After the call, currNormBid = 10.00

See Also

Auction Object


Auction.AuctionDeleteBid

Use this method to deletes a bid placed on an item in an auction.

Definition

Function AuctionDeleteBid(
szAuctionId As String,
szShopperId As String,
Optional bResolve As Boolean
) As Variant

Parameters

szAuctionId

A String that contains the unique auction ID.

szShopperId

A String that contains the unique ID of the bidder.

bResolve

A Boolean that indicates whether to call the AuctionResolve method. A of True causes the method to be called with the bOptimize parameter of the method set to True. A value of False causes the Auction object to skip the automatic call to the AuctionResolve method. The default value is True.

Return Values

The return value is reserved for future use. Ignore the return value.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

'You can treat this function as a subroutine to ignore the return value.
oAuction.AuctionDeleteBid szAuctionId, szShopperId, bResolve

See Also

Auction Object


Auction.AuctionDeleteBids

Use this method to delete all bids on an item made in an auction. The item remains in the auction database and new bids can be accepted.

Definition

Function AuctionDeleteBids(
szAuctionId As String,
Optional bResolve As Boolean
) As Variant

Parameters

szAuctionId

A String that contains the unique auction ID.

bResolve

A Boolean that indicates whether to call the AuctionResolve method. A value of True causes the method to be called with the bOptimize parameter of the method set to True. A value of False causes the Auction object to skip the automatic call to the AuctionResolve method. The default value is True.

Return Values

The return value is reserved for future use. Ignore the return value.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Auction Object


Auction.AuctionDeleteItem

Use this method to delete an item and all bids for the item from the auction database.

Definition

Function AuctionDeleteItem(
szAuctionId As String
) As Variant

Parameters

szAuctionId

A String that contains the unique auction ID.

Return Values

The return value is reserved for future use. Ignore the return value.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Auction Object


Auction.AuctionGetBid

Use this method to retrieve a bid from a specific bidder for a specific auction item.

Definition

Function AuctionGetBid(
szShopperId As String,
szAuctionId As String
) As Object

Parameters

szShopperId

A String that contains the unique ID of the bidder.

szAuctionId

A String that contains the unique auction ID.

Return Values

If this method completes successfully, it returns an ADODB.Recordset object that contains the specified bid.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' rsBid is a Recordset object
rsBid = oAuction.AuctionGetBid(szShopperId, szAuctionId)

See Also

Auction Object


Auction.AuctionGetBids

Use this method to retrieve all the bids for the specified auction item.

Definition

Function AuctionGetBids(
szAuctionId As String,
Optional dtSinceDate As Date
) As Object

Parameters

szAuctionId

A String that contains the auction ID.

dtSinceDate

An optional Date that specifies to return only those bids whose status have changed since the indicated date. Status changes are due to bid updates or calculated field updates. A value of NULL indicates to return all bids.

Return Values

If this method completes successfully, it returns an ADODB.Recordset object that contains the specified bids.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' rsBids is a Recordset object
rsBids = oAuction.AuctionGetBids(szAuctionId, dtSinceDate)

See Also

Auction Object


Auction.AuctionGetItem

Use this method to retrieve an item up for auction.

Definition

Function AuctionGetItem(
szAuctionId As String
) As Object

Parameters

szAuctionId

A String that contains the unique auction ID.

Return Values

If this method completes successfully, it returns an ADODB.Recordset Object that contains the specified item.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Auction Object


Auction.AuctionGetStatus

Use this method to retrieve a Dictionary object containing information for the item up for auction and the bids on the item.

Definition

Function AuctionGetStatus(
szAuctionId As String
) As Object

Parameters

szAuctionId

A String that contains the unique auction ID.

Return Values

If this method completes successfully, it returns a Dictionary object that contains the specified item along with the bids on the item.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The Dictonary object contains two Recordset objects, rsAuctionItem and rsAuctionBids.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Auction Object


Auction.AuctionID

The AuctionID property is a read-only String that contains a GUID that uniquely identifies the Auction object.

Definition

Property AuctionID() As String

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Auction Object


Auction.AuctionInit

Use this method to initialize the Auction object.

Definition

Function AuctionInit(
szDSN As String,
szItemTableName As String,
szBidTableName As String,
szBidOrderBy As String,
objMessageManager As Object,
szLanguage As String,
dtAMT As Date
) As Variant

Parameters

szDSN

A String that contains the connection string to the database containing the Bid and Item tables.

szItemTableName

A String that contains the Item table name.

szBidTableName

A String that contains the Bid table name.

szBidOrderBy

A String that contains the default bid sort order (SQL ORDER BY clause).

objMessageManager

A MessageManager object.

szLanguage

A String that contains the language used by the MessageManager object.

dtAMT

A Date that contains a timestamp.

Return Values

The return value is reserved for future use. Ignore the return value.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

'szDSN = _
'AppConfig.GetOptionsDictionary("").s_TransactionsConnectionString
'objMessageManager is the MessageManager object stored at application
'scope.
'dtAMT is a timestamp.
'Ignore return value by treating AuctionInit as a subroutine.
oAuction.AuctionInit szDSN, "AuctionItem", "AuctionBid", "modified_date", objMessageManager, "English", dtAMT

See Also

Auction Object


Auction.AuctionRandomBids

Use this method to enter random bids into an auction for testing or demonstration purposes.

Definition

Function AuctionRandomBids(
szAuctionId As String,
fDelete As Boolean,
nNumberBids As Long
) As Variant

Parameters

szAuctionId

A String that contains the unique auction ID.

fDelete

A Boolean that indicates whether to delete previous random bids before adding the new bids. A value of True specifies to delete the bids. A value of False specifies to save the bids.

nNumberBids

A Long that contains the number of random bids to add.

Return Values

The return value is reserved for future use. Ignore the return value.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Random bids are entered under the bidder name "Random." The bids are at least the minimum bid and ask for a number of items between one and the number available.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

'szAuctionId is a GUID
oAuction.AuctionRandomBids szAuctionId, FALSE, 25

See Also

Auction Object


Auction.AuctionResolve

Use this method to run the auction engine and determine the status of the auction. It updates computed values in both the Item and Bid tables.

Definition

Function AuctionResolve(
szAuctionId As String,
Optional bOptimize As Boolean
) As Variant

Parameters

szAuctionId

A String that contains the unique auction ID.

bOptimize

An optional Boolean that determines when to stop searching for a winning bid. A value of True indicates to cease checking for winning bids once a winner has been selected. A value of False indicates to search all records in the database in order to look for winning bids. The default value is True.

Return Values

The return value is reserved for future use. Ignore the return value.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Auction Object


Auction.AuctionUpdateItem

Use this method to update an existing item in the auction system.

Definition

Function AuctionUpdateItem(
szAuctionId As String,
szSKU As String,
cyReservePrice As Currency,
nAvailable As Long,
cyBidIncrement As Currency,
nAuctionType As Long,
cyMinimumBid As Currency,
fSealedBid As Boolean,
fSealedInventory As Boolean,
fActive As Boolean,
dtStartDate As Date,
dtEndDate As Date,
nAutoCloseSeconds As Long,
objErrorList As Object,
Optional bResolve As Boolean
) As Long

Parameters

szAuctionId

A String that contains the unique auction ID.

szSKU

A String that contains the unique ID for the item.

cyReservePrice

A Currency that contains the minimum price the seller is willing to sell the item for. The reserve price must be greater than the minimum bid.

nAvailable

A Long that contains the number of items for sale.

cyBidIncrement

A Currency that contains the amount a bid must be raised in order to bid on the item.

nAuctionType

A Long that contains the auction type. For more information, see the Remarks section.

cyMinimumBid

A Currency that contains the minimum opening bid.

fSealedBid

A Boolean that indicates whether to check a bid against the minimum bid. A value of True skips the minimum bid check. A value of False checks against the minimum bid.

fSealedInventory

A Boolean that indicates whether to check the wanted number of items in a bid against the number of items available for sale. A value of True skips the check (the fTakeLess parameter in the bid is ignored). A value of False checks against the available items.

fActive

A Boolean that indicates whether the auction is active. A value of True indicates the auction is active. A value of False suspends bidding on the auction.

dtStartDate

A Date that determines when bids will be accepted on the item.

dtEndDate

A Date that determines when the auction is closed and the items can be purchased.

nAutoCloseSeconds

A Long that indicates the number of seconds to wait after the last bid is received to close the auction. This can close an auction before the end date. A value of zero (0) indicates to ignore the time of the last bid and close the auction on the end date.

objErrorList

An IDispatch interface that contains the error list.

bResolve

A Boolean that indicates whether to call the AuctionResolve method. A value of True causes the method to be called with the bOptimize parameter of the method set to False. A value of False causes the Auction object to skip the automatic call to the AuctionResolve method. The default value is True.

Return Values

If this method completes successfully, it returns a Long that contains the number of error strings written to the objErrorList object.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The auction type controls the method used to determine the winning bidder and the amount the winning bidder must pay. The following table describes the available auction types.

Auction Type | Value | Description | Example
Winning Price | 0 | Winning bidders receive the item they bid on for the amount bid. If there is more than one item, winning bidders receive the number requested at the amount they bid. | Two items are at auction. Bidder A bids $10.00, Bidder B bids $5.00, and Bidder C bids $3.00, and each bidder requests one item. Bidder A receives one item for $10.00 and Bidder B receives one item for $5.00. However, if Bidder A requested two items at $10.00 each, both items would be awarded to Bidder A.
Clear Price | 1 | Winning bidders receive the item they bid on for the lowest winning bid. | Same conditions as Winning Price auction type example. Bidder A and Bidder B each receive one item for $5.00.
Second Price | 2 | Winning bidders pay the lowest of the following: The highest losing bid plus the bid increment, the lowest winning bid, or the reserve price, assuming the number of bids above the reserve price is less than the number of available items. | Same conditions as Winning Price auction type example with a bid increment of $0.50. Bidder A and Bidder B each receive one item for $3.50.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' lNumErrStrings is a Long
lNumErrStrings = oAuction.AuctionUpdateItem(szAuctionId, szSKU, cyReservePrice, nAvailable, cyBidIncrement, nAuctionType, cyMinimumBid, fSealedBid, fSealedInventory, fActive, dtStartDate, dtEndDate, nAutoCloseSeconds, objErrorList, bResolve)

See Also

Auction Object


Auction.dtAMT

The dtAMT property is a read/write DATE value used to timestamp auction actions.

Definition

Property dtAMT() As Date

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Auction Object


Auction.objMessageManager

The objMessageManager property is a read/write MessageManager object used to return error messages to the bidder.

Definition

Property objMessageManager() As Object

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Auction Object


Auction.szBidOrderBy

The szBidOrderBy property is a read/write String used to resolve ties.

Definition

Property szBidOrderBy() As String

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

This string contains the fields (from the Bid table) used as criteria for selecting the auction winners when equal amounts are bid for an item. The string is added to the ORDER BY clause of a SQL string passed to the database for selecting the winners. The default string is "desired, modified_date". This means if two bidders bid the same amount, the bidder requesting more items wins. If still tied, the bidder placing the earliest bid wins.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Auction Object


Auction.szBidTableName

The szBidTableName property is a read/write String used to store the name of the Bid table in the database.

Definition

Property szBidTableName() As String

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The Bid table contains information about bids placed on auction items. The default name for this table in the site database is Auction_bid.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Auction Object


Auction.szDSN

The szDSN property is a read/write String used to store the connection string for the database.

Definition

Property szDSN() As String

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The connection string defaults to an empty string and must be set before the Auction object can be used.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Auction Object


Auction.szItemTableName

The szItemTableName property is a read/write String used to store the name of the Item table in the database.

Definition

Property szItemTableName() As String

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The Item table contains information about items available for auction. The default name of this table in the site database is Auction_item.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Auction Object


Auction.szLanguage

The szLanguage property is a read/write String used to store the language used by the MessageManager object when generating error messages.

Definition

Property szLanguage() As String

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Auction Object


AuthManager Object

Use this object to perform user identification and authentication and to manage user security information. This object also contains methods for cookie and cookieless browsing.

ProgID: | Commerce.AuthManager (Externally creatable)
COM Class Name: | MSCSAuthManager
Type Library Name: | Microsoft Commerce 2000 AuthManager Type Library
DLL Name: | mscsauth.dll
Threading Model: | Both

The methods of the AuthManager object are shown in the following table.

Method | Description
GenerateEncryptionKey | Generates an encryption key for the administration of cookie data. Use this method in administration or setup components only.
GetProperty | Retrieves the specified custom property stored in a cookie or query string.
GetURL | Generates a Uniform Resource Locator (URL) containing optional name/value pairs.
GetUserID | Retrieves the unique ID for the current user.
GetUserIDFromCookie | Retrieves a user ID from a cookie.
Initialize | Initializes the AuthManager object by caching all the required site configuration resource properties.
IsAuthenticated | Indicates whether or not a user is currently authenticated.
Refresh | Updates the cached site configuration resource properties after any of the properties have been changed.
SetAuthTicket | Generates an encrypted MSCSAuth ticket for a registered user.
SetProfileTicket | Generates an encrypted MSCSProfile ticket for an anonymous user.
SetProperty | Adds a property/value pair to a cookie or query string containing a ticket.
SetUserID | Sets the user ID property on a ticket.
UnInitialize | Removes the site-specific configuration resource properties from the cache.
URLArgs | Generates a URL-encoded query string from arrays of parameter names and values.
URLShopperArgs | Generates a URL-encoded query string from arrays of parameter names and values and appends the ticket of the user to the string.

Remarks

The AuthManager object identifies users and gathers information used for user authentication. The methods and properties of this object control and access the contents of cookies and encoded URL strings.

In the Commerce Server 2000 context, authentication uses tickets. A ticket is a string of property/value pairs that provide information about the user. Two types of tickets are supported. An authentication ticket, named MSCSAuth, is used for registered users while a profile ticket, named MSCSProfile, is used for anonymous users. In this context, registered means a user who has provided information to a site that can be used for identification.

A user may have both types of tickets. In this case, the MSCSAuth ticket takes precedence.

A ticket contains a unique user ID, and for authentication tickets, the time of last login and a time window. For an anonymous user who allows cookies, the MSCSProfile ticket is stored on the local computer of the user as a persistent cookie. For a registered user who allows cookies, the MSCSAuth ticket is stored in a session cookie and is valid for the duration of the session or a specified time window, and then is deleted.

If the user does not allow cookies, the ticket is placed in an encoded URL string. The URL string may be used to pass user information between pages and sites, provided all the URLs and query strings are generated by the AuthManager object.

The AuthManager object provides a transparent interface to the tickets, whether they are stored in cookies or in URL query strings, and handles encryption and decryption of the tickets to ensure security.

The AuthManager object is intended to be used only through Active Server Pages (ASP) since it depends on ASP intrinsic objects. Do not create the AuthManager object in application scope as it has dependencies on individual user sessions. The AuthManager object should be created and destroyed on each ASP page.

See Also

Site Security Objects

Working with Site Security and Filters


AuthManager.GenerateEncryptionKey

Use this method to generate an encryption key for encrypting/decrypting the cookie and query string data used for tickets.

Definition

Function GenerateEncryptionKey() As String

Parameters

None.

Return Values

If this method completes successfully, it returns a String that contains the encryption key.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM error that this method can return.

Constant | Value | Description
E_UPM_AUTHMANAGER_GENERATE_ENCRYPTIONKEY_FAILED | &HC1004C26 | An error occurred while generating the encryption key using the CryptoAPI.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

This method is used by the setup and Commerce Server Site Packager components during installation, and can be used to change the encryption key at a later time.

The encryption key is stored as part of the site configuration resource properties in the Admin database.

This method is one of the few AuthManager methods used in C++ applications.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

AuthManager Object


AuthManager.GetProperty

Use this method to retrieve the value of the specified custom property from the current user ticket.

Definition

Function GetProperty(
enumTicketType As EnumMSCS_TicketType,
propName As String
) As Variant

Parameters

enumTicketType

[in] An EnumMSCS_TicketType that indicates the type of ticket that contains the property.

propName

[in] A String that contains the name of the property to retrieve.

Return Values

If this method completes successfully, it returns a Variant that contains the value for the specified property in the current user ticket. If the property is not found, the returned Variant is empty.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_UPM_AUTHID_INVALID_PROPERTY | &HC1004C27 | Invalid custom property name or value.
E_UPM_AUTHMANAGER_API_ASP_ONLY | &HC1004C24 | This method should only be called within an ASP page.
E_UPM_AUTHMANAGER_TICKET_NOT_SET | &HC1004C25 | Requested ticket not set.
MSG_UPM_AUTH_PROPNOTFOUND_ERROR | &HC1004C00 | Requested property does not exist on the ticket.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The following table defines the possible values for the EnumMSCS_TicketType.

Name | Value | Description
enumMSCS_ProfileTicketType | 1 | A MSCSProfile ticket used for an anonymous user.
enumMSCS_AuthTicketType | 2 | A MSCSAuth ticket used for a registered user.

Use the SetProperty method to place custom property values in the current user ticket.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' sPasswordValue is a String
' oAuthManager is a Commerce AuthManager object

sPasswordValue = oAuthManager.GetProperty(enumMSCS_AuthTicketType, _
 "Password")

See Also

AuthManager Object

AuthManager.SetProperty


AuthManager.GetURL

Use this method to generate an encoded Uniform Resource Locator (URL) string.

Definition

Function GetURL(
FileName As String,
fCookie As Boolean,
fSecure As Boolean,
Optional pVarURLParameters As Variant,
Optional pVarURLValues As Variant
) As String

Parameters

FileName

[in] A String that contains the file name to reference in the URL.

fCookie

[in] A Boolean that indicates whether the user allows cookies.

fSecure

[in] A Boolean that indicates whether the URL is secure (HTTPS versus HTTP).

pVarURLParameters

[in, optional] A SafeArray that contains a list of parameter names to include in the URL.

pVarURLValues

[in, optional] A SafeArray that contains values that correspond to the parameter names.

Return Values

If this method completes successfully, it returns a String that contains the encoded URL.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_UPM_AUTHMANAGER_API_ASP_ONLY | &HC1004C24 | This method should only be called within an ASP page.
MSG_UPM_AUTH_SITE_NEEDED_ERROR | &HC1004C10 | The Initialize method must be called with the installed site name before calling this method.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The encoded URL includes the host name (retrieved from the site configuration), the virtual directory in which the file is stored (determined by the scripting context), the name of the file, flags for cookie support and security, and optional custom name/value pairs (for example, the name "SKU" and the stock-keeping unit (SKU) value for an item in a shopping cart).

If cookies are not allowed, the cookie flag is set to False and the ticket is appended to the URL.

Note

  • When a cached HTML segment that contains a URL with an appended ticket is retrieved, the ticket needs to be replaced with the correct one (for the current user context).

The secure flag is set to True if the referenced host is secure.

Use the URLArgs or URLShopperArgs methods to encode a URL query string out of name/value pairs.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' saParameterNames and saParameterValues are SafeArrays
' sURL is a string
' oAuthManager is a Commerce AuthManager object

saParameterNames(0) = "sku"
saParameterValues(0) = "12345"
sURL = oAuthManager.GetURL("filename.asp", False, True, _
 saParameterNames, saParameterValues)

' sURL = http://host_name/virtual_directory/filename.asp?sku=12345&MSCSAuth=Q0H4SE915ASH2KC000Q79QB1E

See Also

AuthManager Object


AuthManager.GetUserID

Use this method to retrieve a user ID stored in a ticket.

Definition

Function GetUserID(
enumTicketType As EnumMSCS_TicketType
) As Variant

Parameters

enumTicketType

An EnumMSCS_TicketType that indicates the type of ticket that contains the user ID.

Return Values

If this method completes successfully, it returns a Variant that contains the user ID. If the appropriate ticket type is not found or there is no user ID, the method returns NULL.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_UPM_AUTHMANAGER_API_ASP_ONLY | &HC1004C24 | This method should only be called within an ASP page.
MSG_UPM_AUTH_SITE_NEEDED_ERROR | &HC1004C10 | The Initialize method must be called with the installed site name before calling this method.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The following table defines the possible values for the EnumMSCS_TicketType.

Name | Value | Description
enumMSCS_ProfileTicketType | 1 | A MSCSProfile ticket used for an anonymous user.
enumMSCS_AuthTicketType | 2 | A MSCSAuth ticket used for a registered user.

If the ticket type is a MSCSAuth ticket and the ticket has expired, the ticket will be deleted and the return value will be as if there was no ticket.

If the ticket type is a MSCSAuth ticket and the ticket is within five minutes of expiring, the last login time is refreshed to the current time, allowing an additional period for the ticket to be valid.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' vUserID is a Variant
' oAuthManager is a Commerce AuthManager object

vUserID = oAuthManager.GetUserID(enumMSCS_ProfileTicketType)

See Also

AuthManager Object


AuthManager.GetUserIDFromCookie

Use this method to retrieve a user ID stored in a cookie.

Definition

Function GetUserIDFromCookie(
cookieData As String
) As String

Parameters

cookieData

[in] A String that contains the cookie.

Return Values

If this method completes successfully, it returns a String that contains the user ID.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM error that this method can return.

Constant | Value | Description
MSG_UPM_AUTH_SITE_NEEDED_ERROR | &HC1004C10 | The Initialize method must be called with the installed site name before calling this method.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The cookie data is always URL decoded.

Commerce Server 2000 Analysis applications use this method to extract user IDs from cookies found in Internet Information Services (IIS) logs.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

AuthManager Object


AuthManager.Initialize

Use this method to initialize the AuthManager object.

Definition

Sub Initialize(
bstrSiteName As String
)

Parameters

bstrSiteName

[in] A String that contains the name of the Commerce Server 2000 Web site.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The AuthManager object must be properly initialized to a valid site name immediately after creating the object and before any other AuthManager object method is used.

The first time any AuthManager object uses this method, it connects to the Administration database and caches the site configuration data using the SiteConfig object. When subsequent AuthManager objects call this method the data is read from the cache.

Use the Refresh method to update the site configuration data after any of the properties have been changed.

Use the UnInitialize method to delete the site-specific configuration resource properties from the cache when the site is no longer valid.

It is suggested to instantiate and initialize the AuthManager object in the Global.asa file to make sure at least one instance of the object exists, and to ensure the dynamic-link library (DLL) is loaded in memory and not flushed out by Internet Information Services (IIS) for performance reasons. This AuthManager object should not be used elsewhere. A separate instance of the AuthManager object must be created and destroyed on each ASP page.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

AuthManager Object


AuthManager.IsAuthenticated

Use this method to determine whether the current user has a valid MSCSAuth ticket. This method also allows the determination of whether the user has been authenticated within a specified period of time.

Definition

Function IsAuthenticated(
Optional TimeWindow As Long
) As Boolean

Parameters

TimeWindow

[in, optional, defaultvalue (0)] A Long that contains a time period in minutes.

Return Values

If this method completes successfully, it returns a Boolean that indicates the authentication status of the current user.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_UPM_AUTHMANAGER_API_ASP_ONLY | &HC1004C24 | This method should only be called within an ASP page.
MSG_UPM_AUTH_SITE_NEEDED_ERROR | &HC1004C10 | The Initialize method must be called with the installed site name before calling this method.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

A MSCSAuth ticket contains the time the user last logged in and a time window of validity. The ticket is no longer valid if the time since the last login has exceeded the time window specified in the SetAuthTicket method when the ticket was generated.

The optional time window parameter, TimeWindow, of this method allows checking whether the time since the user last logged in has exceeded a shorter time interval than the time window specified by the SetAuthTicket method. The default value of zero (0) is equivalent to setting the time window to the same value as specified in the SetAuthTicket method.

This method returns False if the user does not have an MSCSAuth ticket, the ticket is invalid, or the time since the user last logged in has exceeded the specified time window.

If the ticket is within five minutes of expiring, the last login time is refreshed to the current time, allowing an additional period for the ticket to be valid.

Ensure a log-off page is created and called for any logged-in user. The log-off page should either expire the MSCSAuth cookie or clear its contents.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

AuthManager Object


AuthManager.Refresh

Use this method to update the cached site configuration resource properties after any of the properties have been changed.

Definition

Sub Refresh(
bstrSiteName As String
)

Parameters

bstrSiteName

A String that contains the site name.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

This method should be called immediately after changing any of the authentication related site configuration resource properties. Also, use this method when switching between Active Server Pages (ASP) and Microsoft Visual Basic Scripting Edition (VBScript) files and updating the site configuration properties.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

AuthManager Object


AuthManager.SetAuthTicket

Use this method to set an encrypted MSCSAuth ticket for a registered user.

Definition

Sub SetAuthTicket(
UserID As String,
fCookieSupport As Boolean,
TimeWindow As Long
)

Parameters

UserID

[in] A String that contains the unique ID for the current user.

fCookieSupport

[in] A Boolean that indicates whether session cookies are supported.

TimeWindow

[in] A Long that defines the time window in minutes that the MSCSAuth ticket is valid.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_UPM_AUTHID_INVALID_CHARACTER_PRESENT | &HC1004C23 | Invalid character (';' or '%' or '=') present in the UserID or the property name/value pair.
E_UPM_AUTHMANAGER_API_ASP_ONLY | &HC1004C24 | This method should only be called within an ASP page.
MSG_UPM_AUTH_SITE_NEEDED_ERROR | &HC1004C10 | The Initialize method must be called with the installed site name before calling this method.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The time the user last logged in is stored in the ticket, along with the length of time from the last login that the ticket is valid.

If an MSCSAuth ticket for the user already exists and an empty string is passed in as the ID, UserID, for the user, the existing ticket is deleted.

If the current user is anonymous, use the SetProfileTicket method to generate an MSCSProfile ticket.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oAuthManager is a Commerce AuthManager object

oAuthManager.SetAuthTicket "JoeUser@microsoft.com", True, 30

See Also

AuthManager Object

AuthManager.IsAuthenticated


AuthManager.SetProfileTicket

Use this method to set a MSCSProfile ticket for an anonymous user. An anonymous user is not registered with a site.

Definition

Sub SetProfileTicket(
UserID As String,
fCookieSupport As Boolean
)

Parameters

UserID

[in] A String that contains the unique ID for the current user.

fCookieSupport

[in] A Boolean that indicates whether persistent cookies are supported.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_UPM_AUTHID_INVALID_CHARACTER_PRESENT | &HC1004C23 | Invalid character (';' or '%' or '=') present in the UserID or the property name/value pair.
E_UPM_AUTHMANAGER_API_ASP_ONLY | &HC1004C24 | This method should only be called within an ASP page.
MSG_UPM_AUTH_SITE_NEEDED_ERROR | &HC1004C10 | The Initialize method must be called with the installed site name before calling this method.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

If an MSCSProfile ticket for the user already exists and an empty string is passed in for the user ID, UserID, the existing ticket is deleted.

If the current user has registered, use the SetAuthTicket method to generate an MSCSAuth ticket.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oAuthManager is a Commerce AuthManager object

oAuthManager.SetProfileTicket "74A38551-D6D8-FFD0-12BF-0A20C90DC8D1", True

See Also

AuthManager Object

AuthManager.IsAuthenticated


AuthManager.SetProperty

Use this method to place a custom property name/value pair into the current ticket for the user.

Definition

Sub SetProperty(
EnumMSCS_TicketType enumTicketType,
propName As String,
propVal As String
)

Parameters

enumTicketType

[in] An EnumMSCS_TicketType that indicates the type of ticket.

propName

[in] A String that contains the name of the property.

propVal

[in] A String that contains the value corresponding to the named property.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_UPM_AUTHID_INVALID_CHARACTER_PRESENT | &HC1004C23 | Invalid character (';' or '%' or '=') present in the UserID or the property name/value pair.
E_UPM_AUTHID_INVALID_PROPERTY | &HC1004C27 | Invalid custom property name or value.
E_UPM_AUTHMANAGER_API_ASP_ONLY | &HC1004C24 | This method should only be called within an ASP page.
MSG_UPM_AUTH_SITE_NEEDED_ERROR | &HC1004C10 | The Initialize method must be called with the installed site name before calling this method.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Use the GetProperty method to retrieve the custom property values from the current ticket.

The following table defines the possible values for the EnumMSCS_TicketType.

Name | Value | Description
enumMSCS_ProfileTicketType | 1 | A MSCSProfile ticket used for an anonymous user.
enumMSCS_AuthTicketType | 2 | A MSCSAuth ticket used for a registered user.

Note

  • A property with the name "Ticket" is used by the AuthManager object for storing Commerce Server 2000 related information. When creating a custom property, do not set the property name to "Ticket".

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oAuthManager is a Commerce AuthManager object

oAuthManager.SetProperty enumMSCS_AuthTicketType, "Password", "MyPassword123"

See Also

AuthManager Object

AuthManager.GetProperty


AuthManager.SetUserID

Use this method to change the user ID property on a ticket.

Definition

Sub SetUserID(
enumTicketType As EnumMSCS_TicketType,
newUserID As String
)

Parameters

enumTicketType

An EnumMSCS_TicketType that indicates the type of ticket that will contain the user ID.

newUserID

A String that contains the unique ID for the current user.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_UPM_AUTHID_INVALID_CHARACTER_PRESENT | &HC1004C23 | Invalid character (';' or '%' or '=') present in the UserID or the property name/value pair.
E_UPM_AUTHMANAGER_API_ASP_ONLY | &HC1004C24 | This method should only be called within an ASP page.
MSG_UPM_AUTH_SITE_NEEDED_ERROR | &HC1004C10 | The Initialize method must be called with the installed site name before calling this method.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The value for the user ID may be the logon name for a registered user, a globally unique identifier (GUID) for an anonymous user, or any unique value.

If the appropriate ticket already exists, the value in the user ID is updated. If the ticket already exists and an empty string is passed in as the value for the user ID, newUserID, the existing ticket is deleted.

If the ticket does not exist, a ticket is created with default values for the rest of the data.

The following table defines the possible values for the EnumMSCS_TicketType.

Name | Value | Description
enumMSCS_ProfileTicketType | 1 | A MSCSProfile ticket used for an anonymous user.
enumMSCS_AuthTicketType | 2 | A MSCSAuth ticket used for a registered user.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oAuthManager is a Commerce AuthManager object

oAuthManager.SetUserID enumMSCS_AuthTicketType, "JoeUser@microsoft.com"

See Also

AuthManager Object


AuthManager.UnInitialize

Use this method to delete the site-specific configuration resource properties from the cache when the site is no longer valid.

Definition

Sub UnInitialize(
bstrSiteName As String
)

Parameters

bstrSiteName

[in] A String that contains the name of the site.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
MSG_UPM_AUTH_SITE_NEEDED_ERROR | &HC1004C10 | The Initialize method must be called with the installed site name before calling this method.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

This method must be called to disconnect the AuthManager object cache from the specified site.

The Initialize method loads the site configuration resource properties into the cache.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

AuthManager Object


AuthManager.URLArgs

Use this method to generate a Uniform Resource Locator (URL) encoded query string of name/value pairs.

Definition

Function URLArgs(
pVarURLParameters As Variant,
pVarURLValues As Variant
) As String

Parameters

pVarURLParameters

[in] A SafeArray that contains the parameter names.

pVarURLValues

[in] A SafeArray that contains the values corresponding to the parameter names.

Return Values

If this method completes successfully, it returns a String that contains the encoded URL query string.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_UPM_AUTHMANAGER_API_ASP_ONLY | &HC1004C24 | This method should only be called within an ASP page.
MSG_UPM_AUTH_SITE_NEEDED_ERROR | &HC1004C10 | The Initialize method must be called with the installed site name before calling this method.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

This method concatenates the parameter name/value pairs into a URL-encoded string. This method will fail if the two arrays containing the parameter names and values are not the same size.

The URLShopperArgs method performs the same URL encoding and additionally appends the ticket to the query string, if a ticket is set.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' saParameterNames and saParameterValues are SafeArrays
' sURLArg is a string
' oAuthManager is a Commerce AuthManager object

saParameterNames(0) = "sku1"
saParameterNames(1) = "sku3"
saParameterValues(0) = "12345"
saParameterValues(1) = "98765"
sURLArg = oAuthManager.URLArgs(saParameterNames, saParameterValues)

' sURLArg = "sku1=12345&sku3=98765"

See Also

AuthManager Object

AuthManager.URLShopperArgs


AuthManager.URLShopperArgs

Use this method to generate a Uniform Resource Locator (URL) encoded query string of name/value pairs and append the ticket to the query string if a ticket is set.

Definition

Function URLShopperArgs(
pVarURLParameters As Variant,
pVarURLValues As Variant
) As String

Parameters

pVarURLParameters

[in] A SafeArray that contains the parameter names.

pVarURLValues

[in] A SafeArray that contains the values corresponding to the parameter names.

Return Values

If this method completes successfully, it returns a String that contains the encrypted URL string.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_UPM_AUTHMANAGER_API_ASP_ONLY | &HC1004C24 | This method should only be called within an ASP page.
MSG_UPM_AUTH_SITE_NEEDED_ERROR | &HC1004C10 | The Initialize method must be called with the installed site name before calling this method.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

This method concatenates the parameter name/value pairs into a URL-encoded string and appends the ticket. This is useful for cookieless shopping support. This method will fail if the two arrays containing the parameters and values are not the same size.

If both types of tickets exist, the MSCSAuth ticket takes precedence.

Use the URLArgs method to perform URL encoding of parameter/value pairs without appending the ticket.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' saParameterNames and saParameterValues are SafeArrays
' sURLShopArg is a string
' oAuthManager is a Commerce AuthManager object

saParameterNames(0) = "sku1"
saParameterNames(1) = "sku3"
saParameterValues(0) = "12345"
saParameterValues(1) = "98765"
sURLShopArg = oAuthManager.URLShopperArgs(saParameterNames, saParameterValues)

' sURLShopArg = "sku1=12345&sku3=98765&MSCSAuth=Q0H4SE915ASH2KC000Q79QB1E"

See Also

AuthManager Object

AuthManager.SetProperty

AuthManager.SetAuthTicket

AuthManager.SetProfileTicket

AuthManager.URLArgs


BizDeskSecurity Object

Use this object to determine whether to display a module in the navigation pane of Commerce Server Business Desk.

ProgID: | Commerce.BizDeskSecurity (Externally creatable)
COM Class Name: | BizDeskSecurity
Type Library Name: | Microsoft Commerce 2000 BizDesk Security Type Library
DLL Name: | BDSecurity.dll
Threading Model: | Free

The one method of the BizDeskSecurity object is shown in the following table.

Method | Description
CanUserAccess | Determines whether the user has access rights to read the specified file.

Remarks

The Business Desk framework calls this object to determine which modules to display to the current user.

See Also

Site Security Objects


BizDeskSecurity.CanUserAccess

Use this method to determine whether the current user has read access rights to the specified Commerce Server Business Desk module.

Definition

Function CanUserAccess(
bstrPath As String,
) As Boolean

Parameters

bstrPath

A String that contains the file name and path for a Business Desk module.

Return Values

If this method completes successfully, it returns a Boolean set to either True or False. A value of True indicates that the current user has read access rights to the specified file. A value of False indicates that the current user does not have read access rights to the specified file.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Whether the user has read access to the specified Business Desk module is determined from the entries in the access control lists (ACLs) set for the file.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

' bAccess is a Boolean
' oBizDeskSecurity is a Commerce.BizDeskSecurity object
' CatalogEditor.asp is an ASP page corresponding to a Business Desk module

bAccess = oBizDeskSecurity.CanUserAccess("CatalogEditor.asp")

See Also

BizDeskSecurity Object


CacheManager Object

Use this object to establish and use a collection of data caches. Each data cache is either a Dictionary object or an LRUCache object. You can specify which one you would like to use by setting the CacheObjectProgID property.

ProgID: | Commerce.CacheManager (Externally creatable)
COM Class Name: | CacheManager
Type Library Name: | Microsoft Commerce 2000 Cache Manager Type Library
DLL Name: | mscscache.dll
Threading Model: | Both

The properties of the CacheManager object are shown the following table.

Property | Type | Description
AppUrl | String | Stores the full Uniform Resource Locator (URL) of the application. This property is read/write.
CacheObjectProgId | String | Stores the Programmatic Identifier (ProgID) for the object that is to be used for cache functions internally within the CacheManager object. Determines the type of object returned by the GetCache method. This property is read/write.
LoaderConfig | IDispatch | Stores the configuration Dictionary object that should be passed to the Loader component. This property is read/write.
LoaderProgId | String | Stores the ProgID of the component used to create and populate a data cache. This property is read/write.
RefreshInterval | long | Stores the number of seconds between automatic cache refresh operations. This property is read/write.
RetryInterval | long | Stores the number of seconds to wait before retrying after a cache load has failed. This property is read/write.
WriterConfig | IDispatch | Stores the configuration Dictionary object that should be passed to the Writer component. This property is read/write.
WriterProgId | String | Stores the ProgID of the component used to write out some type of data that has been accumulated since the last refresh. Advertising event data is one example of the type of data that might be accumulated. This property is read/write.

The methods of the CacheManager object are shown in the following table.

Method | Description
GetCache | Retrieves the data cache Dictionary object associated with a specified data cache name.
RefreshCache | Forces an immediate, synchronous refresh of the cache.

See Also

General Purpose Programming Concepts

Code to Implement Custom Cache Components


CacheManager.AppUrl

The AppUrl property is a read/write string that contains the full Uniform Resource Locator (URL) of the application.

Definition

Property AppUrl() As String

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The default value for this property is the URL of the current Internet Information Services (IIS) 5.0 application. Depending on the URL used to access the IIS application the first time after it is started, this URL could contain the special host name "localhost," preventing it from being accessed externally. Therefore, it is best to explicitly set this property to the full URL of the IIS application.

Unlike the other properties of CacheManager object that are set on a per-cache basis, the AppUrl property is a global property. The AppUrl property is generally used to register all of the caches running in a web server farm so that they can be managed without requiring explicit registration by an administrator. The Publish Campaign module in Commerce Server Business Desk is an example of this.

If the cache object is a Dictionary object, then the value of this property is passed to the CacheLoader and CacheWriter objects during each cache refresh. It will be put in the _AppUrl key in the Dictionary object.

See Also

CacheManager Object


CacheManager.GetCache

Use this method to retrieve either the Dictionary or LRUCache object for the specified cache name.

Definition

Function GetCache(
bstrName As String
) As IDispatch

Parameters

bstrName

A String that contains the name of the cache to be retrieved.

Return Values

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

This method is designed to be lightweight and fast. It is commonly called several times on any given ASP page.

The first time the GetCache method or the RefreshCache method is called, the data cache object is created and the configured CacheLoader component is invoked to populate it with data. Subsequent calls to the GetCache method may return the same cache object or a new cache object that is created when the cache is refreshed.

If the first call to the GetCache method for a particular cache results in a failed refresh, then the CacheManager object will not immediately retry a refresh when more GetCache method calls are made for the same cache. This is to avoid recurring timeouts that might bring down a system, for example if a database connection becomes temporarily unavailable. In this failure scenario, subsequent calls to the GetCache method will return an error indicating that the cache load failed and will not be retried until the refresh interval has elapsed or until the RefreshCache method is explicitly called.

After a cache has successfully been created, if a subsequent refresh of the cache fails, then the existing cache object is returned until a later refresh succeeds. The CacheManager object provides high availability to cache data at the expense of ensuring the cached data is up to date.

Example

'oMyCache is an object
'strMyCacheName is a String containing the name of an existing cache.

Set oMyCache = myCacheManager.GetCache(strMyCacheName)

See Also

CacheManager Object


CacheManager.CacheObjectProgId

The CacheObjectProgId property is a read/write String that contains the name of the object to be used internally to perform caching functions for this CacheManager object. It also determines the type of object returned by the GetCache method.

Definition

Property CacheObjectProgId(
bstrName As String
) As String

Parameters

bstrName

A String that contains the name of the cache object.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

By default, the CacheManager object will have Commerce.Dictionary set as the value for this property.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CacheManager Object


CacheManager.LoaderConfig

The LoaderConfig property is a read/write reference to a Dictionary object that contains configuration information for the Loader component.

Definition

Property LoaderConfig(
bstrName As String
) As IDispatch

Parameters

bstrName

A String that contains the name of a data cache for which Loader component configuration information is being provided or retrieved.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

This property, a Dictionary object containing configuration information for a particular Loader component, will be passed to that Loader component when it is created to load the associated data cache. When you set this property, the dictionary is shallow cloned and then the CacheManager object stores the clone of the dictionary. This is as opposed to simply storing a reference to the dictionary. Shallow clone means that scalars in the dictionary are copied by value, but other objects in the dictionary are copied by reference. The Loader component needs to implement the IPipelineComponentAdmin interface in order to read the configuration values from the dictionary, and in particular, the SetConfigData method of that interface. The Dictionary object identified by this property is passed to the newly created Loader component using the SetConfigData method.

See Also

CacheManager Object


CacheManager.LoaderProgId

The LoaderProgId property is a read/write string that contains the Programmatic Identifier (ProgID) of the component intended for use in populating the cache.

Definition

Property LoaderProgId(
bstrName As String
) As String

Parameters

bstrName

A String that contains the name of a data cache for which the Loader component ProgID is being provided or retrieved.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

See Also

CacheManager Object


CacheManager.RefreshCache

Use this method to force an immediate refresh of a data cache Dictionary object. This method is synchronous, not returning to the caller until the specified data cache is refreshed.

Definition

Sub RefreshCache(
bstrName As String
)

Parameters

bstrName

A String that contains the name of the data cache to be refreshed.

Return Values

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

If the specified cache is in the middle of being refreshed when the RefreshCache method is invoked, presumably by the background timer thread or a different foreground thread, this method will wait until the refresh operation is complete and then return. It will not result in another refresh operation.

Example

'strMyCacheName is a String containing the name of an existing cache.

myCacheManager.RefreshCache(strMyCacheName)

See Also

CacheManager Object


CacheManager.RefreshInterval

The RefreshInterval property is a read/write number that specifies the approximate number of seconds between automatic cache refresh operations on a specified cache.

Definition

Property RefreshInterval(
bstrName As String
) As Long

Parameters

bstrName

A String that contains the name of a data cache for which the refresh interval is being provided or retrieved.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

A refresh interval value of zero (0) means that the cache is never refreshed automatically.

The default refresh interval value is zero (0).

The value is a measurement of the number of seconds between automatic cache refresh operations.

See Also

CacheManager Object


CacheManager.RetryInterval

The RetryInterval property is a read/write number that specifies the approximate number of seconds to wait before retrying to load the data cache after failing to load.

Definition

Property RetryInterval(
bstrName As String
) As Long

Parameters

bstrName

A String that contains the name of a data cache for which the retry interval is being provided or retrieved.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

A retry interval value provides the number of seconds the CacheManager object should wait before retrying a failed cache refresh operation.

The default retry interval value is 60 (seconds).

The retry interval must be at least 1 (second).

See Also

CacheManager Object


CacheManager.WriterConfig

The WriterConfig property is a read/write reference to a Dictionary object that contains configuration information for the Writer component.

Definition

Property WriterConfig(
bstrName As String
) As IDispatch

Parameters

bstrName

A String that contains the name of a data cache for which Writer component configuration information is being provided or retrieved.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

This property, a Dictionary object containing configuration information for a particular Writer component, is passed to that Writer component when it is created to report results related to cache usage. When you set this property, the dictionary is shallow cloned and then the CacheManager object stores the clone of the dictionary. This is as opposed to simply storing a reference to the dictionary. Shallow clone means that scalars in the dictionary are copied by value, but other objects in the dictionary are copied by reference. The Writer component needs to implement the IPipelineComponentAdmin interface in order to read the configuration values from the dictionary, and in particular, the SetConfigData method of that interface. The Dictionary object identified by this property is passed to the created Writer component using the SetConfigData method.

See Also

CacheManager Object


CacheManager.WriterProgId

The WriterProgId property is a read/write string that contains the Programmatic Identifier (ProgID) of the component intended for use in populating the cache.

Definition

Property WriterProgId(
bstrName As String
) As String

Parameters

bstrName

A String that contains the name of a data cache for which the Writer component ProgID is being provided or retrieved.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

See Also

CacheManager Object


CatalogManager Object

Use this object to work with the entire Product Catalog System. The methods and properties of this object effect all catalogs contained in the Product Catalog System.

ProgID: | Commerce.CatalogManager (Externally creatable)
COM Class Name: | CatalogManager
Type Library Name: | Microsoft Commerce 2000 Catalog Type Library
DLL Name: | Catalog.dll
Threading Model: | Both

The properties of the CatalogManager object are shown in the following table.

Property | Type | Description
Catalogs | _Recordset | Returns a recordset containing a record for each catalog contained in the Product Catalog System, including their properties. This property is read-only.
CategoryDefinitions | _Recordset | Returns a recordset containing the names of all of the category definitions that currently exist in the Product Catalog System. This property is read-only.
CustomCatalogs | _Recordset | Returns a recordset containing a record for each custom catalog. These records include the custom catalog names and the names of the catalogs they are based on. This property is read-only.
ProductDefinitions | _Recordset | Returns a recordset containing the names of all the product definitions that currently exist in the Product Catalog System. This property is read-only.
Properties | _Recordset | Returns a recordset containing the name of each property that currently exists in the Product Catalog System. This property is read-only.

The methods of the CatalogManager object are shown in the following table.

Method | Description
AddDefinitionProperty | Adds a property to a definition.
AddDefinitionVariantProperty | Adds a variant property to a definition.
AddPropertyValue | Adds a value to the list of defined values for this property. Only applies to enumerations.
CreateCatalog | Creates a new catalog.
CreateCategoryDefinition | Creates a new category definition.
CreateProductDefinition | Creates a new product definition.
CreateProperty | Creates a new property.
DeleteCatalog | Deletes a catalog.
DeleteDefinition | Deletes a product or category definition
DeleteProperty | Deletes a property.
ExportCSV | Exports catalog data as a comma-separated value format file.
ExportXML | Exports catalog data as an Extensible Markup Language (XML) format file.
FreeTextSearch | Performs a free-text search of catalogs.
GetCatalog | Returns the specified catalog object.
GetDefinitionProperties | Returns the properties of a specified product or category definition
GetPropertyAttributes | Returns all the attributes of a specified property.
GetPropertyValues | Returns a list of appropriate values for an enumeration property.
ImportCSV | Imports a comma-separated value format file as catalog data.
ImportXML | Imports an XML format file as catalog data.
Initialize | Initializes the CatalogManager object.
Query | Performs queries against product, variant, and category data in one or more catalogs.
RemoveDefinitionProperty | Removes the specified property or variant property from a definition.
RemovePropertyValue | Removes a defined value from an enumeration property.
RenameDefinition | Renames a definition.
RenameProperty | Renames a property.
SetDefinitionProperties | Use this method to change the properties of a category or product definition.
SetPropertyAttributes | Changes the attributes of a property.

Remarks

Some methods of the CatalogManager object cannot be called in a transacted object. They are the CreateCatalog, DeleteCatalog, GenerateCustomCatalog, ImportCSV, ImportXML, and RegenerateFreeTextSearchIndex methods. These methods involve the creation, deletion, or updating of free text indexes. SQL Server does not allow these operations in a transaction.

Binding to the CatalogManager in a COM+ component that has either the Required or Requires New property set generates a run time error.


CatalogManager.AddDefinitionProperty

Use this method to add an existing property to an existing category or product definition.

Definition

Sub AddDefinitionProperty(
strDefinitionName As String,
strPropertyName As String
)

Parameters

strDefinitionName

A String that contains the name of the definition to which the property will be added.

strPropertyName

A String that contains the name of the property.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_DEFINITION_DOESNT_EXIST | &H8898000B | The specified definition did not exist.
E_CAT_PROP_DOESNT_EXIST | &H88980005 | The specified property did not exist.
E_CAT_PROP_IN_DEFINITION | &H8898000D | The specified property was already in the definition.
OLE_E_BLANK | &H80040007 | The object was not initialized. The Initialize method must be called before calling any other method.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

This method adds a property to a definition. Any products or categories created from the definition will also have the property. A property can only be added to a definition once. A property cannot be used in a product definition as both a property and a variant property.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

myCatalogManager.AddDefinitionProperty "Printers", "Manufacturer"

See Also

CatalogManager Object

CatalogManager.AddDefinitionVariantProperty

CatalogManager.RemoveDefinitionProperty


CatalogManager.AddDefinitionVariantProperty

Use this method to add a variant property to a definition. This method is similar to the AddDefinitionProperty method. The properties added with this method will only be used by product variants.

Definition

Sub AddDefinitionVariantProperty(
strDefinitionName As String,
strPropertyName As String
)

Parameters

strDefinitionName

A String that contains the name of the definition to which the specified variant property will be added.

strPropertyName

A String that contains the name of the property to be added to the specified definition.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_DEFINITION_DOESNT_EXIST | &H8898000B | The specified definition did not exist.
E_CAT_PROP_DOESNT_EXIST | &H88980005 | The specified property did not exist.
E_CAT_PROP_IN_DEFINITION | &H8898000D | The specified property was already in the definition.
OLE_E_BLANK | &H80040007 | The object was not initialized. The Initialize method must be called before calling any other method.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

This method adds a variant property to a definition. Any product variants created from the definition will also have the property. A property can only be added to a definition once. A property cannot be used in a product definition as both a property and a variant property.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

myCatalogManager.AddDefinitionVariantProperty "T-Shirts", "Size"

See Also

CatalogManager Object

CatalogManager.AddDefinitionProperty

CatalogManager.RemoveDefinitionProperty


CatalogManager.AddPropertyValue

Use this method to add a value to the list of defined values for the specified enumeration.

Definition

Sub AddPropertyValue(
strPropertyName As String,
strLegalValue As String
)

Parameters

strPropertyName

A String that contains the name of the enumeration property for which a new value will be defined.

strLegalValue

A String that contains the new value.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_PROP_DOESNT_EXIST | &H88980005 | The property you specified did not exist.
E_CAT_PROP_NOT_ENUM | &H88980007 | The property you specified was not of type cscEnumeration.
E_CAT_VALUE_ALREADY_ADDED | &H88980008 | The enumeration value you specified was already present in the list.
OLE_E_BLANK | &H80040007 | The object was not initialized. The Initialize method must be called before calling any other method.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The AddPropertyValue method is used only for properties whose data type is cscEnumeration.

This method adds a new value to the list of defined values for an enumeration property. Any attempts by a client to set this property to a value other than one of the legal values will result in an error. This method is useful for automatic validation against properties that only have a small, fixed set of values. For example, a Color property may have red, green, and blue as the only defined values.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

myCatalogManager.AddPropertyValue "color", "Blue"

See Also

CatalogManager Object

CatalogManager.GetPropertyValues

CatalogManager.RemovePropertyValue


CatalogManager.Catalogs

The Catalogs property is a read-only recordset that describes all the catalogs in the Product Catalog System. The returned recordset includes the properties of each catalog.

Definition

Property Catalogs() As _Recordset

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
OLE_E_BLANK | &H80040007 | The object was not initialized. The Initialize method must be called before calling any other method.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The recordset returned by this property is valid only if it is accessed successfully.

The returned recordset contains the following fields:

Field Name | Data-Type | Description
CatalogName | String 128 Characters | None
Locale | Integer | None
StartDate | DateTime | None
EndDate | DateTime | None
VariantID | String 128 Characters | The name of the property that uniquely identifies a product variant.
ProductID | String 128 Characters | The name of the property that uniquely identifies a product.
Currency | String 128 Characters | None
WeightMeasure | String 128 Characters | None
TimeStamp | Timestamp | None
CatalogID | Integer | The number that uniquely identifies a catalog.
CustomCatalog | Bit | A flag indicating whether this is a custom catalog.
FreeTextIndexCreated | DateTime | None
ProductTableUpdated | Datetime | None

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CatalogManager Object

CatalogManager.CreateCatalog

CatalogManager.DeleteCatalog


CatalogManager.CategoryDefinitions

The CategoryDefinitions property is a read-only recordset that contains the names of all the category definitions in the Product Catalog System.

Definition

Property CategoryDefinitions() As _Recordset

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The recordset returned by this property is valid only if it is accessed successfully.

The returned recordset will contain a single field called DefinitionName and one row for each category definition in the Product Catalog System. This field is a 128 character String.

If no category definitions are currently in the Product Catalog System, then the EOF property of the returned recordset will be set to VARIANT_TRUE.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CatalogManager Object

CatalogManager.CreateCategoryDefinition

CatalogManager.DeleteDefinition


CatalogManager.CreateCatalog

Use this method to create a new catalog.

Definition

Function CreateCatalog(
strCatalogName As String,
strProductID As String,
Optional strProductVariantID As Variant,
Optional lcidLocale As Variant,
Optional strCurrency As Variant,
Optional strWeightMeasure As Variant,
Optional dtStartDate As Variant,
Optional dtEndDate As Variant
) As ProductCatalog

Parameters

strCatalogName

A String that contains the name of the catalog to be created. See the Remarks section for a list of restricted characters.

strProductID

A String that contains the product ID property.

strProductVariantID

A Variant that contains the product variant ID property.

lcidLocale

A Variant that contains the locale ID (LCID) of the catalog to be created.

strCurrency

A Variant that contains the currency type of the catalog to be created.

strWeightMeasure

A Variant that contains the unit of weight or measure of the catalog to be created.

dtStartDate

A Variant of subtype DATE that contains the start date.

dtEndDate

A Variant of subtype DATE that contains the end date.

Return Values

If this method completes successfully, it returns the ProductCatalog object that was created.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_CATALOG_EXISTS | &H88980001 | There was already a catalog by that name. Catalog names must be unique throughout the Product Catalog System.
E_CAT_PRODID_DOESNT_EXIST | &H88980010 | The property you specified for the ProductID did not exist in the Product Catalog System properties.
E_CAT_UPDATE_FREETEXT_INDEX_FAILED | &H88980015 | This error occurs when full text search is installed but updating the full text search index fails. The catalog is created but full text search does not work. For the catalog to participate in full text searches delete the catalog and recreate it.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The ProductCatalog returned by this method is valid only if it was created successfully.

If variants are to be used in this catalog, you must provide a property name in the optional strProductVariantID parameter. If this parameter is not specified upon creation of the catalog, any attempt to create a product variant in that catalog will fail.

If the strProductID or strProductVariantID parameters are of type cscString, cscEnumeration, or cscFileName, they are limited to a length of 256 characters.

The returned ProductCatalog object will be pre-initialized and ready for use.

Notes

  • This method cannot be called in a transacted object. This method involves the creation, deletion, or updating of free text indexes. SQL Server does not allow these operations in a transaction.

  • Catalog names, and therefore the strCatalogName, parameter cannot begin with the pound sign (#) and cannot contain any of the following characters:
    • Blank space ( )

    • Double quote (")

    • Comma (,)

    • Period (.)

    • Left square bracket ([)

    • Right square bracket (])

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

Set oNewCatalog = myCatalogManager.CreateCatalog ("NewCatalog", "ItemNum", "SKU")

See Also

CatalogManager Object

CatalogManager.DeleteCatalog

CatalogManager.GetCatalog


CatalogManager.CreateCategoryDefinition

Use this method to create a new category definition.

Definition

Sub CreateCategoryDefinition(
strDefinitionName As String
)

Parameters

strDefinitionName

A String that contains the name of the new category definition.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_DEFINITION_EXISTS | &H8898000A | The specified category definition name already existed.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Category and product definition names must be globally unique across the entire Product Catalog System. It is not possible to have a category definition and a product definition with the same name.

The initial definition is empty when it is created. To add individual properties to the definition, use the AddDefinitionProperty method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

myCatalogManager.CreateCategoryDefinition "Housewares"

See Also

CatalogManager Object

CatalogManager.AddDefinitionProperty

CatalogManager.CreateProductDefinition

CatalogManager.DeleteDefinition


CatalogManager.CreateProductDefinition

Use this method to create a new product definition.

Definition

Sub CreateProductDefinition(
strDefinitionName As String
)

Parameters

strDefinitionName

A String that contains the name of the new product definition.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_DEFINITION_EXISTS | &H8898000A | The specified product definition name already existed.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Category and product definition names must be globally unique across the entire Product Catalog System. It is not possible to have a category definition and a product definition with the same name.

The initial definition is empty when it is created. To add individual properties to the definition, use the AddDefinitionProperty or AddDefinitionVariantProperty method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

myCatalogManager.CreateProductDefinition "Microwave"

See Also

CatalogManager Object

CatalogManager.AddDefinitionProperty

CatalogManager.AddDefinitionVariantProperty

CatalogManager.CreateCategoryDefinition

CatalogManager.DeleteDefinition


CatalogManager.CreateProperty

Use this method to create a new property.

Definition

Function CreateProperty(
strPropertyName As String,
eDataType As CatalogDataTypeEnum,
Optional varMaxLength As Variant
) As _Recordset

Parameters

strPropertyName

A String that contains the name of the new property. This parameter can only contain characters that are acceptable in XML tags.

eDataType

An enumeration value that specifies the data type of the new property. See the Remarks section for valid values.

varMaxLength

A Variant that contains the maximum length for the property. Even though this parameter is an optional value it must be given if the data type of the property is cscString. Properties of data type cscEnumeration have a fixed default value of 128, which cannot be changed. Properties of data type cscFilePath have a fixed default value of 256, which cannot be changed.

Return Values

If this method completes successfully, it returns a Recordset object that contains the property attributes.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_PROP_EXISTS | &H88980003 | The specified property name already existed. Property names must be unique across the Product Catalog System.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The recordset returned by this property is valid only if it is accessed successfully.

This method returns a single row Recordset object containing the newly created property. For more information about the fields in this Recordset object, see PropertyAttribute Recordset.

The following table shows the values of the CatalogDataTypeEnum enumeration, their associated names, and describes their use.

Name | Value | Description
cscInteger | 0 | Indicates an exact numeric value that holds whole numbers from –2[31] (-2,147,483,648) <= n <= 2[31] –1 (2,147,483,647)
cscBigInteger | 1 | Indicates an exact numeric value with precision 19 (if signed) or 20 (if unsigned) and scale 0 (signed: –2[63] <= n <= 2[63] – 1, unsigned: 0 <= n <= 2[64] – 1) [3], [9].
cscFloat | 2 | Indicates a positive or negative floating-point number. The range of positive values is approximately 2.23E –308 through 1.79E 308 and the range of negative values is approximately –2.23E –308 through –1.79E 308.
cscDouble | 3 | Indicates a positive or negative floating-point number. The range of positive values is approximately 2.23E –308 through 1.79E 308 and the range of negative values is approximately –2.23E –308 through –1.79E 308.
cscBoolean | 4 | Indicates a Boolean (bit), holds either a 1 or 0. Integer values other than 1 or 0 are accepted but are always interpreted as 1.
cscString | 5 | Indicates a variable-length character string with a maximum string length of 255 characters.
cscDateTime | 6 | Indicates a Microsoft SQL Server DateTime data type.
cscCurrency | 7 | Indicates a Microsoft SQL Server Money data type.
cscFilePath | 8 | Indicates a String that holds a file path.
cscEnumeration | 9 | Indicates an Integer associated with a defined constant.
cscInvalid | -1 | Reserved for future use.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

'varMaxLength is a Variant
'cscString is an enum of type cscEnumeration
varMaxLength = 128
Set rsNewPropAttribs = myCatalogManager.CreateProperty("Format", cscString, varMaxLength)

See Also

CatalogManager Object

CatalogManager.DeleteProperty

CatalogManager.GetPropertyAttributes

CatalogManager.SetPropertyAttributes


CatalogManager.CustomCatalogs

The CustomCatalogs property is a read-only recordset that describes the custom catalogs in the Product Catalog System, and the base catalogs on which they are based.

Definition

Property CustomCatalogs() As _Recordset

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The Recordset object returned by this property is valid only if it was accessed successfully.

The Recordset object contains the following fields:

Field | Data Type | Description
CustomCatalogName | String, 128 Characters | None
CatalogName | String, 128 Characters | None
CustomCatalogID | Integer | The number that uniquely identifies a catalog.
TimeStamp | timestamp | None

The Recordset object is sorted on the CustomCatalogName field.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CatalogManager Object

CatalogManager.Catalogs


CatalogManager.DeleteCatalog

Use this method to delete a catalog and derived custom catalogs from the Product Catalog System.

Definition

Sub DeleteCatalog(
strCatalogName As String
)

Parameters

strCatalogName

A String that contains the name of the catalog to be deleted.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_CATALOG_DOESNT_EXIST | &H88980002 | The specified catalog did not exist.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Note

  • This method cannot be called in a transacted object. This method involves the creation, deletion, or updating of free text indexes. SQL Server does not allow these operations in a transaction.

  • Deleting a catalog will also delete and custom catalogs that were derived from it.

Example

myCatalogManager.DeleteCatalog "OurStore"

See Also

CatalogManager Object

CatalogManager.CreateCatalog


CatalogManager.DeleteDefinition

Use this method to delete a definition from the Product Catalog System.

Definition

Sub DeleteDefinition(
strDefinitionName As String,
Optional fForceDelete As Boolean
)

Parameters

strDefinitionName

A String that contains the name of the definition to be deleted.

fForceDelete

A Boolean that specifies whether to force a deletion. A value of True indicates that the definition should be deleted even if it is currently being used in a catalog. A value of False indicates that the definition should only be deleted if it is not currently being used in a catalog. The default value is False.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_DEFINITION_DOESNT_EXIST | &H8898000B | The definition you specified did not exist.
E_CAT_DEFINITION_USED_IN_CATALOG | &H8898000C | This error is only returned when the fForceDelete parameter was set to False and the definition was already used in a catalog.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Use a value of True for the fForceDelete parameter with caution, as the category or product definition, and all categories and products that are based on them in all catalogs will also be deleted. This could result in data loss.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

myCatalogManager.DeleteDefinition "T-Shirts", FALSE

See Also

CatalogManager Object

CatalogManager.CreateCategoryDefinition

CatalogManager.CreateProductDefinition


CatalogManager.DeleteProperty

Use this method to delete a property from the Product Catalog System.

Definition

Sub DeleteProperty(
strPropertyName As String
)

Parameters

strPropertyName

A String that contains the name of the property to be deleted.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_PROP_DOESNT_EXIST | &H88980005 | The specified property did not exist.
E_CAT_PROP_IS_ID | &H88980011 | The specified property is used as either the ProductID property or VariantID property in one or more catalogs. These properties are defined when the catalog is created and cannot be removed.
E_CAT_PROP_STILL_IN_DEF | &H88980004 | The specified property is used in a definition. Call the RemoveDefinitionProperty method to remove the property from the definition before calling this method.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

myCatalogManager.DeleteProperty "Width"

See Also

CatalogManager Object

CatalogManager.CreateProperty


CatalogManager.ExportCSV

Use this method to export catalog data to a comma-separated values format file.

Definition

Sub ExportCSV(
strCSVDestination As String,
strCatalogToExport As String
fRunSynchronously As Boolean
)

Parameters

strCSVDestination

A String that contains the full path and file name of the export file to be created.

strCatalogToExport

A String that contains the name of the catalog to export.

fRunSynchronously

A Boolean that specifies whether the method should be run synchronously. A value of True indicates that the method will not return until the export is completed. A value of False indicates that the method will return immediately after spawning the export thread.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_IMPORT_IN_PROGRESS | &H88980025 | There was an existing import method call that had not yet completed. This method cannot run while an import is in progress.
E_CAT_FILE_CREATION_FAILED | &H88980018 | The method was unable to create the output file.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The ExportCSV method can be used to output product data from the Product Catalog System in a format that can be used in other programs, such as Microsoft Excel.

This method can only output product data from one catalog at a time.

The comma-separated values (CSV) file generated only contains products. The categories, relationships, and hierarchy are not written to the CSV file.

Note

  • This method runs in a separate thread. Prior to spawning the thread, it checks that there is not an existing ExportCSV, ExportXML, ImportCSV or ImportXML method in progress. Once the new thread is spawned, this method returns immediately, if fRunSynchronously is False, with no errors. Any errors that occurred while importing the catalog are logged to the Windows NT Event Log. Use the Windows Event Viewer to view the Windows NT Event Log.

  • If there is a temporary loss of the SQL connection, longer than two minutes, an import or export will be aborted. Other methods should work after the interruption.

Caution

  • Changes made to the catalog while an export is in progress may or may not be reflected in the output file. Additions and deletions made during the export could result in a corrupt file. Changes should be avoided during an export.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

myCatalogManager.ExportCSV "c:\exports\ourcatalog.csv", "OurStore"

See Also

CatalogManager Object

CatalogManager.ExportXML

CatalogManager.ImportCSV


CatalogManager.ExportXML

Use this method to export catalog data to an Extensible Markup Language (XML) file.

Definition

Sub ExportXML(
strXMLFilePath As String,
Optional strCatalogsToExport As Variant
VARIANT_BOOL fRunSynchronously
)

Parameters

strXMLFilePath

A String that contains the path and file name of the XML file to be created.

strCatalogsToExport

A Variant that contains the catalogs to export. See the Remarks section for more information.

fRunSynchronously

A Boolean that specifies whether the method should be run synchronously. A value of True indicates that the method will not return until the export is completed. A value of False indicates that the method will return immediately after spawning the export thread.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_IMPORT_IN_PROGRESS | &H88980025 | There was an existing import method call that had not yet completed. This method cannot run while an import is in progress.
E_CAT_FILE_CREATION_FAILED | &H88980018 | The method was unable to create the output file.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

If the parameter strCatalogsToExport is missing, or contains an empty string, then all catalogs are exported. Otherwise the parameter strCatalogsToExport is a comma-separated list of catalog names to be exported.

Note

  • This method runs in a separate thread. Prior to spawning the thread, it checks that there is not an existing ExportCSV, ExportXML, ImportCSV or ImportXML method in progress. Once the new thread is spawned, this method returns immediately, if fRunSynchronously is False, with no errors. Any errors that occurred while importing the catalog are logged to the Windows NT Event Log. Use the Windows Event Viewer to view the Windows NT Event Log.

  • If there is a temporary loss of the SQL connection, longer than two minutes, an import or export will be aborted. Other methods should work after the interruption.

Caution

  • Changes made to the catalog while an export is in progress may or may not be reflected in the output file. Additions and deletions made during the export could result in a corrupt file. Changes should be avoided during an export.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

myCatalogManager.ExportXML "c:\exports\ourcatalog.xml", "OurStore"

See Also

CatalogManager Object

CatalogManager.ExportCSV

CatalogManager.ImportXML


CatalogManager.FreeTextSearch

Use this method to perform a free-text search of catalogs.

Definition

Function FreeTextSearch(
strPhrase As String,
Optional strCatalogsToSearch As Variant,
Optional eClassTypeRequired As Variant,
Optional strPropertiesToReturn As Variant,
Optional strPropertyToSortOn As Variant,
Optional fSortAscending As Boolean,
Optional lStartingRecord As Variant,
Optional lRecordsToRetrieve As Variant,
Optional plTotalRecordsInQuery As Variant
) As _Recordset

Parameters

strPhrase

A String that contains the search phrase.

strCatalogsToSearch

A Variant that contains the catalogs to search in a comma-separated list. An empty string indicates search all catalogs.

eClassTypeRequired

A VARIANT that contains the catalog class desired. Valid values are from the CatalogClassTypeEnum enumeration, and are described in the Remarks section below.

strPropertiesToReturn

A Variant that contains the properties to return. This is a comma-delimited String.

strPropertyToSortOn

A Variant that contains the property on which to sort. If not included, the returned recordset will be unsorted.

fSortAscending

A Boolean that specifies whether to sort in ascending or descending order. A value of True indicates that the returned recordset will be sorted in ascending order. A value of False indicates that the returned recordset will be sorted in descending order. The default value is TRUE.

lStartingRecord

A Variant that contains the number of the starting record to retrieve. This is an offset from the first record.

lRecordsToRetrieve

A Variant that contains the number of records to retrieve starting from the starting record.

plTotalRecordsInQuery

A Variant used to return the number of records returned in the search.

Return Values

If this method completes successfully, it returns a Recordset object that contains the search results.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_MULTI_CAT_QUERY_NEEDS_PROPS | &H8898000F | The strPropertiesToReturn parameter must be specified if the search is done across multiple catalogs.
E_CAT_NO_CATALOGS | &H88980013 | There were no catalogs in the Product Catalog System.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The recordset returned by this method contains valid data only if the method completes successfully.

The FreeTextSearch method is used to perform arbitrary lexical comparisons on words or phrases in one or more catalogs. The FreeTextSearch functionality in the Product Catalog System is based on full text indexing in SQL Server 2000, and therefore, inherits keywords and operators from SQL Server 2000 for controlling the free text search.

The following table shows the values of the CatalogClassTypeEnum enumeration, their associated names, and describes their use.

Name | Value | Description
cscCategoryClass | 1 | Requests category data.
cscProductVariantClass | 2 | Requests product variant data.
cscProductClass | 4 | Requests product data.
cscProductFamilyClass | 8 | Requests product family data.
cscProductFamilyForVariantsClass | 16 | Requests family for variant data, which means the product family of a product variant is being requested.
CscProductVariantsForFamily | 32 | Requests variants for family data, which means that all of the product variants for a product family are being requested.

CatalogClassTypeEnum values can be combined in the eClassTypeRequired parameter with logical OR operators, so that specifying cscProductClass OR cscProductVariantClass will return both product and product variant data.

The programming rules regarding the strPropertiesToReturn parameter vary depending on whether a single catalog name is passed in the strCatalogsToSearch parameter or whether multiple catalog names are passed. When a single catalog name is passed, the strPropertiesToReturn parameter is optional and defaults to all properties. When multiple catalog names are passed, the strPropertiesToReturn parameter is required.

If no value is specified for the strPropertiesToReturn parameter the method returns all fields in the specified catalog, otherwise it returns only the fields specified in the strPropertiesToReturn parameter.

For more information, see CatalogProduct Recordset.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

'rsFTSResults is a recordset object
'plTotalRecordsInQuery is a Variant.
'Check it after the method returns for the
'total number of records that match the query.
Set rsFTSResults = myCatalogManager.FreeTextSearch("red ribbons", "Craft Supplies", "", "Price", True, 0, 20, plTotalRecordsInQuery)

See Also

CatalogManager Object

CatalogManager.Query


CatalogManager.GetCatalog

Use this method to retrieve a specified catalog from the Product Catalog System.

Definition

Function GetCatalog(
strCatalogName As String
) As ProductCatalog

Parameters

strCatalogName

A String that contains the name of the catalog to be retrieved.

Return Values

If this method completes successfully, it returns the ProductCatalog object that contains the catalog specified.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following standard COM error value has a particular meaning in the context of this method:

S_FALSE

The catalog specified did not exist.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The ProductCatalog object contains valid data only if the method completes successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

Set oCatalog = myCatalogManager.GetCatalog("Cdcatalog")

See Also

CatalogManager Object

CatalogManager.CreateCatalog

CatalogManager.DeleteCatalog


CatalogManager.GetDefinitionProperties

Use this method to return the properties of the specified catalog or product definition.

Definition

Function GetDefinitionProperties(
strDefinitionName As String
) As _Recordset

Parameters

strDefinitionName

A String that contains the name of the definition whose properties will be returned.

Return Values

If this method completes successfully, it returns a Recordset that contains the properties of the specified definition.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_DEFINITION_DOESNT_EXIST | &H8898000B | The specified definition did not exist.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The recordset returned by this method contains valid data only if the method completes successfully.

The returned recordset contains the following fields:

Field | Data Type | Description
DefinitionID | Integer | The number that uniquely identifies the definition.
PropertyName | String, 256 Characters | None
PropertyOrder | Integer | None
PropertyType | Integer | Zero (0) indicates product or category, one (1) indicates product variant.
TimeStamp | timestamp | None

The rows of the recordset are sorted on the PropertyOrder field.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

Set rsDefProps = myCatalogManager.GetDefinitionProperties("T-Shirts")

See Also

CatalogManager Object

CatalogManager.AddDefinitionProperty

CatalogManager.AddDefinitionVariantProperty

CatalogManager.RemoveDefinitionProperty


CatalogManager.GetPropertyAttributes

Use this method to return the attributes of the specified property.

Definition

Function GetPropertyAttributes(
strPropertyName As String
) As _Recordset

Parameters

strPropertyName

A String that contains the name of the property whose attributes will be returned.

Return Values

If this method completes successfully, it returns a Recordset object that contains the list of attributes for the specified property

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The recordset returned by this method contains valid data only if the method completes successfully.

This method returns a single row Recordset object containing the requested property. For more information about the fields in this Recordset object, see PropertyAttribute Recordset.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

Set rsPropAttribs = myCatalogManager.GetPropertyAttributes("Size")

See Also

CatalogManager Object

CatalogManager.SetPropertyAttributes


CatalogManager.GetPropertyValues

Use this method to return the list of values defined for an enumeration property.

Definition

Function GetPropertyValues(
strPropertyName As String
) As _Recordset

Parameters

strPropertyName

A String that contains the name of the enumeration property for which the defined values will be returned.

Return Values

If this method completes successfully, it returns a Recordset object that contains the defined values in the enumeration.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The returned recordset contains valid data only if the method completes successfully.

The returned recordset contains the following fields:

Field | Data Type | Description
PropertyName | String 256 Characters | None
Value | String 256 Characters | None

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

Set rsEnumValues = myCatalogManager.GetPropertyValues("Color")

See Also

CatalogManager Object

CatalogManager.AddPropertyValue

CatalogManager.RemovePropertyValue


CatalogManager.ImportCSV

Use this method to import a comma-separated-value (CSV) format file as catalog data.

Definition

Sub ImportCSV(
strCSVFileSource As String,
strProductIDColumnName As String,
strPriceColumnName As String,
strCatalogName As String,
fUpdateOnly As Boolean
fRunSynchronously As Boolean
)

Parameters

strCSVFileSource

A String that contains the path and file name of the CSV file to import.

strProductIDColumnName

A String that contains the name of the column that provides a unique ID for products to be imported into the catalog.

strPriceColumnName

A String that contains the name of the column in the CSV file containing the product prices.

strCatalogName

A String that contains the name of the catalog into which the CSV file will be imported. The name of the catalog cannot begin with "#" or consist solely of spaces.

fUpdateOnly

A Boolean that specifies whether to update an existing catalog or create a new one. A value of True indicates that if the system contains a catalog whose name is the same as the one specified in the strCatalogName parameter, it will be updated with the imported data. A value of False indicates to delete the catalog if it already exists and create a new one with the imported data. The default value is False.

fRunSynchronously

A Boolean that specifies whether the method should be run synchronously. A value of True indicates that the method will not return until the import is completed. A value of False indicates that the method will return immediately after spawning the import thread.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_IMPORT_IN_PROGRESS | &H88980025 | There was an existing import method call that had not yet completed. This method cannot run while an import is in progress.
E_CAT_FILE_OPEN_ERROR | &H88980020 | The method was unable to open the file.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

If the parameter strCatalogName specifies a catalog that does not exist, a new catalog will be created and the value of the fUpdateOnly parameter is ignored.

The ImportCSV method is used to bring existing data from a wide variety of sources into the Product Catalog System. The CSV file must conform to the following format:

  • The first row of data consists of column names, separated by commas. Rows are delimited by new lines in the text file.

  • Each subsequent row (called a data row) must have the same number of commas as the very first row. In other words, all columns in the CSV must be defined by the first row.

  • All items in the CSV file (one row per item) are assumed to be products, and are created from a common product definition. If no product definition exists in the destination catalog then one will be created during the import process.

  • Each item must specify a value for the column specified as the ProductID column, as well as for the column specified as the Price column.

  • Missing data is represented my two adjacent commas.

Notes

  • This method runs in a separate thread. Prior to spawning the thread, it checks that the specified file can be opened and that there is not an existing ExportCSV, ExportXML, ImportCSV or ImportXML method in progress. Once the new thread is spawned, this method returns immediately, if fRunSynchronously is False, with no errors. Any errors that occurred while importing the catalog are logged to the Windows NT Event Log. Use the Windows Event Viewer to view the Windows NT Event Log.

  • This method cannot be called in a transacted object. This method involves the creation, deletion, or updating of free text indexes. SQL Server does not allow these operations in a transaction.

  • If there is a temporary loss of the SQL connection, longer than two minutes, an import or export will be aborted. Other methods should work after the interruption.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

myCatalogManager.ImportCSV "c:\imports\ourcatalog.csv", "SKU", "Price", "OurCatalog", TRUE

See Also

CatalogManager Object

CatalogManager.ExportCSV

CatalogManager.ImportXML


CatalogManager.ImportXML

Use this method to import an Extensible Markup Language (XML) file as catalog data.

Definition

Sub ImportXML(
strXMLFilePath As String,
fUpdateOnly As Boolean
fRunSynchronously As Boolean
)

Parameters

strXMLFilePath

A String that contains the path and file name of the XML file to import.

fUpdateOnly

A Boolean that specifies whether to update an existing catalog or create a new one. A value of True indicates that if the system contains a catalog whose name is the same as the one specified in the strCatalogName parameter, it will be updated with the imported data. A value of False indicates to delete the catalog if it already exists and create a new one with the imported data.

fRunSynchronously

A Boolean that specifies whether the method should be run synchronously. A value of True indicates that the method will not return until the import is completed. A value of False indicates that the method will return immediately after spawning the import thread.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_IMPORT_IN_PROGRESS | &H88980025 | There was an existing import method call that had not yet completed. This method cannot run while an import is in progress.
E_CAT_FILE_OPEN_ERROR | &H88980020 | The method was unable to open the file.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

When performing a partial or delta import (when updating an existing catalog by importing new or changed catalog data), it is important that the schema of the data being imported matches the schema of the existing catalog. For more information about the catalog schema, see Import Semantic.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Note

  • This method runs in a separate thread. Prior to spawning the thread, it checks that the specified file can be opened and that there is not an existing ExportCSV, ExportXML, ImportCSV or ImportXMLmethod in progress. Once the new thread is spawned, this method returns immediately, if fRunSynchronously is False, with no errors. Any errors that occurred while importing the catalog are logged to the Windows NT Event Log. Use the Windows Event Viewer to view the Windows NT Event Log.

  • This method cannot be called in a transacted object. This method involves the creation, deletion, or updating of free text indexes. SQL Server does not allow these operations in a transaction.

  • If there is a temporary loss of the SQL connection, longer than two minutes, an import or export will be aborted. Other methods should work after the interruption.

  • The names of catalogs in the source file cannot begin with "#" or consist solely of spaces.

  • If a property existing in the catalog has one type and the property of the same name existing in the import file has a different type, the import will fail. For example, the catalog has a SKU property that is a string, and the XML file being imported has a SKU property that is an integer. This will cause an error.

Example

myCatalogManager.ImportXML "c:\imports\ourcatalog.xml", TRUE

See Also

CatalogManager Object

CatalogManager.ExportXML

CatalogManager.ImportCSV


CatalogManager.Initialize

Use this method to initialize a CatalogManager object. This method should be called once before calling any other methods or properties.

Definition

Sub Initialize(
strConfigString As String,
fIsADOConnectionString As Boolean
)

Parameters

strConfigString

A String that contains the configuration string.

fIsADOConnectionString

A Boolean that determines whether the strConfigString parameter refers to an ADO connection string or a site name. A value of True indicates an ADO connection string. A value of False indicates a site name.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_CATMGR_ALREADY_INITIALIZED | &H88980062 | The CatalogManager objects was already initialized.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

myCatalogManager.Initialize strConfigString, TRUE

See Also

CatalogManager Object


CatalogManager.ProductDefinitions

The ProductDefinitions property is a read-only Recordset object that contains the names of all the product definitions in the Product Catalog System.

Definition

Property ProductDefinitions() As _Recordset

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The Recordset object contains valid data only if the property was accessed successfully.

The returned recordset will contain a single field called DefinitionName and one row for each product definition in the Product Catalog System. This field is a 128 character String.

If no product definitions are currently in the Product Catalog System, then the EOF property of the returned recordset will be set to VARIANT_TRUE.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CatalogManager Object

CatalogManager.CreateProductDefinition

CatalogManager.DeleteDefinition


CatalogManager.Properties

The Properties property is a read-only recordset that returns the name of each property that currently exists in the Product Catalog System. If the catalog name is specified, only properties used in that catalog are returned.

Definition

Function Properties(
Optional strCatalogName As Variant
) As _Recordset

Parameters

strCatalogName

A Variant that contains the name of the catalog for which the properties are returned. If this optional parameter is omitted, all properties are returned.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The Recordset object contains valid data only if the property was accessed successfully.

This method returns a Recordset object containing a row for each property returned. For more information about the fields in this Recordset object, see PropertyAttribute Recordset.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

Set rsProps = myCatalogManager.Properties ("ShoesCatalog")

See Also

CatalogManager Object

CatalogManager.CreateProperty

CatalogManager.DeleteProperty


CatalogManager.Query

Use this method to perform queries against product, variant, and category data in one or more catalogs.

Definition

Function Query(
strPhrase As String,
Optional strCatalogsToSearch As Variant,
Optional eClassTypeRequired As Variant,
Optional strPropertiesToReturn As Variant,
Optional strPropertyToSortOn As Variant,
Optional fSortAscending As Boolean,
Optional lStartingRecord As Variant,
Optional lRecordsToRetrieve As Variant,
Optional plTotalRecordsInQuery As Variant
) As _Recordset

Parameters

strPhrase

A String that contains the search phrase.

strCatalogsToSearch

A Variant that contains the catalogs to search as a comma-separated list. An empty string indicates search all catalogs.

eClassTypeRequired

A Variant that contains the catalog class desired. Valid values are from the CatalogClassTypeEnum enumeration, and are described in the Remarks section below.

strPropertiesToReturn

A Variant that contains the properties to return as a comma-separated list.

strPropertyToSortOn

A Variant that contains the property on which to sort.

fSortAscending

A Boolean that specifies whether to sort in ascending or descending order. A value of True indicates that the returned recordset will be sorted in ascending order. A value of False indicates that the returned recordset will be sorted in descending order. The default value is True.

lStartingRecord

A Variant that contains the starting record to retrieve. This is an offset from the first record.

lRecordsToRetrieve

A Variant that contains the number of records to retrieve, beginning from the starting record.

plTotalRecordsInQuery

A Variant used to return the total number of records matching the query.

Return Values

If this method completes successfully, it returns a Recordset object containing the search results.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_MULTI_CAT_QUERY_NEEDS_PROPS | &H8898000F | The strPropertiesToReturn parameter must be specified if the search is done across multiple catalogs.
E_CAT_NO_CATALOGS | &H88980013 | There were no catalogs in the Product Catalog System.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The returned Recordset object and the plTotalRecordsInQuery parameter contain valid data only if the method completes successfully.

The Query method is used to perform arbitrary queries against product, product-variant, and category data in one or more catalogs. The strPhrase parameter is very similarly to the ADO recordset Filter property. Simple queries should follow the key-operator-value convention (for example, length < 100). Queries whose value is a String data type should enclose that value in single quotes (for example, color = 'Blue').

More sophisticated queries can be constructed by using the AND and OR operators to group multiple clauses, such as (level > 10) OR (Name = 'Bob' AND Title='CPA').

The programming rules regarding the strPropertiesToReturn parameter vary depending if a single catalog name is passed in the strCatalogsToSearch parameter, or if multiple catalog names are passed. When a single catalog name is passed, the strPropertiesToReturn parameter is optional and defaults to all properties. When multiple catalog names are passed, the strPropertiesToReturn parameter is required.

The following table shows the values of the CatalogClassTypeEnum enumeration, their associated names, and describes their use.

Name | Value | Description
cscCategoryClass | 1 | Requests category data.
cscProductVariantClass | 2 | Requests product variant data.
cscProductClass | 4 | Requests product data.
cscProductFamilyClass | 8 | Requests product family data.
cscProductFamilyForVariantsClass | 16 | Requests family for variant data, which means the product family of a product variant is being requested.
CscProductVariantsForFamily | 32 | Requests variants for family data, which means that all of the product variants for a product family are being requested.

CatalogClassTypeEnum values can be combined in the eClassTypeRequired parameter with logical OR operators, so that specifying cscProductClass OR cscProductVariantClass will return both product and product variant data.

If no value is specified for the strPropertiesToReturn parameter the method returns all fields in the specified catalog, otherwise it returns only the fields specified in the strPropertiesToReturn parameter.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

'plTotalRecordsInQuery is an existing Long.
'Examine it after the method returns to see if
'there are more records to get.
Set rsQueryResults = myCatalogManager.Query("Productid='blue suede'", "ShoeCatalog", cscProductClass,"Price, SKU, Size", "SKU", TRUE, 1, 25, plTotalRecordsInQuery)

See Also

CatalogManager Object

CatalogManager.FreeTextSearch


CatalogManager.RemoveDefinitionProperty

Use this method to remove the specified property or variant property from the specified definition.

Definition

Sub RemoveDefinitionProperty(
strDefinitionName As String,
strPropertyName As String
)

Parameters

strDefinitionName

A String that contains the name of the definition for which the specified property will be removed.

strPropertyName

A String that contains the name of the property to be removed.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_DEFINITION_DOESNT_EXIST | &H8898000B | The specified definition did not exist.
E_CAT_PROP_NOT_IN_DEFINITION | &H8898000E | The specified property was not included in this definition.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

When you remove a property from a definition, it is also removed from any products, product-variants, or categories created from that definition.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Caution

  • Use caution when using this method. In most cases, calling this method results in the deletion of data.

  • Removing the last variant property in a product family definition will convert it to a product definition and will remove all existing product variants based on this definition.

Example

myCatalogManager.RemoveDefinitionProperty "T-Shirts", "Color"

See Also

CatalogManager Object

CatalogManager.AddDefinitionProperty

CatalogManager.AddDefinitionVariantProperty

CatalogManager.GetDefinitionProperties


CatalogManager.RemovePropertyValue

Use this method to remove a defined value from an enumeration property.

Definition

Sub RemovePropertyValue(
strPropertyName As String,
strLegalValue As String
)

Parameters

strPropertyName

A String that contains the name of the enumeration property from which the specified value will be removed.

strLegalValue

A String that contains the defined value to be removed as a choice from the specified enumeration property.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_PROP_DOESNT_EXIST | &H88980005 | The specified property did not exist.
E_CAT_PROP_NOT_ENUM | &H88980007 | The specified property was not of type cscEnumeration. Call this method only for enumeration type properties.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Caution

  • When a value is removed from an enumeration type property all products that have that property set to that value will have the value changed to NULL.

Example

myCatalogManager.RemovePropertyValue "Color", "Pink"

See Also

CatalogManager Object

CatalogManager.AddPropertyValue

CatalogManager.GetPropertyValues


CatalogManager.RenameDefinition

Use this method to rename a definition.

Definition

Sub RenameDefinition(
strOldName As String,
strNewName As String
)

Parameters

strOldName

A String that contains the existing name of the definition.

strNewName

A String that contains the wanted name of the definition.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_DEFINITION_DOESNT_EXIST | &H8898000B | The specified old definition name did not exist.
E_CAT_DEFINITION_EXISTS | &H8898000A | A definition with the specified new name already existed.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

This method affects every product and category using the definition.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

myCatalogManager.RenameDefinition "T-Shirts", "Tee-Shirts"

See Also

CatalogManager Object

CatalogManager.RenameProperty


CatalogManager.RenameProperty

Use this method to rename a property.

Definition

Sub RenameProperty(
strOldPropertyName As String,
strNewPropertyName As String
)

Parameters

strOldPropertyName

A String that contains the existing name of the property.

strNewPropertyName

A String that contains the wanted name of the property.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_PROP_DOESNT_EXIST | &H88980005 | The specified old property name did not exist.
E_CAT_PROP_EXISTS | &H88980003 | A property with the specified new property name already existed.
E_CAT_PROP_IS_ID | &H88980011 | The property name you specified was used as a ProductID or VariantID of a catalog. These properties are specified when a catalog is created and cannot be renamed or deleted.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

myCatalogManager.RenameProperty "Weight", "Wt."

See Also

CatalogManager Object

CatalogManager.RenameDefinition


CatalogManager.SetDefinitionProperties

Use this method to change the properties of a category or product definition.

Definition

Sub SetDefinitionProperties(
strDefinitionName As _String,
pRSNewState As _Recordset,
)

Parameters

strDefinitionName

A String that contains the name of the definition.

pRSProperties

A _Recordset that specifies the new properties.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_PROP_DOESNT_EXIST | &H88980005 | There was no property with the name you specified.
E_CAT_PROP_CHANGED | &H88980006 | The attributes of the property have changed since the property was last read. This error occurs when the sForceUpdate parameter is False, and the attributes were modified after a call to the CreateProperty or GetPropertyAttributes methods.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

myCatalogManager.SetDefinitionProperties "Shirt",pRSProperties

See Also

CatalogManager Object

CatalogManager.CreateProperty


CatalogManager.SetPropertyAttributes

Use this method to change the attributes of a property.

Definition

Sub SetPropertyAttributes(
pRSNewState As _Recordset,
Optional fForceUpdate As Variant
)

Parameters

pRSNewState

A _Recordset object that specifies the new attribute values.

fForceUpdate

A Variant that specifies whether or not to force an update.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_PROP_CHANGED | &H88980006 | The attributes of the property have changed since the property was last read. This error occurs when the sForceUpdate parameter is False, and the attributes were modified after a call to the CreateProperty or GetPropertyAttributes methods.
E_CAT_PROP_DOESNT_EXIST | &H88980005 | There was no property with the name you specified.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Use a Recordset object returned from either the GetPropertyAttributes method or the CreateProperty method as the pRSNewState parameter so that its timestamp can be compared with the timestamp of the existing property for error detection. You can change all attributes for a property except its data type.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

myCatalogManager.SetPropertyAttributes pRSNewState, TRUE

See Also

CatalogManager Object

CatalogManager.CreateProperty

CatalogManager.GetPropertyAttributes


PropertyAttribute Recordset

The PropertyAttribute recordset reflects the property definitions found in the CatalogAttributes table.

The following table shows the fields in the PropertyAttribute Recordset.

Field name | Data type
PropertyName | String
DataType | Small integer
u_DefaultValue | String
i_DefaultValue | Integer
dt_DefaultValue | datetime
cy_DefaultValue | money
f_DefaultValue | bit
fp_DefaultValue | float
i_MinValue | Integer
i_MaxValue | Integer
dt_MinValue | datetime
dt_MaxValue | datetime
fp_MinValue | float
fp_MaxValue | float
IsFreeTextSearchable | bit
IncludeInSpecSearch | bit
MinLength | Integer
MaxLength | Integer
cy_MinValue | money
cy_MaxValue | money
TimeStamp | timestamp
DisplayOnSite | bit
DisplayName | String
AssignAll | bit
ExportToDW | bit
DisplayInProductsList | bit


CatalogSets Object

Use this object to work with catalog sets in the catalog management system. Catalog sets allow you to present different collections of catalogs to different users and organizations.

ProgID: | Commerce.CatalogSets (Externally creatable)
COM Class Name: | CatalogSets
Type Library Name: | Microsoft Commerce 2000 Catalog Sets Type Library
DLL Name: | CatalogSets.dll
Threading Model: | Apartment

The methods of the CatalogSets object are shown in the following table.

Method | Description
CreateCatalogSet | Creates a new catalog set.
DeleteCatalogSet | Deletes the specified catalog set.
GetCatalogs | Returns a list of all catalogs.
GetCatalogSetIDForUser | Returns the catalog set ID for a user.
GetCatalogSetInfo | Returns information about the specified catalog set.
GetCatalogSets | Returns a list of all catalog sets.
GetCatalogsForUser | Returns a list of catalogs associated with the specified user.
GetCatalogsInCatalogSet | Returns a list of catalogs associated with the specified catalog set.
GetCatalogsNotInCatalogSet | Returns a list of all catalogs not associated with the specified catalog set.
Initialize | Initializes the CatalogSets object.
RemoveCatalogFromCatalogSets | Remove a catalog from all catalog sets.
UpdateCatalogSet | Allows modification of an existing catalog set.


CatalogSets.CreateCatalogSet

Use this method to create a new catalog set in the catalog database.

Definition

Function CreateCatalogSet(
CatalogSetName As String,
CatalogSetDescription As String,
bWildCard As Boolean,
Optional CatalogNamesRS As _Recordset
) As String

Parameters

CatalogSetName

A String that contains a name for the new catalog set. The maximum length is 128 characters.

CatalogSetDescription

A String that contains a description of the new catalog set.

bWildCard

A Boolean that indicates whether this catalog set should automatically include all catalogs, including any new catalogs that might be created in the future. A value of True indicates that this catalog set includes all existing catalogs. A value of False indicates that this catalog set only includes a specific set of catalogs.

CatalogNamesRS

A reference to an ADO Recordset object that specifies the catalogs to be included in the new catalog set. The Recordset object should contain a single column named CatalogName, and one row per catalog to be included. If the bWildCard parameter is True, then this parameter will be ignored.

Return Values

If this method completes successfully, it returns a String that contains the ID of the new catalog set.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The returned String contains a valid ID only if the new catalog set was created successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

'The following example shows the creation of a catalog set
'associated with all the catalogs in the catalog management system.
strCatalogSetID = myCatalogSets.CreateCatalogSet("PremiumCatalogs", "Premium catalog set", TRUE)

'The following example shows the creation of a catalog set
'associated with two specific catalogs.
set rsCatalogNames = CreateObject("ADODB Recordset")
call rsCatalogNames.Fields.Append("CatalogName", adBSTR)
rsCatalogNames.Open
rsCatalogNames.AddNew
rsCatalogNames.Fields("CatalogName").value = "Catalog1"
rsCatalogNames.Update
rsCatalogNames.AddNew
rsCatalogNames.Fields("CatalogName").value = "Catalog2"
rsCatalogNames.Update

strCatalogSetID = myCatalogSets.CreateCatalogSet("CombinedCatalog", "A one and a two", FALSE, rsCatalogNames)

See Also

CatalogSets Object


CatalogSets.DeleteCatalogSet

Use this method to delete an existing catalog set from the Catalog database.

Definition

Sub DeleteCatalogSet(
CatalogSetID As String
)

Parameters

CatalogSetID

A String that contains the ID of the catalog set to be deleted.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Deleting a catalog set does not delete the catalog set ID. Referencing an invalid catalog set ID will prevent access to the solution sites.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

'strCatalogSetID1 is a GUID
myCatalogSets.DeleteCatalogSet strCatalogSetID1

See Also

CatalogSets Object


CatalogSets.GetCatalogs

Use this method to return a list of all catalogs.

Definition

Function GetCatalogs() As Recordset

Parameters

None.

Return Values

If this method completes successfully, it returns a Recordset object that contains the list of all catalogs

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The Recordset object returned by this method contains valid data only if the method completes successfully.

The Recordset object returned by this method has a single 128 character field, named CatalogName.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

set rsMyCatalogs = myCatalogSets.GetCatalogs()

See Also

CatalogSets Object


CatalogSets.GetCatalogSetIDForUser

Use this method to return the CatalogSetID for a specific user.

Definition

Function GetCatalogSetIDForUser(
objProfileService As IDispatch,
user_id As String,
defaultCatalogSetID As String
) As Variant

Parameters

objProfileService

A ProfileService object.

user_id

A String that contains the user ID.

defaultCatalogSetID

A String that contains the default catalog set ID.

Return Values

If this method completes successfully, it returns a Variant that contains the CatalogSetID.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The Variant returned by this method contains valid data only if the method completes successfully.

If the user defined in the objProfileService parameter has a catalog set associated with it, this method returns that ID; if not, it returns the catalog set associated with the user organization. If this catalog set does not exist, it returns the value supplied in the defaultCatalogSetID parameter.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

strCatalogSetID = myCatalogSets.GetCatalogSetIDForUser(oProfileService, user_id, defaultCatalogSetID)

See Also

CatalogSets Object

ProfileService Object


CatalogSets.GetCatalogSetInfo

Use this method to return the basic properties for a catalog set.

Definition

Function GetCatalogSetInfo(
CatalogSetID As String
) As Recordset

Parameters

CatalogSetID

A String that contains the catalog set ID, a GUID.

Return Values

If this method completes successfully, it returns a Recordset object.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The Recordset object returned by this method contains valid data only if the method completes successfully.

This method returns a forward-only Recordset object with a single row and the following fields:

Field | Type | Description
CatalogSetID | GUID | None
CatalogSetName | String, maximum of 255 characters | None
CatalogSetDescription | String, maximum of 255 characters | None
bWildCard | Integer | A Boolean that indicates whether this catalog set automatically includes all catalogs, including any new catalogs that might be created in the future. A value of True indicates that this catalog set includes all existing catalogs. A value of False indicates that this catalog set only includes a specific set of catalogs.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

'
set rsMyCatalogSetInfo = myCatalogSets.GetCatalogSetInfo(strCatalogSetID)

See Also

CatalogSets Object


CatalogSets.GetCatalogSets

Use this method to return a list of all catalog sets.

Definition

Function GetCatalogSets() As Recordset

Parameters

None.

Return Values

If this method completes successfully, it returns a Recordset object that contains the list of all catalog sets.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The Recordset object returned by this method contains valid data only if the method completes successfully.

This method returns a forward-only Recordset object with a row for each catalog set and the following fields:

Field | Type | Description
CatalogSetID | GUID | None
CatalogSetName | String, 255 characters | None
CatalogSetDescription | String, 255 characters | None
bWildCard | Integer | A Boolean that indicates whether this catalog set automatically includes all catalogs, including any new catalogs that might be created in the future. A value of True indicates that this catalog set includes all existing catalogs. A value of False indicates that this catalog set only includes a specific set of catalogs.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

set rsMyCatalogSets = myCatalogSets.GetCatalogSets()

See Also

CatalogSets Object


CatalogSets.GetCatalogsForUser

Use this method to return the list of catalogs that have been assigned to a particular user through the catalog set specified in their profile.

Definition

Function GetCatalogsForUser(
objProfileService As IDispatch,
user_id As String,
defaultCatalogSetID As String
) As Recordset

Parameters

objProfileService

A profile service object.

user_id

A String that contains the user ID.

defaultCatalogSetID

A String that contains the default catalog set ID.

Return Values

If this method completes successfully, it returns a Recordset object that contains the list of catalogs.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The Recordset object returned by this method contains valid data only if the method completes successfully.

This method returns a Recordset object with a row for each catalog in the catalog set associated with the user profile in the user_id parameter and the following fields:

Field | Type | Description
CatalogName From the CatalogSet_Catalogs table. | String maximum of 255 characters | None
CatalogName From the CatalogGlobal table. | String maximum of 128 characters | None

If the user profile object passed to this method has not been initialized, the object will return the default catalog set.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

Set objProfileService = Server.CreateObject("Commerce.ProfileService")
Call objProfileService.Initialize(sProfileServiceConnectionString, "Profile Definitions")
set rsCatalogSet = myCatalogSets.GetCatalogsForUser(objProfileService, user_id, defaultCatalogSetID)

See Also

CatalogSets Object


CatalogSets.GetCatalogsInCatalogSet

Use this method to return the catalogs that are included in a particular catalog set.

Definition

Function GetCatalogsInCatalogSet(
CatalogSetID As String
) As Recordset

Parameters

CatalogSetID

A String that contains the catalog set ID.

Return Values

If this method completes successfully, it returns a Recordset object that contains the list of catalogs.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The Recordset object returned by this method contains valid data only if the method completes successfully.

This method returns a Recordset object with a row for each catalog in the catalog set and the following fields:

Field | Type | Description
CatalogName From the CatalogSet_Catalogs table. | String maximum of 255 characters | None
CatalogName From the CatalogGlobal table. | String maximum of 128 characters | None

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

set rsCatalogNames = myCatalogSets.GetCatalogsInCatalogSet(CatalogSetID)

See Also

CatalogSets Object


CatalogSets.GetCatalogsNotInCatalogSet

Use this method to return the catalogs that are not included in a specified catalog set.

Definition

Function GetCatalogsNotInCatalogSet(
CatalogSetID As String
) As Recordset

Parameters

CatalogSetID

A String that contains the catalog set ID.

Return Values

If this method completes successfully, it returns a Recordset object.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The Recordset object returned by this method contains valid data only if the method completes successfully.

The Recordset object returned by this method has a single 128 character field, named CatalogName.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

'strCatalogSetID is the GUID of a catalog set
set rsCatalogs = myCatalogSets.GetCatalogsNotInCatalogSet(strCatalogSetID)

See Also

CatalogSets Object


CatalogSets.Initialize

Use this method to initialize a new CatalogSet object.

Definition

Sub Initialize(
CatalogConnectionString As String,
TransactionConfigConnectionString As String
)

Parameters

CatalogConnectionString

A String that contains the catalog connection string.

TransactionConfigConnectionString

A String that contains the transaction configuration connection string. Not used.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Note

  • The TransactionConfigConnectionString parameter is required, but not used. The contents of the String are ignored. This parameter is reserved for future use.

Example

myCatalogSets.Initialize strCatalogConnection, ""

See Also

CatalogSets Object


CatalogSets.RemoveCatalogFromCatalogSets

Use this method to remove a catalog from all catalog sets.

Definition

Sub RemoveCatalogFromCatalogSets(
CatalogName As String
)

Parameters

CatalogName

A String that contains the catalog name to be removed.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

This method should be called whenever a catalog is deleted, before or after calling the CatalogManager.DeleteCatalog or ProductCatalog.DeleteCustomCatalog methods.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

MyCatalogManager.DeleteCatalog "Shoes"
myCatalogSets.RemoveCatalogFromCatalogSets "Shoes"

See Also

CatalogSets Object


CatalogSets.UpdateCatalogSet

Use this method to update an existing catalog set and its basic properties.

Definition

Sub UpdateCatalogSet(
CatalogSetID As String,
CatalogSetName As String,
CatalogSetDescription As String,
bWildCard As Boolean,
Optional CatalogNamesRS As Recordset
)

Parameters

CatalogSetID

A String that contains the catalog set ID (GUID).

CatalogSetName

A String that contains the catalog set name. The maximum length is 128 characters.

CatalogSetDescription

A String that contains the catalog set description.

bWildCard

A Boolean that indicates which catalogs to use. A value of True indicates use all catalogs. A value of False indicates use the catalogs contained in the CatalogNameRS parameter.

CatalogNamesRS

A Recordset object that contains the catalog names.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

'strCatalogSetID is the GUID for the CatalogSet.
'rsCatalogNames is a Recordset as described in the parameter description.

myCatalogSets.UpdateCatalogSet strCatalogSetID, "Clothing", "All soft goods", FALSE, rsCatalogNames

See Also

CatalogSets Object


CatalogToVendorAssociation Object

Use this object to associate catalogs with vendors.

ProgID: | Commerce.CatalogToVendorAssociation (Externally creatable)
COM Class Name: | CatalogToVendorAssociation
Type Library Name: | Microsoft Commerce 2000 Catalog Vendor Association Type Library
DLL Name: | CatalogVendorAssociation.dll
Threading Model: | Apartment

The methods of the CatalogToVendorAssociation object are shown in the following table.

Method | Description
GetVendorInfoForCatalog | Returns information about the vendor associated with the specified catalog.
GetVendorList | Returns a list of vendors available for association with catalogs.
Initialize | Initializes a CatalogToVendorAssociation object by connecting to the appropriate database.
SpecifyVendorForCatalog | Associates the specified vendor and catalog.
UnspecifyVendorForCatalog | Disassociates the specified vendor and catalog.


CatalogToVendorAssociation.GetVendorInfoForCatalog

Use this method to retrieve information about the vendor associated with the specified catalog.

Definition

Function GetVendorInfoForCatalog(
szCatalogID As String
) As Recordset

Parameters

szCatalogID

A String that contains the ID of the catalog for which vendor information will be returned.

Return Values

If this method completes successfully, it returns an ADO Recordset object containing the requested vendor information.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The returned ADO RecordSet object will contain valid data only if the method completed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

set rsVendorInfo = myCatalogToVendorAssociation.GetVendorInfoForCatalog(szCatalogID)

See Also

CatalogToVendorAssociation Object


CatalogToVendorAssociation.GetVendorList

Use this method to retrieve a list of vendors associated with the passed alias qualifier and value, and associated with the input document name.

Definition

Function GetVendorList(
szSourceAliasQualifier As String,
szSourceAliasValue As String,
szInputDocumentName As String
) As Recordset

Parameters

szSourceAliasQualifier

A String that contains the source alias qualifier.

szSourceAliasValue

A String that contains the source alias value.

szInputDocumentName

A String that contains the input document name.

Return Values

If this method completes successfully, it returns an ADO Recordset object containing the requested list of vendors.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The returned ADO RecordSet object will contain valid data only if the method completed successfully.

Note

  • This method is only available when BizTalk Server is installed. It requires the BizTalKDBInternal object.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

set rsVendorList = myCatalogToVendorAssociation.GetVendorList(szSourceAliasQualifier, szSourceAliasValue, szInputDocumentName)

See Also

CatalogToVendorAssociation Object


CatalogToVendorAssociation.Initialize

Use this method to initialize a CatalogToVendorAssociation object.

Definition

Sub Initialize(
vConnectionString As String
)

Parameters

vConnectionString

A String that contains the connection string for the database containing the catalog to vendor associations.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

myCatalogToVendorAssociation.Initialize vConnectionString

See Also

CatalogToVendorAssociation Object


CatalogToVendorAssociation.SpecifyVendorForCatalog

Use this method to associate a vendor with a particular catalog.

Definition

Sub SpecifyVendorForCatalog(
szCatalogID As String,
szVendorQualifier As String,
szVendorQualifierValue As String,
szVendorName As String
)

Parameters

szCatalogID

A String that contains the identifier of the catalog with which to associated the specified vendors.

szVendorQualifier

A String that contains the qualifier of the vendor to be associated with the specified catalog.

szVendorQualifierValue

A String that contains the qualifier value of the vendor to be associated with the specified catalog.

szVendorName

A String that contains the name of the vendor to be associated with the specified catalog.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

myCatalogToVendorAssociation.SpecifyVendorForCatalog szCatalogID, szVendorQualifier, szVendorQualifierValue, szVendorName

See Also

CatalogToVendorAssociation Object


CatalogToVendorAssociation.UnspecifyVendorForCatalog

Use this method to disassociate a catalog with any previously associated vendors.

Definition

Sub UnspecifyVendorForCatalog(
szCatalogID As String
)

Parameters

szCatalogID

A String that contains the identifier of the catalog for which no vendors should be associated.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

myCatalogToVendorAssociation.UnspecifyVendorForCatalog szCatalogID

See Also

CatalogToVendorAssociation Object


Category Object

Use this object to work with relationships between categories and products. You can also use this object to manipulate parent/child relationships for a category.

ProgID: | Dependent (See Remarks for more information)
COM Class Name: | Category
Type Library Name: | Microsoft Commerce 2000 Catalog Type Library
DLL Name: | Catalog.dll
Threading Model: | Both

The properties of the Category object are shown in the following table.

Property | Type | Description
AncestorCategories | Recordset | Contains a recordset of category names that exist anywhere above this category, and that directly or indirectly contain this category, in the hierarchy. This property is read-only.
CatalogName | String | Contains the name of the catalog of which this Category object is a member. This property is read-only.
CategoryName | BSTR | Contains the name of this category. This property is read-only.
ChildCategories | Recordset | Contains a recordset containing the child Category objects for this category. This property is read-only.
DescendantProducts | Recordset | Contains all products that exist anywhere below this category. Accessing this property on the root category returns every product in the entire catalog. This property is read-only.
GetCategoryProperties | Recordset | Contains a recordset containing the property values for this category. This property is read-only.
ParentCategories | Recordset | Contains a recordset containing the names of the Category objects that are parent categories to this category. This property is read-only.
Products | Recordset | Contains the products that exist within this category, but not within descendant categories. This property is read-only.
RelatedCategories | Recordset | Contains a recordset that describes all of the categories and product families that have relationships to this category. This property is read-only.
RelatedProducts | Recordset | Contains a recordset that describes all the product variants and product families that have relationships to this category. This property is read-only.

The methods of the Category object are shown in the following table.

Method | Description
AddChildCategory | Adds another specified category as a child of this category.
AddParentCategory | Adds another specified category as a parent of this category.
AddProduct | Adds another specified product variant as a child of this category.
AddRelationshipToCategory | Adds a relationship from another category to this category.
AddRelationshipToProduct | Adds a relationship from this category to a specified product.
RemoveChildCategory | Removes the specified category as a child of this category.
RemoveParentCategory | Removes the specified category as a parent of this category.
RemoveProduct | Removes a product from this category.
RemoveRelationshipToCategory | Removes the relationship between this category and a specified category.
RemoveRelationshipToProduct | Removes the relationship between this category and a specified product.
SetCategoryProperties | Assigns new properties to a category.

Remarks

The Category object is a dependent object. Obtain a reference to it by calling one of the following methods:

  • ProductCatalog.CreateCategory

  • ProductCatalog.GetCategory


Category.AddChildCategory

Use this method to add a category as a child to this category.

Definition

Sub AddChildCategory(
strCategoryName As String
)

Parameters

strCategoryName

A String that contains the name of the category to be added as a child to this category.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_CATEGORY_ALREADY_ADDED | &H8898002D | The specified category has already been added as child to this category.
E_CAT_CATEGORY_DOESNT_EXIST | &H8898001C | The specified category did not exist.
E_CAT_INVALID_CHILDCATEGORY | &H8898005D | The category that you specified already exists as a parent of this category.
E_CAT_INVALID_RELATION | &H88980039 | A category cannot be a parent or child of itself.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

myCategory.AddChildCategory "shirts"

See Also

Category Object

Category.AddParentCategory

Category.RemoveChildCategory


Category.AddParentCategory

Use this method to add the specified category as a parent of this category.

Definition

Sub AddParentCategory(
strCategoryName As String
)

Parameters

strCategoryName

A String that contains the name of the category to be added as a parent to this category.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_CATEGORY_ALREADY_ADDED | &H8898002D | The specified category was already a child of this category.
E_CAT_CATEGORY_DOESNT_EXIST | &H8898001C | The specified category did not exist.
E_CAT_PARENT_CAT_EXISTS_AS_CHILD | &H88980052 | The category that you specified as a parent category already existed as a child category for this category.
E_CAT_INVALID_RELATION | &H88980039 | A category cannot be a parent or child of itself.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

myCategory.AddParentCategory "Apparel"

See Also

Category Object

Category.AddChildCategory

Category.RemoveParentCategory


Category.AddProduct

Use this method to add the specified product to this category.

Definition

Sub AddProduct(
varProductID As Variant
)

Parameters

varProductID

A Variant that contains the of the product to be added.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_PRODUCT_DOESNT_EXIST | &H8898001E | The specified product did not exist in the catalog.
E_CAT_PRODUCT_ALREADY_ADDED | &H88980029 | The specified product was already in this category.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

A product may exist in multiple categories simultaneously, without limit.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

myCategory.AddProduct "SKU4005"

See Also

Category Object

Category.RemoveProduct


Category.AddRelationshipToCategory

Use this method to add a relationship from this category to another specified category.

Definition

Sub AddRelationshipToCategory(
strRelatedCategoryName As String,
strRelationshipName As String,
Optional strRelationshipDescription As Variant
)

Parameters

strRelatedCategoryName

A String that contains the name of the category to which a relationship is to be added.

strRelationshipName

A String that contains a name for the relationship.

strRelationshipDescription

A Variant of sub type String that contains an optional description for the relationship.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_CATEGORY_DOESNT_EXIST | &H8898001C | The specified category did not exist.
E_CAT_INVALID_RELATION | &H88980039 | The relationship was invalid. A category or product cannot be related to itself.
E_CAT_INVALID_RELATION_DESC | &H88980055 | The relationship description exceeded 256 characters.
E_CAT_INVALID_RELATION_NAME | &H88980054 | The relationship name exceeded 128 characters.
E_CAT_RELATIONSHIP_EXISTS | &H88980033 | The specified relationship already existed.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

A relationship must be given a name and may optionally be given a description. The description can include information that describes the nature of the relationship between the categories (for example, an "accessory" or "add-on"). Relationships are one way, that is, if category A has a relationship to category B that does not create a reciprocal relationship from category B to category A.

When multiple relationships are created between the same two categories, each relationship must have a unique name.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

myCategory.AddRelationshipToCategory "Apparel", "Accessory", "This would go great with that!"

See Also

Category Object

Category.RemoveRelationshipToCategory


Category.AddRelationshipToProduct

Use this method to add a relationship between the specified product and this category. This relationship must be given a name and may optionally be given a description. The description can include information that describes the nature of the relationship between the categories (for example, an "accessory" or "add-on").

Definition

Sub AddRelationshipToProduct(
varRelatedProductID As Variant,
strRelationshipName As String,
Optional strRelationshipDescription As Variant
)

Parameters

varRelatedProductID

A Variant that contains the ID of the related product.

strRelationshipName

A String that contains a name for the relationship.

strRelationshipDescription

A Variant that contains an optional description for the relationship.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_INVALID_RELATION | &H88980039 | The relationship was invalid. A category or product cannot be related to itself
E_CAT_INVALID_RELATION_DESC | &H88980055 | The relationship description exceeded 256 characters
E_CAT_INVALID_RELATION_NAME | &H88980054 | The relationship name exceeded 128 characters
E_CAT_PRODUCT_DOESNT_EXIST | &H8898001E | The specified product did not exist.
E_CAT_RELATIONSHIP_EXISTS | &H88980033 | There was already a relationship with the specified product.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

In order for this method to complete successfully, the product identified must already exist.

When multiple relationships are created between a category and product, each relationship must have a unique name.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

myCategory.AddRelationshipToProduct "SKU4005", "Accessory", "This would go great with that"

See Also

Category Object

Category.RemoveRelationshipToProduct


Category.AncestorCategories

The AncestorCategories property is a read-only Recordset object that contains the names of categories that exist anywhere above this category in the hierarchy

Definition

Property AncestorCategories() As Recordset

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The AncestorCategories property contains valid data only if it was accessed successfully.

The AncestorCategories property is a Recordset object with a single 128-character field, named Name.

See Also

Category Object

Category.ParentCategories

Category.ChildCategories


Category.CatalogName

The CatalogName property is a read-only String that contains the name of the catalog within which this category exists.

Definition

Property CatalogName() As String

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The CatalogName property contains valid data only if the property is accessed successfully.

See Also

Category Object


Category.CategoryName

The CategoryName property is a read-only String that contains the name of this category.

Definition

Property CategoryName() As String

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The CategoryName property contains valid data only if the property is accessed successfully.

See Also

Category Object


Category.ChildCategories

The ChildCategories property is a read-only Recordset object that contains the names of categories that exist below this category in the hierarchy.

Definition

Property ChildCategories() As Recordset

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The ChildCategories property contains valid data only if the property is accessed successfully.

The ChildCategories recordset contains a row for each of the categories that are currently children of this category. The following table lists the fields for the ChildCategories recordset.

Field Data Type Description
CategoryName String
maximum of 128 characters 		The name of the category.
DefinitionName String
maximum of 128 characters 		The name of the definition.
CatalogName String
maximum of 128 characters 		The name of the Catalog that contains the category.

If this category has no children, an empty recordset is returned whose EOF property is set to VARIANT_TRUE. Your code should check the value of this property to determine if child categories exist.

See Also

Category Object

Category.ParentCategories

Category.AncestorCategories


Category.DescendantProducts

The DescendantProducts property is a read-only Recordset object that contains all products that exist anywhere below this category. Accessing this property on the root category returns every product in the entire catalog.

Definition

Property DescendantProducts(
Optional eClassTypeRequired As Variant,
Optional lStartingRecord As Variant,
Optional lRecordsToRetrieve As Variant,
Optional plTotalRecordsInQuery As Variant
) As Recordset

Parameters

eClassTypeRequired

A Variant that contains the catalog class desired. Valid values are from the CatalogClassTypeEnum enumeration. For more information, see the Remarks section.

lStartingRecord

A Variant that contains the starting record.

lRecordsToRetrieve

A Variant that contains the number of records to retrieve.

plTotalRecordsInQuery

A Variant used to return the total number of records in the query.

Error Values

This property sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

This property gets all the products, which are directly or indirectly under this category.

The returned recordset contains all the fields in the CatalogProduct Recordset.

The following table shows the values of the CatalogClassTypeEnum enumeration, their associated names, and describes their use.

Name | Value | Description
cscCategoryClass | 1 | Requests category data.
cscProductVariantClass | 2 | Requests product variant data.
cscProductClass | 4 | Requests product data.
cscProductFamilyClass | 8 | Requests product family data.
cscProductFamilyForVariantsClass | 16 | Requests family for variant data, which means the product family of a product variant is being requested.
CscProductVariantsForFamily | 32 | Requests variants for family data, which means that all of the product variants for a product family are being requested.

CatalogClassTypeEnum values can be combined in the eClassTypeRequired parameter with logical OR operators, so that specifying cscProductClass OR cscProductVariantClass will return both product and product variant data.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Category Object

Category.RelatedProducts

Category.Products


Category.GetCategoryProperties

The GetCategoryProperties property is a read-only recordset that contains the properties for this category. Both the properties that are present in the definition of this category, and the built-in properties, are returned.

Definition

Property GetCategoryProperties() As Recordset

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_CATEGORY_DOESNT_EXIST | &H8898001C | This category has been removed from the catalog.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The GetCategoryProperties property contains valid data only if the property is accessed successfully.

The returned recordset contains all the common fields in the CatalogProduct Recordset. It also contains all the fields that are in the product definitions for the category. The ProductID field (the unique product identifier) is returned even if it is not part of a product definition.

The recordset returned is updateable, but disconnected. If this category has been deleted from the database, this property returns an error.

See Also

Category Object

Category.SetCategoryProperties


Category.ParentCategories

The ParentCategories property is a read-only recordset that contains the names of the parent categories of this category.

Definition

Property ParentCategories() As Recordset

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The ParentCategories property contains valid data only if the property is accessed successfully.

The ParentCategories property contains the names of the categories that are parent categories of this category. The recordset returned contains a single 128-character string column named Name, and one row for each parent that exists.

If this category is a root category, it has no parent categories, and an empty recordset is returned whose EOF property is set to VARIANT_TRUE.

See Also

Category Object

Category.AncestorCategories

Category.ChildCategories


Category.Products

The Products property is a read-only recordset that contains product data for all of the products that exist directly within this category.

Definition

Property Products(
Optional eClassTypeRequired As Variant,
Optional strPropertyToSortOn As Variant,
Optional lStartingRecord As Variant,
Optional lRecordsToRetrieve As Variant,
Optional plTotalRecordsInQuery As Variant
) As _Recordset

Parameters

eClassTypeRequired

A Variant that contains the catalog class desired. Valid values are from the CatalogClassTypeEnum enumeration. For more information, see the Remarks section.

strPropertyToSortOn

A Variant that contains the property to sort on.

lStartingRecord

A Variant that contains the starting record number.

lRecordsToRetrieve

A Variant that contains the number of records to retrieve.

plTotalRecordsInQuery

A Variant used to return the total number of records in the query.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

If the properties specified in strPropertyToSortOn parameter are invalid then the recordset will be unsorted.

Note

  • If the value of cscCategoryClass is specified for the eClassTypeRequired parameter, the returned recordset will contain all the products and all the child categories in this category.

The Products property contains the product data for all the products in this category.

The returned recordset contains all the fields in the CatalogProduct Recordset.

If this category contains no products, then the Products property returns an empty recordset whose EOF property is set to VARIANT_TRUE.

The following table shows the values of the CatalogClassTypeEnum enumeration, their associated names, and describes their use.

Name | Value | Description
cscCategoryClass | 1 | Requests category data.
cscProductVariantClass | 2 | Requests product variant data.
cscProductClass | 4 | Requests product data.
cscProductFamilyClass | 8 | Requests product family data.
cscProductFamilyForVariantsClass | 16 | Requests family for variant data, which means the product family of a product variant is being requested.
CscProductVariantsForFamily | 32 | Requests variants for family data, which means that all of the product variants for a product family are being requested.

CatalogClassTypeEnum values can be combined in the eClassTypeRequired parameter with logical OR operators, so that specifying cscProductClass OR cscProductVariantClass will return both product and product variant data.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Category Object

Category.DescendantProducts

Category.RelatedProducts


Category.RelatedCategories

The RelatedCategories property is a read-only recordset that contains all categories related to this category.

Definition

Property RelatedCategories() As Recordset

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The RelatedCategories property contains information on all the relationships this category has to other categories. The recordset returned contains one row for each relationship present.

The returned recordset contains the following fields:

Field Data Type Description
CategoryName String
maximum of 128 characters 		The name of the category.
RelationshipName String
maximum of 128 characters 		The name of the relationship.
RelationshipDescription String
maximum of 256 characters 		The description of the relationship.

See Also

Category Object

Category.AncestorCategories

Category.ChildCategories

Category.ParentCategories

Category.AddRelationshipToCategory

Category.RemoveRelationshipToCategory


Category.RelatedProducts

The RelatedProducts property is a read-only recordset containing information about all products related to this category.

Definition

Property RelatedProducts() As Recordset

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The recordset returned contains one row for each relationship present.

The following table shows the fields in the returned recordset.

Field | Data Type | Description
<defined ProductID field> | Varies | The unique product identifier, defined during catalog creation.
RelationshipName String
maximum of 128 characters 		The name of the relationship.
RelationshipDescription String
maximum of 256 characters 		The description of the relationship.

See Also

Category Object

Category.DescendantProducts

Category.Products

Category.AddRelationshipToProduct

Category.RemoveRelationshipToProduct


Category.RemoveChildCategory

Use this method to remove a category that is a child of this category.

Definition

Sub RemoveChildCategory(
strCategoryName As String
)

Parameters

strCategoryName

A String that contains the name of the category to be removed as a child of this category.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_CATEGORY_DOESNT_EXIST | &H8898001C | The category you specified either did not exist or was not a child of this category.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Use the RemoveChildCategory method to remove a child category from this category. If the category named in the strCategoryName parameter does not exist, then this method will fail.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

myCategory.RemoveChildCategory "T-Shirts"

See Also

Category Object

Category.AddChildCategory

Category.RemoveParentCategory


Category.RemoveParentCategory

Use this method to remove the specified category as a parent of this category.

Definition

Sub RemoveParentCategory(
strCategoryName As String
)

Parameters

strCategoryName

A String that contains the name of the category to be removed as a parent to this category.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_CATEGORY_DOESNT_EXIST | &H8898001C | The category you specified either did not exist or was not a parent of this category.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Use the RemoveParentCategory method to remove a parent category from this category. If the category named in the strCategoryName parameter does not exist, then this method will fail.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

myCategory.RemoveParentCategory "Apparel"

See Also

Category Object

Category.AddParentCategory

Category.RemoveChildCategory


Category.RemoveProduct

Use this method to remove a product from this category.

Definition

Sub RemoveProduct(
varProductID As Variant
)

Parameters

varProductID

A Variant that contains the product ID.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_PRODUCT_DOESNT_EXIST | &H8898001E | The product you specified did not exist.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

myCategory.RemoveProduct "Widget"

See Also

Category Object

Category.AddProduct


Category.RemoveRelationshipToCategory

Use this method to remove a relationship between the specified category and this category.

Definition

Sub RemoveRelationshipToCategory(
strRelatedCategoryName As String,
strRelationshipName As String
)

Parameters

strRelatedCategoryName

A String that contains the name of the related category.

strRelationshipName

A String that contains the name of the relationship.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_CATEGORY_DOESNT_EXIST | &H8898001C | The category you specified either did not exist or was not a parent of this category.
E_CAT_DEFN_NO_RELATIONSHIP_EXISTS | &H88980045 | The specified relationship did not exist.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The RemoveRelationshipToCategory method removes a relationship between this category and the category named in the strRelatedCategoryName parameter. Since more than one relationship may exist between these two categories, you must also specify the name of the relationship you wish to remove in the strRelationshipName parameter. If the category specified as the strRelatedCategoryName parameter does not exist or the relationship specified as the strRelationshipName parameter does not exist, then this method will fail.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

myCategory.RemoveRelationshipToCategory "Gadget", "Accessory"

See Also

Category Object

Category.AddRelationshipToCategory

Category.RemoveRelationshipToProduct


Category.RemoveRelationshipToProduct

Use this method to remove a relationship between the specified product and this category.

Definition

Sub RemoveRelationshipToProduct(
varRelatedProductID As Variant,
strRelationshipName As String
)

Parameters

varRelatedProductID

A Variant that contains the ID of the related product.

strRelationshipName

A String that contains the name of the relationship.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_DEFN_NO_RELATIONSHIP_EXISTS &H88980045
            The specified relationship did not exist.
    E_CAT_PRODUCT_DOESNT_EXIST | &H8898001E | The specified product did not exist.

    Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

    Remarks

    The RemoveRelationshipToProduct method removes a relationship between this category and the product identified by the varRelatedProductID parameter. Since more than one relationship may exist between this category and product, you must also specify the name of the relationship you wish to remove in the strRelationshipName parameter. If the product specified as the varRelatedProductID parameter does not exist or the relationship specified as the strRelationshipName parameter does not exist, then this method will fail.

    For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

    Example

    myCategory.RemoveRelationshipToProduct "Gadget", "FeaturedProduct"

    See Also

    Category Object

    Category.AddRelationshipToProduct


Category.SetCategoryProperties

Use this method to set values for the properties of this category.

Definition

Sub SetCategoryProperties(
pRSCategory As _Recordset,
Optional fForceUpdate As Variant
)

Parameters

pRSCategory

A Recordset object that contains the properties for this category.

fForceUpdate

A Variant that causes a forced update of the category properties.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_CATEGORY_CHANGED | &H88980028 | The properties of this category have changed since they were last read. This error is returned only if the fForceUpdate parameter is set to False.
E_CAT_CATEGORY_DOESNT_EXIST | &H8898001C | This category has been removed from the catalog.
E_CAT_INVALIDVALUE_FOR_PROPERTY &H88980038 This error is returned if:
  • One of the properties did not satisfy the Min/Max condition.

  • The properties of string or enumeration data type exceeded the maximum length.

  • The value of the enumeration property was not one of the legal values defined.
E_CAT_NULL_PRICE_NOT_ALLOWED | &H8898003F | The OriginalPrice field in the pRSCategory recordset was blank or NULL. This field is required if the category is used as a pricing category.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Use the SetCategoryProperties method to modify the properties of a category. The pRSCategory parameter specifies a Recordset object that describes the new property values for this category. Use the Recordset object returned by the GetCategoryProperties method so that its timestamp can be compared for error checking.

If the fForceUpdate parameter is set to False, and the property values in the pRSCategory parameter have changed, the method will fail.

This method will not update the built in fields in the catalog. If this category is being used as a pricing category, then this method will update the price of all the products using this category as the pricing category

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

myCategory.SetCategoryProperties pRSCategory, "TRUE"

See Also

Category Object


ContentList Object

Use this object to access a particular collection of content items. The ContentList object provides aggregated access to the private data that it stores and to the shared data stored in the ContentListFactory object that created it. This object also flows through the Content Selection Framework (CSF) pipeline for the purpose of scoring content items.

ProgID: | Dependent (See Remarks for more information)
COM Class Name: | ContentList
Type Library Name: | Microsoft Commerce 2000 Cache Manager Type Library
DLL Name: | mscscache.dll
Threading Model: | Both

The properties of the ContentList object are shown in the following table.

Property | Type | Description
ActiveRows | IRowCollection | The collection of rows that meet the current Threshold and RowLimit properties and that have not been filtered out of the ContentList object. This property is read-only.
AllRows | IRowCollection | The collection of all rows in the ContentList object. This property is read-only.
Count | Long | Stores the number of rows in the ContentList object. This property is read/write.
Factory | IContentListFactory | Stores a reference to the ContentListFactory object that created this ContentList object. This property is read-only.
Fields | Fields | The Fields collection for a particular row in the ContentList object. This property is read-only.
RowLimit | Long | Stores the maximum number of rows that can exist in the ActiveRows collection property. This property is read/write.
Sorted | Boolean | Stores a flag that controls whether or not the rows in the ActiveRows collection property are returned sorted by score. This property is read/write.
Threshold | Float | Stores the Threshold score that items must meet to be included in the ActiveRows collection property. This property is read/write.
TraceMessages | ISimpleList | Stores the list of TraceMessage strings accumulated for a particular row in the ContentList object. This property is read-only.
TraceMode | Boolean | Stores the TraceMode value. A value of True enables score tracing, a value of False disables it. This property is read/write.

The methods of the ContentList object are shown in the following table.

Method | Description
AdjustScore | Adjusts the score associated with an item in the ContentList object by applying a multiplier.
BuildIndex | Builds an index on all rows based on the specified column.
Filter | Filters items in a ContentList object based on the specified criteria.
GetData | This method is not usable from Microsoft Visual Basic or Microsoft Visual Basic Scripting Edition (VBScript).
GetScore | Gets the score of an item in a ContentList object.
Search | Returns a collection of content items that match the search criteria.
SetData | This method is not usable from Microsoft Visual Basic or Microsoft Visual Basic Scripting Edition (VBScript).
SetScore | Sets the score of an item in a ContentList object.

Remarks

Both the ContentList object and the ContentListFactory object implement a common interface, IDataContainer. Therefore, they share the following methods and properties, which are functionally identical on both objects:

Properties:

  • AllRows

  • Count

  • Fields

Methods:

  • BuildIndex

  • GetData

  • Search

  • SetData

The function of a ContentList object is:

  • To aggregate private data in the ContentList object with shared data in the ContentListFactory object.

  • To provide functionality for scoring, searching, and filtering the list of content.

The ContentList object is a dependent object. Create a new ContentList object by calling the method ContentListFactory.CreateNewContentList.

Important

  • The ContentList and the ContentListFactory objects are designed to be run in-process with their clients. The GetData and SetData methods assume direct memory access for performance reasons.


ContentList.ActiveRows

The ActiveRows property returns a RowCollection object. This property is read-only; however, the RowCollection object is read/write. Changes made to the data within the RowCollection object are also reflected in the ContentList object.

Definition

Property ActiveRows() As IRowCollection

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The ActiveRows RowCollection object allows access to the content items of the ContentList object whose score is greater than or equal to the current threshold score contained in the Threshold property. If the value of the Threshold property is set to a negative number, even items that have been filtered out by the Filter method might be included in the ActiveRows collection. This occurs because an item being filtered out has a score set to zero, which is still greater than a negative threshold value.

Regardless of the number of items with scores above the threshold, the number of items in the ActiveRows object is limited by the RowLimit property.

The order of the rows in the ActiveRows collection is undefined unless the Sorted property is set to True.

See Also

ContentList Object

RowCollection Object


ContentList.AdjustScore

Use this method to adjust the score of an item in the ContentList object by applying a multiplier.

Definition

Sub AdjustScore(
RowNum As Long,
Multiplier As Float,
Component As String,
Description As String
)

Parameters

RowNum

A Long that contains the position of the item in the ContentList object for which the score is to be adjusted. Positions are counted from zero (0), not from one (1).

Multiplier

A Float that contains the value by which the score will be multiplied.

Component

An optional String that contains an identifier for the pipeline component that is adjusting the score. By convention, this is the ProgID of the pipeline component.

Description

An optional String that contains a description to be appended to the score adjustment tracing string. This string should briefly describe the nature of the adjustment.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The Component and Description parameters are optional. They are ignored unless the TraceMode property is set to True.

This method assumes that the ContentList object has a column of type CLCOL_R4 with the CLCOL_SCORE_COLUMN flag set.

Example

myContentList.AdjustScore 1, 1.25

See Also

ContentList Object


ContentList.AllRows

The AllRows property returns a new RowCollection object that allows access to the items in the ContentList object and, through aggregation, the ContentListFactory object. The AllRows property is read-only; however, the RowCollection object is read/write. Changes made to the data in the RowCollection object are reflected in the ContentList object.

Definition

Property AllRows() As IRowCollection

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

This property is functionally identical to the one of the same name to be found in the ContentListFactory object.

See Also

ContentList Object

RowCollection Object


ContentList.BuildIndex

Use this method to build an index for a specific column in a ContentList object.

Definition

Sub BuildIndex(
vCol As Variant
)

Parameters

vCol

A Variant that identifies the column for which the index will be built. The column is identified by either a number representing a column position, starting at zero (0), or a string containing a column name.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

S_FALSE

An index already exists on the column.

Remarks

An index can be built on any read-only, non-private column that is of type string, integer, or array of strings or integers. (CLCOL_READONLY and not CLCOL_PRIVATE). Also, only columns of type CLCOL_I2, CLCOL_I4, CLCOL_STRING, and CLCOL_VARIANTARRAY can be indexed. The non-private restriction means that the column will actually reside in the corresponding ContentListFactory object.

If a search is conducted on a column for which no index yet exists, the index is automatically created. This means that, although you are never required to call the BuildIndex method, you may want to incur the cost of creating the index at a known time for performance sake.

This method is functionally identical to the one of the same name in the ContentListFactory object.

Example

myDataContainer.BuildIndex 10

See Also

ContentList Object


ContentList.Count

The Count property is a read/write number that gets or sets the number of items in a ContentList object.

Definition

Property Count() As Long

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Normally, the Count property is already fixed when a ContentList object is created by a ContentListFactory object. The property may only be set for ContentList objects that are created by a ContentListFactory object that has not yet had any content items stored in it. Also, the Count property cannot be set to a number smaller than the current setting.

This property is functionally identical to the one of the same name in the ContentListFactory object.

See Also

ContentList Object


ContentList.Factory

The Factory property is a read-only reference to the ContentListFactory object that created this ContentList object.

Definition

Property Factory As ContentListFactory

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

See Also

ContentList Object


ContentList.Fields

The Fields property creates a new Fields object that allows access to the fields for a specified content item. The Fields property is read-only; however, the Fields object is read/write in that changes made using this object are reflected in the ContentList object.

Definition

Property Fields(
RowNum As Long
) As Fields

Parameters

RowNum

A Long that contains the position of the item in the ContentList object for which a Fields object will be returned. Positions are counted from zero (0), not from one (1).

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The Fields object exposes the same interface as the ActiveX Data Objects (ADO) Fields object.

This property is functionally identical to the one of the same name in the ContentListFactory object.

See Also

ContentList Object


ContentList.Filter

Use this method to filter items in a ContentList object. Items that do not pass the filter have their scores set to zero (0).

Definition

Sub Filter(
vColumn As Variant,
vFilterCriteria As Variant,
FilterAction As FilterActionEnum,
Component As String
)

Parameters

vColumn

A Variant that identifies the column for which the index will be built. The column is identified by either a number representing a column position, starting at zero (0), or a string containing a column name.

vFilterCriteria

A Variant that contains the filter criterion. The criterion is either a single String, an array of Strings, or an Integer.

FilterAction

An enumeration value. Valid values are FILTER_REQUIRE and FILTER_EXCLUDE. See the Remarks section for more information about the consequences of these two actions.

Component

A String that is intended to contain the name of the pipeline component doing the filtering. This parameter is optional and is used for score tracing. Trace messages will be generated for content items that are filtered out.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

An item in the ContentList object matches the criteria if the value for the specified column exactly matches a string or number passed in the vFilterCriteria parameter. If the vFilterCriteria parameter is an array of strings, matching any one of the strings in the array is considered a match. If the FilterAction parameter is set to FILTER_REQUIRE, non-matching items have their scores set to zero (0). If the FilterAction parameter is set to FILTER_EXCLUDE, matching items have their scores set to zero (0).

For the sake of uniformity, the pipeline components provided with Commerce Server 2000 pass their own Programmatic Identifier (ProgID) for the Component parameter.

Example

myContentList.Filter "Score", 3, FILTER_EXCLUDE

See Also

ContentList Object


ContentList.GetData

Due to performance considerations and compatibility issues, this method cannot be used from Microsoft Visual Basic or Microsoft Visual Basic Scripting Edition (VBScript).

See Also

ContentList Object


ContentList.GetScore

Use this method to retrieve the score of an item in a ContentList object.

Definition

Function GetScore(
RowNum As Long
) As Float

Parameters

RowNum

A Long that contains the position of the item in the ContentList object for which the score will be returned. Positions are counted from zero (0), not from one (1).

Return Values

If this method completes successfully, it returns a Float that contains the score for the specified item.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Example

'sngScore is a float
sngScore = myContentList.GetScore(12)

See Also

ContentList Object


ContentList.RowLimit

The RowLimit property is a read/write number that specifies the maximum number of rows that the object should select for the ActiveRows property.

Definition

Property RowLimit() As Long

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

See Also

ContentList Object

ContentList.ActiveRows


ContentList.Search

Use this method to create a RowCollection object that allows access to each item in the ContentList object that matches the specified criterion.

Definition

Function Search(
vCol As Variant,
vSearchCriteria As Variant
) As IRowCollection

Parameters

vCol

A VARIANT that identifies the column to search. The column is identified by either a number representing a column position, starting at zero (0), or a string containing a column name.

vSearchCriteria

A Variant that contains the filter criterion. The criterion is usually a String, an array of Strings, or an Integer. An attempt will be made to coerce other types to the type of the column being searched.

Return Values

If this method completes successfully, it returns a reference to a new RowCollection object that contains one row for each matching item.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

The following standard COM error value has a particular meaning in the context of this method.

S_FALSE

No rows in the ContentList object matched the filter criteria. As a result, the returned RowCollection is empty.

Remarks

Columns must be shared (not private) and read-only in order to be indexed and searched. Columns must also be of type string, integer (long or short), or variant array to be searchable. The search criteria may be any variant type that can be coerced to the type of the column being searched.

When the search criteria is an array of variants, the set of rows returned contains all rows that match any of the search criteria array elements. It is a union of the matches.

This property is functionally identical to the one of the same name in the ContentListFactory object.

Example

'myCol is a RowCollection object
Set myCol = myContentList.Search(10, "CarAds")

See Also

ContentList Object


ContentList.SetData

Due to performance considerations, this method cannot be used from Microsoft Visual Basic or Microsoft Visual Basic Scripting Edition (VBScript).

See Also

ContentList Object


ContentList.SetScore

Use this method to set a new score for an item in a ContentList object.

Definition

Sub SetScore(
RowNum As Long,
Score As Float,
Component As String,
Description As String
)

Parameters

RowNum

A Long that contains the position of the item in the ContentList object for which a new score will be set. Positions are counted from zero (0), not from one (1).

Score

A Float that contains the new score.

Component

A String that is intended to contain the name of the pipeline component that is setting the new score. This parameter is optional and is used for score tracing.

Description

A String that is intended to contain the reason that the score is being set; for example, Need of Delivery. This parameter is optional and is used for score tracing.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The Component and Description parameters are optional.

This method assumes that the ContentList object has a column of type CLCOL_R4 with the CLCOL_SCORE_COLUMN flag set.

For the sake of uniformity, pipeline components provided with Commerce Server 2000 pass the Programmatic Identifier (ProgID) of the component for the Component parameter.

Example

'strProgID is a string
myContentList.SetScore(123456, 0.5, strProgID, "")

See Also

ContentList Object


ContentList.Sorted

The Sorted property is a read/write Boolean that determines whether or not the next enumeration of the ContentList object ActiveRows property will be returned in sorted order by score (highest to lowest).

Definition

Property Sorted() As Boolean

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

A value of True indicates that the next enumeration of the ContentList object ActiveRows property should be returned in sorted order by score (highest to lowest). A value of FALSE indicates that it will not be sorted. The items do not actually change positions in the list — that is, the ordinal identifying an item never changes. Setting the value to True only effects the next enumeration of the ActiveRows property, subsequent enumerations will be unsorted unless the property is set to True again.

See Also

ContentList Object


ContentList.Threshold

The Threshold property is a read/write floating point number. This number contains a threshold score that items must meet or exceed to be included in the ActiveRows collection property.

Definition

Property Threshold() As float

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

See Also

ContentList Object


ContentList.TraceMessages

The TraceMessages property is a SimpleList object that contains the list of trace strings that have accumulated for the given item in a ContentList object. The TraceMessages property is read-only; however, the returned SimpleList object is read/write.

Definition

Property TraceMessages(
RowNum As Long
) As ISimpleList

Parameters

RowNum

A Long that contains the position of the row for which the trace messages will be returned. Row positions start at zero (0), not one (1).

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The TraceMode property acts as a global switch to control whether any score tracing is performed. If it is set to True, score tracing is performed. If it is set to False, score tracing is suppressed.

When you use score tracing, you will notice a dramatic negative effect on performance; score tracing should not be used under normal circumstances. However, it can be useful when you are attempting to troubleshoot a scoring-related issue.

The list will be empty if the TraceMode property is set to False or if no score modifications have been made to the item.

Each item in the list is a string in the following format:

<component>,<operator><number>,<description>

Where the fields of the string are defined as follows:

component

The identifier of the component that made the score change, as passed to the AdjustScore, SetScore, and Filter methods.

operator

= if the score set to an absolute value by the SetScore or Filter methods, or * if a multiplier was applied to the score by the AdjustScore method.

number

The score returned by the SetScore method after any adjustments by the Filter or AdjustScore methods.

description

The reason for the score change, as passed to the AdjustScore or SetScore methods, and set by the Filter method.

An example score tracing string is:

"Commerce.AdNod,=0.9875,Need of Delivery".

See Also

ContentList Object

ContentList.TraceMode


ContentList.TraceMode

The TraceMode property is a read/write Boolean that controls whether score tracing is enabled or suppressed.

Definition

Property TraceMode() As Boolean

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

This property acts as a global switch to control whether or not score tracing is performed. If it is set to True, a SimpleList object of trace messages will be constructed that can be accessed through the TraceMessages property. If it is set to False, score tracing is suppressed.

When you use score tracing, you will notice a dramatic negative effect on performance; score tracing should not be used under normal circumstances. However, it can be useful when you are attempting to troubleshoot a scoring-related issue.

See Also

ContentList Object


ContentListFactory Object

Use this object to efficiently maintain lists of content items that compete with each other to be selected for display on a Web page by a Content Selection pipeline (CSP).

ProgID: | Commerce.ContentListFactory (Externally creatable)
COM Class Name: | ContentListFactory
Type Library Name: | Microsoft Commerce 2000 Cache Manager Type Library
DLL Name: | mscscache.dll
Threading Model: | Both

The properties of the ContentListFactory object are shown in the following table.

Property | Type | Description
AllRows | IRowCollection | The collection of all rows in the ContentListFactory object. This property is read-only.
Count | long | Stores the number of rows in the ContentListFactory object. This property is read/write.
Fields | Fields | The Fields collection for a particular row in the ContentListFactory object. This property is read-only.
Schema | IContentListSchema | Stores a reference to the ContentListSchema object used by this ContentListFactory object. This property is read/write.

The methods of the ContentListFactory object are shown in the following table.

Method | Description
BuildIndex | Builds an index on the specified column.
ConstructFromRecordset | Initializes a ContentListFactory object, and creates and initializes a new ContentListSchema object, from an ADO Recordset object. The ContentListFactory object is populated with the data from the Recordset object.
CreateNewContentList | Creates a new ContentList object based on the schema in use by this ContentListFactory object. The new ContentList object has access to the shared data in the ContentListFactory object that created it.
GetData | This method is not usable from Visual Basic or VBScript.
Search | Returns a RowCollection object containing the collection of content items that match the search criteria.
SetData | This method is not usable from Visual Basic or VBScript.

Remarks

Important

  • The ContentList and the ContentListFactory objects are designed to be run in-process with their clients. The GetData and SetData methods assume direct memory access for performance reasons.

Both the ContentList object and the ContentListFactory object implement a common interface, IDataContainer. Therefore they share the following methods and properties, which are functionally identical on both objects:

Properties:

  • AllRows

  • Count

  • Fields

Methods:

  • BuildIndex

  • GetData

  • Search

  • SetData


ContentListFactory.AllRows

The AllRows property returns a new RowCollection object that allows access to the items in the ContentListFactory object. The AllRows property is read-only; however, the RowCollection object is read/write in that changes made using this object are reflected in the ContentListFactory object.

Definition

Property AllRows() As IRowCollection

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

This property is functionally identical to the one of the same name in the ContentList object.

See Also

ContentListFactory Object

RowCollection Object


ContentListFactory.BuildIndex

Use this method to build an index for a specific column in a ContentListFactory object.

Definition

Sub BuildIndex(
vCol As Variant
)

Parameters

vCol

A Variant that identifies the column for which the index will be built. The column is identified by either a number representing a column position, starting at zero (0), or a string containing a column name.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

S_FALSE

An index already exists on the column.

Remarks

An index can be built on any read-only, non-private column that is of type string, integer, or array of strings or integers. (CLCOL_READONLY and not CLCOL_PRIVATE). Also, only columns of type CLCOL_I2, CLCOL_I4, CLCOL_STRING, and CLCOL_VARIANTARRAY can be indexed.

If a search is conducted on a column for which no index yet exists, the index is automatically created. This means that, though you are never required to call the BuildIndex method, you may want to incur the cost of creating the index at a known time for performance sake.

This method is functionally identical to the one of the same name to be found in the ContentList object.

Example

call myContentListFactory.BuildIndex("AdType")

See Also

ContentListFactory Object


ContentListFactory.ConstructFromRecordset

Use this method to initialize a new ContentListFactory object, and create and initialize a new ContentListSchema object, from an ADO Recordset object.

Definition

Sub ConstructFromRecordset(
Recordset As _Recordset,
Skip As Variant,
Add As ContentListSchema
)

Parameters

Recordset

A reference to an ADO Recordset object from which the ContentList object will be constructed.

Skip

An optional Variant that is a SimpleList object. The SimpleList object contains the names of field(s) that exist in the Recordset object but that should not have a column in the new ContentList object.

Add

An optional reference to a ContentListSchema object that contains information about additional columns or new flags for existing columns that should be accounted for when the new ContentList object is created. Refer to the Remarks section for additional information.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The Skip and Add parameters are both optional.

Columns defined in the ContentListSchema object that do not exist in the Recordset object are added to the new schema for the ContentListFactory object. Schema columns defined in both the ContentListSchema object and in the Recordset object get their flag settings from the former object, overriding the default flag settings otherwise applied. Supplemental columns may be either shared or private. Data for any supplemental, shared columns should be initialized using the SetData method. Data for any supplemental, private columns cannot be provided until a corresponding ContentList object is created.

The default value for dwFlags for columns created from the fields of the Recordset object is CLCOL_READONLY.

The ContentListFactory object attempts to access the RecordCount property of the RecordSet to determine how many rows of data for which space should be allocated. Not all types of RecordSets support this. If the RecordCount property cannot be determined, the ContentListFactory object will grow the factory in chunks of 100 rows. For this reason, it is most efficient to pass a RecordSet for which the RecordCount property is defined.

Column types are mapped from the Recordset object according to the following table.

ADO Type | ContentList Type
adSmallInt, adUnsignedSmallInt | CLCOL_I2
adInteger, adUnsignedInt, adError | CLCOL_I4
adSingle | CLCOL_I4
adDouble | CLCOL_R8
adDBDate, adDBTime, adDBTimeStamp | CLCOL_DATE
adChar, adVarChar, adLongVarChar, adWChar, adVarWChar, adLongVarWChar | CLCOL_STRING
adChapter*, adDispatch | CLCOL_DISPATCH
adChapter | CLCOL_UNKNOWN
adBoolean | CLCOL_BOOL

Note

  • *One level hierarchical Recordset objects are supported. The child Recordset objects are created in the ContentList object as a SimpleList of Dictionary objects.

Example

'rsSource is an existing recordset.
'vSkip is a simple list of fields to ignore.
'vSchema is a ContentListSchema object.
myContentListFactory.ConstructFromRecordset rsSource, vSkip, vSchema

See Also

ContentListFactory Object


ContentListFactory.Count

The Count property is a read/write number that gets or sets the number of content items in a ContentListFactory object.

Definition

Property Count() As Long

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The Count property cannot be changed once ContentList objects have been created by the ContentListFactory object. Also, the Count property cannot be set to a smaller number than its current setting.

This property is functionally identical to the one of the same name to be found in the ContentList object.

See Also

ContentListFactory Object


ContentListFactory.CreateNewContentList

Use this method to create a new ContentList object based on the schema established for this ContentListFactory object. The new ContentList object provides a unified interface to the private data that it stores and to the shared data stored in the ContentListFactory object (that created it).

Definition

Function CreateNewContentList() As ContentList

Parameters

None.

Return Values

If this method completes successfully, it returns a reference to the new ContentList object.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The new ContentList object will be based on the established schema for this ContentListFactory object. Storage for columns marked as CLCOL_PRIVATE in the schema is allocated in the ContentList object. The ContentList object maintains a pointer back to the factory that created it, which is where the storage for "shared" columns is maintained.

A ContentList object cannot exist independently of a ContentListFactory object.

The only prerequisite for calling this method is that a schema has been established. This can be accomplished by setting the Schema property or by calling the ConstructFromRecordset method.

Example

set oMyContentList = myContentListFactory.CreateNewContentList()

See Also

ContentListFactory Object


ContentListFactory.Fields

The Fields property creates a new Fields object that allows access to the fields for a specified content item. The Fields property is read-only; however, the Fields object is read/write in that changes made using this object are reflected in the ContentListFactory object.

Definition

Property Fields(
RowNum As Long
) As Fields

Parameters

RowNum

A Long that contains the position of the item in the ContentListFactory object for which a Fields object will be returned. Positions are counted from 0, not from 1.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The Fields object exposes the same interface as the ADO Fields object.

This property is functionally identical to the one of the same name to be found in the ContentList object.

See Also

ContentListFactory Object


ContentListFactory.GetData

Due to performance considerations, this method is not intended for use from Visual Basic or VBScript.

See Also

ContentListFactory Object


ContentListFactory.Schema

The Schema property is a ContentListSchema object that contains the schema used by this ContentListFactory object. The Schema property is read/write.

Definition

Property Schema() As ContentListSchema

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

This property is intended to only be set once. However, until any ContentList object is created using the CreateNewContentList method, or until rows are allocated in the ContentListFactory object by setting the Count property, it can be changed.

If this property is read before it is written, an empty ContentListSchema object will be created and returned.

See Also

ContentListFactory Object


ContentListFactory.Search

Use this method to create a RowCollection object that allows access to each item in the ContentListFactory object that matches the specified criterion.

Definition

Function Search(
vCol As Variant,
vSearchCriteria As Variant
) As IRowCollection

Parameters

vCol

A Variant that identifies the column to search. The column is identified by either a number representing a column position, starting at zero (0), or a string containing a column name.

vSearchCriteria

A Variant that contains the filter criterion. The criterion is usually a String, an array of Strings, or an Integer. An attempt will be made to coerce other types to the type of the column being searched.

Return Values

If this method completes successfully, it returns a reference to a new RowCollection object that contains one row for each matching item.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

S_FALSE

No rows in the ContentListFactory object matched the filter criteria. As a result, the returned RowCollection is empty.

Remarks

Columns must be shared (not private) and read-only in order to be indexed and searched. Columns must also be of type string, integer (long or short), or variant array to be searchable. The search criteria may be any variant type that can be coerced to the type of the column being searched.

When the search criteria is an array of variants, the set of rows returned contains all rows that match any of the search criteria array elements. It is a union of the matches.

This method is functionally identical to the one of the same name to be found in the ContentList object.

Example

set oMyRowCollection = myDataContainer.Search("AdType", "CarAds")

See Also

ContentListFactory Object


ContentListFactory.SetData

Due to performance considerations, this method is not intended for use from Visual Basic or VBScript.

See Also

ContentListFactory Object


ContentListSchema Object

Use this object to manipulate the schema for a ContentListFactory object.

ProgID: | Commerce.ContentListSchema (Externally creatable)
COM Class Name: | ContentListSchema
Type Library Name: | Microsoft Commerce 2000 Cache Manager Type Library
DLL Name: | mscscache.dll
Threading Model: | Both

The properties of the ContentListSchema object are shown in the following table.

Property | Type | Description
ColumnFlags | Long | Stores the column flags, represented as a bit field. This property is read/write.
ColumnName | String | Stores the column name. This property is read/write.
ColumnType | ColumnTypeEnum | Stores the data type of the column. This property is read/write.
Count | Long | Stores the number of columns defined by the schema. This property is read-only.
Locked | Boolean | Indicates whether this schema can be modified. This property is read/write. It is initially set to False. Once set to True, it can never be set back to False.

The methods of the ContentListSchema object are shown in the following table.

Method | Description
Add | Adds a new column to the schema.
FindColumn | Returns the position of a named column. Column positions are counted starting from zero (0), not one (1). This position index may be used as the Column index parameter for the GetData, SetData, Filter, and Search methods of the ContentList object.
GetSchema | Returns the entire schema in a high-performance, non-scriptable manner.
SetSchema | Sets the entire schema in a high-performance, non-scriptable manner.


ContentListSchema.Add

Use this method to add a new column to a schema for use by a ContentListFactory object and its associated ContentList objects.

Definition

Function Add(
sName As String,
Type As ColumnTypeEnum,
Flags As Long
) As Long

Parameters

sName

A String that contains a name for the new column.

Type

A value from the ColumnTypeEnum enumeration. See the Remarks section for more details.

Flags

A Long that contains the bit mask column flag settings for the new column.

Return Values

If this method completes successfully, it returns a Long that contains the position of the new column. Column positions are numbered starting with zero (0), not one (1).

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Once the Locked property has been set to True, subsequent calls to this method will fail. The ContentListFactory object will set the Locked property of its ContentListSchema object to True when one of the following conditions is met:

  • Rows of data are allocated in the factory by setting the Count property or calling the ConstructFromRecordset method.

  • The ContentListFactory object has been used to construct one or more ContentList objects using the CreateNewContentList method.

The following table shows the values of the ColumnTypeEnum enumeration, their associated names, and describes their use.

Name | Value | Description
CLCOL_I2 | 2 | A 16-bit integer. This value corresponds to the VARTYPE value VT_I2.
CLCOL_I4 | 3 | A 32-bit integer. This value corresponds to the VARTYPE value VT_I4.
CLCOL_R4 | 4 | A single precision floating point number. This value corresponds to the VARTYPE value VT_R4.
CLCOL_R8 | 5 | A double precision floating point number. This value corresponds to the VARTYPE value VT_R8.
CLCOL_CY | 6 | A 64-bit integer used to store a currency value. This value corresponds to the VARTYPE value VT_CY. Monetary values stored using this type are scaled by 10,000 (4 decimal places). For example, the value 86900 would correspond to a currency value of $8.69 in the US. This is also the same as the money datatype used by SQL7.
CLCOL_DATE | 7 | A double precision floating point number used to store a date/time value. This value corresponds to the VARTYPE value VT_DATE.
CLCOL_DISPATCH | 9 | A reference to an object that supports scripting/automation (inherits from IDispatch). This value corresponds to the VARTYPE value VT_DISPATCH.
CLCOL_BOOL | 11 | A boolean value. This value corresponds to the VARTYPE value VT_BOOL. Do not confuse this with the C++ type BOOL, which is 4 bytes.
CLCOL_UNKNOWN | 13 | A pointer to an IUnknown-based interface that, presumably, does not support scripting/automation (inherits from IUnknown). This value corresponds to the VARTYPE value VT_UNKNOWN.
CLCOL_STRING | 14 | A pointer to a string in the private heap maintained by every ContentListFactory object. There is no corresponding VARTYPE value.
CLCOL_VARIANTARRAY | 15 | A pointer to a SAFEARRAY. The corresponding variant type is VT_ARRAY or VT_VARIANT.

Note

  • With the exception of CLCOL_STRING and CLCOL_VARIANTARRAY, these types are identical to the corresponding VARTYPE and share the same constant value. They may be used as a VARTYPE.

Example

'"Color" is the column name.
'CLCOL_STRING indicates the column is of type String.
'0 indicates that no flags are applied.

dim iColumnNum as Long
iColumnNum = myContentListSchema.Add("Color", CLCOL_STRING, 0)

See Also

ContentListSchema Object


ContentListSchema.ColumnFlags

The ColumnFlags property is a read/write long that contains the column flags.

Definition

Property ColumnFlags(
vColumn As Variant
) As Long

Parameters

vColumn

A Variant that contains either the column name or the column position in order to identify the column in question. Column positions are counted from zero (0), not one (1).

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Column flags are represented as a bit field. The following table shows the meanings of the bits that are used and the constants provided for manipulating those bits.

Bit | Constant | Description
1 | CLCOL_READONLY (= 0x01) | When the bit is set, data in the column is read-only, and cannot be updated. This will be common for data stored in the ContentListFactory object since that data is shared between multiple page requests. When the bit is cleared, data in the column is read/write, and can be freely updated. No record locking is performed, so update contention could occur when updating data in the ContentListFactory object. This is not a concern for columns that are marked Private since they exist in the individual instances of ContentList objects, and ContentList objects are typically created for and used by a single thread.
2 | CLCOL_PRIVATE (= 0x02) | When the bit is set, the data in the column is private to each ContentList object based on this schema. This means that the data is stored separately in each ContentList object that is created, and not stored in the shared columns in the corresponding ContentListFactory object.
4 | CLCOL_SCORE_COLUMN (= 0x04) | When the bit is set it indicates that the data in this column is the score value associated with the content item. The type of this column must be a single-precision floating-point type (CLCOL_R4); only one column in the schema can have this flag set. Further, since a unique score value must be associated with each individual page request, this bit can only be set in conjunction with the CLCOL_PRIVATE bit. In other words, it must be a column stored in the ContentList object, as opposed to the ContentListFactory object, that is marked as the score column.

See Also

ContentListSchema Object


ContentListSchema.ColumnName

The ColumnName property is a read/write string that contains the name of the column.

Definition

Property ColumnName(
vColumn As Variant
) As String

Parameters

vColumn

A Variant that contains either the column name or the column position in order to identify the column in question. Column positions are counted from zero (0), not one (1).

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Though using a column name as the value of the vColumn parameter in order to retrieve that same column name may be fruitless, passing a column name does make sense when changing the column name.

See Also

ContentListSchema Object


ContentListSchema.ColumnType

The ColumnType property is a read/write value from the ColumnTypeEnum enumeration, specifying the data type of the specified column.

Definition

Property ColumnType(
vColumn As Variant
) As ColumnTypeEnum

Parameters

vColumn

A Variant that contains either the column name or the column position in order to identify the column in question. Column positions are counted from zero (0), not one (1).

[out,retval] When getting the property, a pointer used to return a value from the ColumnTypeEnum enumeration. See the Remarks section for more details.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The following table shows the values of the ColumnTypeEnum enumeration, their associated names, and describes their use.

Name | Value | Description
CLCOL_I2 | 2 | A 16-bit integer. This value corresponds to the VARTYPE value VT_I2.
CLCOL_I4 | 3 | A 32-bit integer. This value corresponds to the VARTYPE value VT_I4.
CLCOL_R4 | 4 | A single precision floating point number. This value corresponds to the VARTYPE value VT_R4.
CLCOL_R8 | 5 | A double precision floating point number. This value corresponds to the VARTYPE value VT_R8.
CLCOL_CY | 6 | A 64-bit integer used to store a currency value. This value corresponds to the VARTYPE value VT_CY. Monetary values stored using this type are scaled by 10,000 (4 decimal places). For example, the value 86900 would correspond to a currency value of $8.69 in the US. This is also the same as the money datatype used by SQL7.
CLCOL_DATE | 7 | A double precision floating point number used to store a date/time value. This value corresponds to the VARTYPE value VT_DATE.
CLCOL_DISPATCH | 9 | A reference to an object that supports scripting/automation (inherits from IDispatch). This value corresponds to the VARTYPE value VT_DISPATCH.
CLCOL_BOOL | 11 | A boolean. This value corresponds to the VARTYPE value VT_BOOL. Do not confuse this with the C++ type BOOL, which is 4 bytes.
CLCOL_UNKNOWN | 13 | A pointer to an IUnknown-based interface that, presumably, does not support scripting/automation (inherits from IUnknown). This value corresponds to the VARTYPE value VT_UNKNOWN.
CLCOL_STRING | 14 | A pointer to a string in the private heap maintained by every ContentListFactory object. There is no corresponding VARTYPE value.
CLCOL_VARIANTARRAY | 15 | A pointer to a SAFEARRAY. The corresponding variant type is VT_ARRAY or VT_VARIANT.

Note

  • With the exception of CLCOL_STRING and CLCOL_VARIANTARRAY, these types are identical to the corresponding VARTYPE and share the same constant value. Indeed, they may be used as a VARTYPE.

See Also

ContentListSchema Object


ContentListSchema.Count

The Count property is a read-only value that contains the current number of columns in the schema.

Definition

Property Count() As Long

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

See Also

ContentListSchema Object


ContentListSchema.FindColumn

Use this method to find the position of a column specified by name.

Definition

Function FindColumn(
sName As String
) As Long

Parameters

sName

A String that contains the name of the column for which the position will be returned.

Return Values

If this method completes successfully, it returns a Long that contains the position of the new column.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Column positions are counted from zero (0), not one (1).

Example

'"Color" is the column name.
Dim iColumnNum as Long

iColumnNum = myContentListSchema.FindColumn("Color")

See Also

ContentListSchema Object


ContentListSchema.GetSchema

In the interest of high performance, this method is not intended for use from Microsoft Visual Basic or Microsoft Visual Basic Scripting Edition (VBScript).

See Also

ContentListSchema Object


ContentListSchema.Locked

The Locked property is a read/write Boolean that indicates whether the ContentListSchema object can be modified. A value of True indicates that the schema is locked and cannot be modified. A value of False indicates that the schema is not locked and can be modified. Once the object is in use it can no longer be modified.

Definition

Property Locked() As Boolean

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

A ContentListSchema object becomes permanently locked as soon as this property is set to True. Once locked, the contained schema cannot be modified or unlocked. ContentListFactory objects will lock the schema as soon as any rows are allocated or any ContentList objects are created, whichever occurs first.

See Also

ContentListSchema Object


ContentListSchema.SetSchema

In the interest of high performance, this method is not intended for use from Microsoft Visual Basic or Microsoft Visual Basic Scripting Edition (VBScript).

See Also

ContentListSchema Object


ContentSelector Object

Use this object to select one or more items of content for display on a Web page. The content may come from customer campaigns (ads, discounts), or from custom applications built on the Content Selection Framework (CSF).

If you want to select custom content for display on your Web pages, you can use the CSF by instantiating and using ContentSelector objects. ContentSelector objects invoke different CSF pipelines to select different types of content based on the dictionary passed to the GetContent method.

ProgID: | Commerce.ContentSelector (Externally creatable)
COM Class Name: | CContentSelector
Type Library Name: | Microsoft Commerce 2000 CSF Pipeline Component 1.0 Type Library
DLL Name: | CSFComp.dll
Threading Model: | Both

The ContentSelector object implements all of the methods and properties of the Dictionary object, only the method not inherited from the Dictionary object is shown in the following table.

Method | Description
GetContent | Executes a Content Selection pipeline. The pipeline selects one or more content items. The selected content items are stored in a SimpleList object, formatted as strings of HTML or XML.

Remarks

The Context dictionary maintains a reference to a ContentSelector object in its ContextProfile entry. This ContentSelector object is used to pass arbitrary properties to the pipeline components. Arbitrary properties can be associated with the ContentSelector object because it inherits from the Dictionary object.

See Also

Content Selection Objects


ContentSelector.GetContent

Use this method to execute a Content Selection pipeline and return the resulting content in a SimpleList object.

Definition

Function GetContent(
dictCSFContext As IDictionary,
) As ISimpleList

Parameters

dictCSFContext

A global context dictionary with a configuration for an instance of a CSF application. The dictionary contains global objects and configurations used by the ContentSelector object. At a minimum, the dictionary must contain the Pipeline key so that the ContentSelector object knows which pipeline to execute.

Return Values

If this method completes successfully, it returns a reference to a SimpleList object that contains the selected content. The elements of the SimpleList object are HTML or XML strings.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Note

  • This method can also return an error returned by the invoked pipeline.

Remarks

The ContentSelector object reads the Pipeline key of the passed in dictionary object to find the pipeline object to invoke. It copies the values of the dictionary passed to it into a new dictionary. The new dictionary is passed to the pipeline as the pipe Context dictionary. An empty dictionary is created and passed as the Order dictionary for the pipeline. The ContentSelector object adds a reference to itself under the ContextProfile key in the pipe Context dictionary.

When pipeline execution has completed, the ContentSelector object looks for the key _formatted in the Order dictionary, and returns the list assigned to that key as the return value. If the list assigned to the _formatted key does not exist, an empty list is created and returned. The self-reference in the pipe Context dictionary is removed to prevent a circular reference. References to the Order and Context dictionaries are added to the ContentSelector object before it returns, giving the page access to the values written into those dictionaries by the pipeline.

Example

For example code, see the sample in ContentSelector Object.

See Also

CacheManager Object

Content Selection Pipelines

ContentSelector Object


DataFunctions Object

Use this object to perform locale-based formatting, parsing, and value range checking in a site. This object also has a variety of utilities useful for site development.

ProgID: | Commerce.DataFunctions (Externally creatable)
COM Class Name: | DataFunctions_4_0
Type Library Name: | Commerce -- MSCSAspHelp Type Library
DLL Name: | MSCSAspHelp.dll
Threading Model: | Both

The properties of the DataFunctions object are shown in the following table.

Property | Type | Description
Locale | Long | Stores a number that represents the default locale to be used to format date, time, money, and number values. This property is read/write.
CurrencySymbol | Variant | Stores the currency symbol to use if no currency symbol is specified in the ConvertStringToCurrency and LocalizeCurrency methods. The default value is the system default currency symbol. This property is read/write.

The methods of the DataFunctions object are shown in the following table.

Method | Description
CleanString | Processes the specified string. This processing can include stripping out white spaces, modifying the case of the string, and validating that the length of the string falls within a specified range.
ConvertDateString | Converts the specified string representation of the date to a date Variant, based on the default or specified locale.
ConvertDateTimeString | Converts the specified string representation of the date and time to a date Variant, based on the default or specified locale.
ConvertFloatString | Converts the specified string representation of a floating-point number to a double Variant, based on the default or specified locale.
ConvertMoneyStringToNumber | Converts the specified string representation of a currency value to a long Variant, based on the default or specified locale.
ConvertNumberString | Converts the specified string representation of a number to an integer Variant, based on the default or specified locale.
ConvertTimeString | Converts the specified string representation of a time value to a date Variant, based on the default or specified locale.
Date | Returns a string representation of a date stored in a date Variant, based on the default or specified locale.
DateTime | Returns a string representation of a date and time stored in a date Variant, based on the default or specified locale.
Float | Returns a string representation of a floating-point number, based on the default or specified locale.
GetLocaleInfo | Retrieves information about the specified locale.
GetLocaleList | Retrieves a list of installed locales.
Money | Returns a formatted currency string, based on the default or specified locale.
Number | Returns a string representation of a number, based on the default or specified locale.
Time | Returns a string representation of a time stored in a date Variant, based on the default or specified locale.
ValidateDateTime | Checks whether the specified string contains a valid date and/or time, and optionally checks against a specified range.
ValidateFloat | Checks whether the specified string contains a valid floating-point number, and optionally checks the value of the number against a specified range.
ValidateNumber | Checks whether the specified string contains a valid number, and optionally checks the value of the number against a specified range.
CloneObject | Clones a SimpleList or Dictionary object.
ConvertStringToCurrency | Converts the specified string representation of currency value into a currency Variant.
LocalizeCurrency | Creates a string representation of a currency value formatted to a specified locale and currency symbol.


DataFunctions.CleanString

Use this method to process a string, based on the default or specified locale. The string processing can include stripping out leading and trailing white spaces, modifying string case, and validating that the length of the string falls within a given range.

Definition

Function CleanString(
vtInput As Variant,
vtMinLen As Variant,
vtMaxLen As Variant,
vtStripWhite As Variant,
vtStripReturn As Variant,
vtCase As Variant,
vtLocale As Variant
) As Variant

Parameters

vtInput

A Variant that contains the text of the string to process.

vtMinLen

A Variant that contains the minimum length against which the length of the input string will be validated. The default value for this parameter is zero (0).

vtMaxLen

A Variant that contains the maximum length against which the length of the input string will be validated. The default value for this parameter is no limit.

vtStripWhite

A Variant that contains the Boolean value that indicates whether leading and trailing white spaces should be stripped from the input string. The default value is True.

vtStripReturn

A Variant that contains the Boolean value that indicates whether the carriage returns contained anywhere in the input string should be stripped. The default value is True.

vtCase

A Variant that specifies any conversions to the case of the input string. The default value for this parameter is zero (0), which results in no modification to the case of the input string. If this parameter is set to one (1), the input string is converted to uppercase. If this parameter is set to two (2), the input string is converted to lowercase.

vtLocale

A Variant that specifies the locale to use when processing the input string. If this parameter is not specified, the value of the Locale property of the DataFunctions object is used.

Return Values

If this method completes successfully, it returns a string Variant that contains the processed string; otherwise, NULL is returned.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

<HTML>
<HEAD>
</HEAD>
<BODY>
<%
Set MSCSDataFunctions = Server.CreateObject("Commerce.DataFunctions")
myLocale = "1033"
MSCSDataFunctions.Locale = myLocale
Dim Result
Dim strData
strData = " Microsoft Press   "
Result = MSCSDataFunctions.CleanString(strData, 1, 20, True, True, 1)
Response.Write Result
' "MICROSOFT PRESS" will be written to the page
%>
</BODY>
</HTML>

See Also

DataFunctions Object

DataFunctions.Locale

Page.RequestString


DataFunctions.CloneObject

Use this method to clone a SimpleList or Dictionary object. This method performs a deep copy of the cloned object, so new memory is allocated for the clone.

Definition

Function CloneObject(
pdispSource As Object
) As Object

Parameters

pdispSource

A reference to the SimpleList or Dictionary object to be cloned.

Return Values

If this method completes successfully, it returns a reference to the SimpleList or Dictionary object clone.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' dSource and dCopy are Dictionary objects
Set MSCSDataFunctions = Server.CreateObject("Commerce.DataFunctions")

dCopy = MSCSDataFunctions.CloneObject(dSource)

See Also

DataFunctions Object

DataFunctions.Locale


DataFunctions.ConvertDateString

Use this method to convert a date string to a date Variant, based on the default or specified locale.

Definition

Function ConvertDateString(
vtDate As Variant,
vtLocale As Variant
) As Variant

Parameters

vtDate

A Variant that contains a string representation of the date to convert.

vtLocale

A Variant that specifies the locale to use when processing the string. If this parameter is not specified, the value of the Locale property of the DataFunctions object is used.

Return Values

If this method completes successfully, it returns a date Variant containing the converted value; otherwise, NULL is returned.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

In some cases, the DataFunctions.ConvertDateString method returns NULL when converting a string representation of the date to the date Variant type for Latvian and Bulgarian locales. To avoid this problem, remove the constant string added at the end of the Date Representation String according to the Regional Settings in the Control Panel.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

<HTML>
<HEAD>
</HEAD>
<BODY>
<%
' Converts date using US and France locales
Dim Result
Set MSCSDataFunctions = Server.CreateObject("Commerce.DataFunctions")
myLocale = "1036"
MSCSDataFunctions.Locale = myLocale
Result = MSCSDataFunctions.ConvertDateString("12/1/2000", myLocale)
Response.Write "France: " & Result & "<P>"
myLocale = "1033"
MSCSDataFunctions.Locale = myLocale
Result = MSCSDataFunctions.ConvertDateString("12/1/2000", myLocale)
Response.Write "USA: " & Result
%>
</BODY>
</HTML>

See Also

DataFunctions Object

DataFunctions.Locale

DataFunctions.ConvertDateTimeString

DataFunctions.Date

DataFunctions.DateTime

Page.RequestTime


DataFunctions.ConvertDateTimeString

Use this method to convert a date and time string to a date/time Variant, based on the default or specified locale.

Definition

Function ConvertDateTimeString(
vtDateTime As Variant,
vtLocale As Variant
) As Variant

Parameters

vtDateTime

A Variant that contains a string that specifies the date/time value to convert.

vtLocale

A Variant that specifies the locale to use to convert the date. If this value is not specified, the value of the Locale property of the DataFunctions object is used.

Return Values

If this method completes successfully, it returns a datetime Variant that contains the converted date/time value; otherwise, NULL is returned.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

<HTML>
<HEAD>
</HEAD>
<BODY>
<%
' Converts date time string using US and France locales
' vSourceDateTime is a variant containing a date time string
Dim Result
Set MSCSDataFunctions = Server.CreateObject("Commerce.DataFunctions")
myLocale = "1036"
MSCSDataFunctions.Locale = myLocale
Result = MSCSDataFunctions.ConvertDateTimeString(vSourceDateTime, _
    myLocale)
Response.Write "France: " & Result & "<P>"
myLocale = "1033"
MSCSDataFunctions.Locale = myLocale
Result = MSCSDataFunctions.ConvertDateTimeString(vSourceDateTime , _
    myLocale)
Response.Write "USA: " & Result
%>
</BODY>
</HTML>

See Also

DataFunctions Object

DataFunctions.Locale

DataFunctions.ConvertDateString

DataFunctions.Date

DataFunctions.DateTime

Page.RequestTime


DataFunctions.ConvertFloatString

Use this method to convert a floating-point number represented as a string to a double Variant, based on the default or specified locale.

Definition

Function ConvertFloatString(
vtNum As Variant,
vtLocale As Variant
) As Variant

Parameters

vtNum

A Variant that contains a string representation of the floating-point number to convert.

vtLocale

A Variant that specifies the locale to use to convert the string. If this parameter is not specified, the value of the Locale property of the DataFunctions object is used.

Return Values

If this method completes successfully, it returns a double Variant that contains the converted number; otherwise, NULL is returned.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

<HTML>
<HEAD>
</HEAD>
<BODY>
<%
' Converts float using US and France locales
' vSourceFloat is a variant containing a float string
Dim Result
Set MSCSDataFunctions = Server.CreateObject("Commerce.DataFunctions")
myLocale = "1036"
MSCSDataFunctions.Locale = myLocale
Result = MSCSDataFunctions.ConvertFloatString(vSourceFloat , _
    myLocale)
Response.Write "France: " & Result & "<P>"
myLocale = "1033"
MSCSDataFunctions.Locale = myLocale
Result = MSCSDataFunctions.ConvertFloatString(vSourceFloat , _
    myLocale)
Response.Write "USA: " & Result
%>
</BODY>
</HTML>

See Also

DataFunctions Object

DataFunctions.Locale

DataFunctions.Float

DataFunctions.ValidateFloat


DataFunctions.ConvertMoneyStringToNumber

Use this method to convert a money string to a number, based on the default or specified locale.

Definition

Function ConvertMoneyStringToNumber(
vtMoney As Variant,
vtLocale As Variant
) As Variant

Parameters

vtMoney

A Variant that contains a string representation of the monetary value to convert.

vtLocale

A Variant that specifies the locale to use to convert the string. If this parameter is not specified, the value of the Locale property of the DataFunctions object is used.

Return Values

If this method completes successfully, it returns an integer Variant that represents the value of the specified string in the base monetary unit of the specified locale; otherwise, NULL is returned.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The ConvertMoneyStringToNumber method returns the value in the base monetary unit for a given locale. Thus, given a value in dollars, ConvertMoneyStringToNumber returns the number of cents in the dollar value.

Additionally, ConvertMoneyStringToNumber does not round values. For example, if you pass this method "123.009" the method returns 12300, not 12301.

This method returns a Variant of type long, not an OLE currency type.

In some cases, this method returns NULL when converting a string representation of monetary value to the currency Variant type for Swedish and Portuguese Standard locales. To avoid this problem, use the Microsoft Visual Basic Scripting Edition (VBScript) function Replace(MoneyString, CurrencyDigitGroupingSymbol, "") to remove the currency digit grouping symbol from the money string prior to calling the method ConvertMoneyStringToNumber.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

<HTML>
<HEAD>
</HEAD>
<BODY>
<%
Dim Result
Dim Amount
Amount = "12000"
Set MSCSDataFunctions = Server.CreateObject("Commerce.DataFunctions")
' Set Locale to USA
myLocale = "1033"
MSCSDataFunctions.Locale = myLocale
Result = MSCSDataFunctions.ConvertMoneyStringToNumber("34.095", myLocale)
Response.Write "USA: " & Result & "<P>"
%>
</BODY>
</HTML>

See Also

DataFunctions Object

DataFunctions.Locale

DataFunctions.ConvertFloatString

DataFunctions.ConvertNumberString


DataFunctions.ConvertNumberString

Use this method to convert an integer represented as a string to an integer Variant, based on the default or specified locale.

Definition

Function ConvertNumberString(
vtNum As Variant,
vtLocale As Variant
) As Variant

Parameters

vtNum

A Variant that contains a string representation of the number to convert.

vtLocale

A Variant that specifies the locale to use to convert the string. If this parameter is not specified, the value of the Locale property of the DataFunctions object is used.

Return Values

If this method completes successfully, it returns an integer Variant containing the converted number; otherwise, NULL is returned.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The ConvertNumberString method is designed to accept only integers. Passing a floating-point number as the vtNum parameter results in an error. To convert floating-point numbers, use the ConvertFloatString method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

<HTML>
<HEAD>
</HEAD>
<BODY>
<%
' Converts integer string using US and France locales
' vSourceInt is a variant containing an integer string
Dim Result
Set MSCSDataFunctions = Server.CreateObject("Commerce.DataFunctions")
myLocale = "1036"
MSCSDataFunctions.Locale = myLocale
Result = MSCSDataFunctions.ConvertNumberString(vSourceInt , _
    myLocale)
Response.Write "France: " & Result & "<P>"
myLocale = "1033"
MSCSDataFunctions.Locale = myLocale
Result = MSCSDataFunctions.ConvertNumberString(vSourceInt , _
    myLocale)
Response.Write "USA: " & Result
%>
</BODY>
</HTML>

See Also

DataFunctions Object

DataFunctions.Locale

DataFunctions.ConvertFloatString

DataFunctions.Number

DataFunctions.ValidateNumber


DataFunctions.ConvertStringToCurrency

Use this method to convert a string representation of a monetary value into a currency Variant, based on the specified locale and currency symbol.

Definition

Function ConvertStringToCurrency(
vtMoneyString As Variant,
Optional vtLocale As Variant,
Optional vtCurrencySymbol As Variant
) As Variant

Parameters

vtMoneyString

A Variant that contains the currency string to convert.

vtLocale

A Variant that specifies the locale to use when converting the string to a currency Variant. If this parameter is not specified, the value of the Locale property of the DataFunctions object is used.

vtCurrencySymbol

A Variant that contains the currency symbol to expect when converting the currency string.

Return Values

If this method completes successfully, it returns a Variant used to return the string representation of the converted monetary value.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

<HTML>
<HEAD>
</HEAD>
<BODY>
<%
Dim Result
Dim Amount
' vtAmount is a string representation of a monetary value
Set MSCSDataFunctions = Server.CreateObject("Commerce.DataFunctions")
' Set to USA
myLocale = 1033
MSCSDataFunctions.Locale = myLocale
Result = MSCSDataFunctions.ConvertStringtoCurrency(vtAmount, _
    myLocale, "$")
Response.Write "USA: " & Result & "<P>"

%>
</BODY>
</HTML>

See Also

DataFunctions Object

DataFunctions.Locale

DataFunctions.LocalizeCurrency

DataFunctions.ConvertMoneyStringToNumber


DataFunctions.ConvertTimeString

Use this method to convert a time string to a date Variant, based on the default or specified locale.

Definition

Function ConvertTimeString(
vtDate As Variant,
vtLocale As Variant
) As Variant

Parameters

vtDate

A Variant that specifies a string representation of the time to convert.

vtLocale

A Variant that specifies the locale to use to convert the string. If this parameter is not specified, the value of the Locale property of the DataFunctions object is used.

Return Values

If this method completes successfully, it returns a date Variant that contains the time; otherwise, NULL is returned. Additionally, if the string representation contains a date, ConvertTimeString returns NULL.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

<HTML>
<HEAD>
</HEAD>
<BODY>
<%
Dim Result
Dim Amount
' vtTimeString is a string representation of a time value
Set MSCSDataFunctions = Server.CreateObject("Commerce.DataFunctions")
' Set to USA
myLocale = 1033
MSCSDataFunctions.Locale = myLocale
Result = MSCSDataFunctions.ConvertTimeString(vtTimeString , myLocale)
Response.Write "USA: " & Result & "<P>"

See Also

DataFunctions Object

DataFunctions.Locale

DataFunctions.Time

DataFunctions.ValidateDateTime


DataFunctions.CurrencySymbol

The CurrencySymbol property is a read/write string Variant that stores the currency symbol to use if the currency symbol parameter is not specified in the ConvertStringToCurrency and LocalizeCurrency methods. The default value is the system default currency symbol.

Definition

Property CurrencySymbol As Variant

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

See Also

DataFunctions Object

DataFunctions.ConvertStringToCurrency

DataFunctions.LocalizeCurrency


DataFunctions.Date

Use this method to convert a date Variant to a string representation of the specified date, based on the default or specified locale.

Definition

Function Date(
dtDate As Date,
vtLocale As Variant
) As Variant

Parameters

dtDate

A Date Variant that contains the date to format.

vtLocale

A Variant that specifies the locale to use to convert the date to a string. If this parameter is not specified, the value of the Locale property of the DataFunctions object is used.

Return Values

If this method completes successfully, it returns a string Variant that contains the date value formatted as a string; otherwise, NULL is returned.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

<HTML>
<HEAD>
</HEAD>
<BODY>
<%
Dim Result, vtDateVar
' vtDateVar is a date variant containing a valid date
Set MSCSDataFunctions = Server.CreateObject("Commerce.DataFunctions")
' Set Locale to USA
myLocale = "1033"
MSCSDataFunctions.Locale = myLocale
Result = MSCSDataFunctions.Date(vtDateVar)
Response.Write "USA: " & Result & "<P>"
%>
</BODY>
</HTML>

See Also

DataFunctions Object

DataFunctions.Locale

DataFunctions.DateTime

DataFunctions.ValidateDateTime

DataFunctions.ConvertDateString


DataFunctions.DateTime

Use this method to convert a date Variant to a string representation of the specified date value based on the default or specified locale.

Definition

Function DateTime(
dtDate As Date,
vtLocale As Variant
) As Variant

Parameters

dtDate

A Date that contains the date/time value to convert.

vtLocale

A Variant that specifies the locale to use to convert the Date Variant to a string. If this parameter is not specified, the value of the Locale property of the DataFunctions object is used.

Return Values

If this method completes successfully, it returns a string Variant that contains the string representation of the specified date/time value; otherwise, NULL is returned.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

<HTML>
<HEAD>
</HEAD>
<BODY>
<%
Dim Result, vtDateVar
' vtDateVar is a date variant containing a valid date time value
Set MSCSDataFunctions = Server.CreateObject("Commerce.DataFunctions")
' Set Locale to USA
myLocale = "1033"
MSCSDataFunctions.Locale = myLocale
Result = MSCSDataFunctions.DateTime(vtDateVar)
Response.Write "USA: " & Result & "<P>"
%>
</BODY>
</HTML>

See Also

DataFunctions Object

DataFunctions.Locale

DataFunctions.Date

DataFunctions.ValidateDateTime

Page.RequestTime


DataFunctions.Float

Use this method to convert a number stored in a double to a string representation of that number, based on the default or specified locale.

Definition

Function Float(
fNumber As Double,
vtLocale As Variant
) As Variant

Parameters

fNumber

A Double that contains the floating-point number to convert.

vtLocale

A Variant that specifies the locale to use to convert the floating-point number to a string. If this parameter is not specified, the value of the Locale property of the DataFunctions object is used.

Return Values

If this method completes successfully, it returns a string Variant that contains the string representation of the specified floating-point number; otherwise, NULL is returned.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

<HTML>
<HEAD>
</HEAD>
<BODY>
<%
Dim Result
Dim Amount
Amount = "12000"
Set MSCSDataFunctions = Server.CreateObject("Commerce.DataFunctions")
' Set Locale to USA
myLocale = "1033"
myInputFloat = 100.00010
MSCSDataFunctions.Locale = myLocale
Result = MSCSDataFunctions.Float(myInputFloat, myLocale,True, False)
Response.Write "USA, No Rounding, With Trailing: " & Result & "<P>"
Result = MSCSDataFunctions.Float(myInputFloat, myLocale,True, True)
Response.Write "USA, No Rounding, Trim Trailing: " & Result & "<P>"
Result = MSCSDataFunctions.Float(myInputFloat, myLocale,False, False)
Response.Write "USA, Rounding, With Trailing: " & Result & "<P>"
Result = MSCSDataFunctions.Float(myInputFloat, myLocale,False, True)
Response.Write "USA, Rounding, Trim Trailing: " & Result & "<P>"
%>
</BODY>
</HTML>

See Also

DataFunctions Object

DataFunctions.Locale

DataFunctions.ValidateFloat

DataFunctions.ConvertFloatString


DataFunctions.GetLocaleInfo

Use this method to get information on the specified locale.

Definition

Function GetLocaleInfo(
vtInfo As Long,
vtLocale As Variant
) As Variant

Parameters

vtInfo

A Long that indicates the type of locale information to return. This value must map to one of the LCTYPE constants. For information about these constants, see the Win32 SDK Help.

vtLocale

A Variant that identifies the locale for which to return information. If this Variant is empty (VT_EMPTY) or null (VT_NULL), the method returns information for the locale specified by the most recent call to put_Locale.

Return Values

If this method completes successfully, it returns a string Variant that contains the requested locale information; otherwise, NULL is returned.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The Locale property stores a number value that indicates the default locale to be used by the DataFunctions methods to format date, time, money, and number information. For those DataFunctions methods take a locale value for a parameter, if that value is not supplied, the value of this property is used.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

Dim vtResult, lInfo
Set MSCSDataFunctions = Server.CreateObject("Commerce.DataFunctions")
' Set Locale to USA
myLocale = "1033"
MSCSDataFunctions.Locale = myLocale
vtResult = MSCSDataFunctions.GetLocaleInfo(lInfo, myLocale)

See Also

DataFunctions Object

DataFunctions.Locale


DataFunctions.GetLocaleList

Use this method to retrieve a SimpleList object that contains the locales available on the computer.

Definition

Function GetLocaleList() As Variant

Parameters

None.

Return Values

If this method completes successfully, it returns an object Variant that references a SimpleList object that specifies the locales available on the computer.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

DataFunctions Object

DataFunctions.Locale


DataFunctions.Locale

The Locale property is a read/write Long that indicates the default locale to be used by the DataFunctions methods to format date, time, money, and number information. Where the DataFunctions methods take a locale value for a parameter, if that value is not supplied, the value to which you initialize this property is used.

Definition

Property Locale As Long

Parameters

None.

Error Values

This property sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Many of the methods implemented in the Commerce Server objects take locale identifiers as optional parameters. These identifiers are represented by unique hexadecimal codes.

The list of locale and language identifiers can be found in the National Language Support API. This specification can be found in the Microsoft Developer Network. (See Platform SDK, Windows Base Services, International Features).

This list is continually growing and further locale support may be added to any future product.

The following table contains a list of these hexadecimal locale identifiers.

Identifier | Locale
0x0000 | Language Neutral
0x0400 | Process Default Language
0x0401 | Arabic (Saudi Arabia)
0x0801 | Arabic (Iraq)
0x0c01 | Arabic (Egypt)
0x1001 | Arabic (Libya)
0x1401 | Arabic (Algeria)
0x1801 | Arabic (Morocco)
0x1c01 | Arabic (Tunisia)
0x2001 | Arabic (Oman)
0x2401 | Arabic (Yemen)
0x2801 | Arabic (Syria)
0x2c01 | Arabic (Jordan)
0x3001 | Arabic (Lebanon)
0x3401 | Arabic (Kuwait)
0x3801 | Arabic (U.A.E.)
0x3c01 | Arabic (Bahrain)
0x4001 | Arabic (Qatar)
0x0402 | Bulgarian
0x0403 | Catalan
0x0404 | Chinese (Taiwan)
0x0804 | Chinese (PRC)
0x0c04 | Chinese (Hong Kong)
0x1004 | Chinese (Singapore)
0x0405 | Czech
0x0406 | Danish
0x0407 | German (Standard)
0x0807 | German (Swiss)
0x0c07 | German (Austrian)
0x1007 | German (Luxembourg)
0x1407 | German (Liechtenstein)
0x0408 | Greek
0x0409 | English (United States)
0x0809 | English (United Kingdom)
0x0c09 | English (Australian)
0x1009 | English (Canadian)
0x1409 | English (New Zealand)
0x1809 | English (Ireland)
0x1c09 | English (South Africa)
0x2009 | English (Jamaica)
0x2409 | English (Caribbean)
0x2809 | English (Belize)
0x2c09 | English (Trinidad)
0x040a | Spanish (Traditional Sort)
0x080a | Spanish (Mexican)
0x0c0a | Spanish (Modern Sort)
0x100a | Spanish (Guatemala)
0x140a | Spanish (Costa Rica)
0x180a | Spanish (Panama)
0x1c0a | Spanish (Dominican Republic)
0x200a | Spanish (Venezuela)
0x240a | Spanish (Colombia)
0x280a | Spanish (Peru)
0x2c0a | Spanish (Argentina)
0x300a | Spanish (Ecuador)
0x340a | Spanish (Chile)
0x380a | Spanish (Uruguay)
0x3c0a | Spanish (Paraguay)
0x400a | Spanish (Bolivia)
0x440a | Spanish (El Salvador)
0x480a | Spanish (Honduras)
0x4c0a | Spanish (Nicaragua)
0x500a | Spanish (Puerto Rico)
0x040b | Finnish
0x040c | French (Standard)
0x080c | French (Belgian)
0x0c0c | French (Canadian)
0x100c | French (Swiss)
0x140c | French (Luxembourg)
0x040d | Hebrew
0x040e | Hungarian
0x040f | Icelandic
0x0410 | Italian (Standard)
0x0810 | Italian (Swiss)
0x0411 | Japanese
0x0412 | Korean
0x0812 | Korean (Johab)
0x0413 | Dutch (Standard)
0x0813 | Dutch (Belgian)
0x0414 | Norwegian (Bokmal)
0x0814 | Norwegian (Nynorsk)
0x0415 | Polish
0x0416 | Portuguese (Brazilian)
0x0816 | Portuguese (Standard)
0x0418 | Romanian
0x0419 | Russian
0x041a | Croatian
0x081a | Serbian (Latin)
0x0c1a | Serbian (Cyrillic)
0x041b | Slovak
0x041c | Albanian
0x041d | Swedish
0x081d | Swedish (Finland)
0x041e | Thai
0x041f | Turkish
0x0421 | Indonesian
0x0422 | Ukrainian
0x0423 | Belarusian
0x0424 | Slovenian
0x0425 | Estonian
0x0426 | Latvian
0x0427 | Lithuanian
0x0429 | Farsi
0x042a | Vietnamese
0x042d | Basque
0x0436 | Afrikaans
0x0438 | Faeroese

See Also

DataFunctions Object

DataFunctions.GetLocaleList


DataFunctions.LocalizeCurrency

Use this method to retrieve a string representation of a currency value formatted to a specified locale and currency symbol.

Definition

Function LocalizeCurrency(
cyCurrency As Variant,
Optional vtLocale As Variant,
Optional vtCurrencySymbol As Variant
) As Variant

Parameters

cyCurrency

A currency Variant that contains the value to format as a string.

vtLocale

A Variant that contains the locale to use when formatting the string.

vtCurrencySymbol

[in, optional] A Variant that contains the currency symbol to use when formatting the string.

Return Values

If this method completes successfully, it returns a Variant containing the formatted string.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

<HTML>
<HEAD>
</HEAD>
<BODY>
<%
Dim Result
Dim Amount
' vtAmount is a Currency Variant
Set MSCSDataFunctions = Server.CreateObject("Commerce.DataFunctions")
' Set to USA
myLocale = 1033
MSCSDataFunctions.Locale = myLocale
Result = MSCSDataFunctions.LocalizeCurrency(vtAmount, myLocale, "$")
Response.Write "USA: " & Result & "<P>"

' Set to Minbar
myLocale = 1036
MSCSDataFunctions.Locale = myLocale
Result = MSCSDataFunctions.LocalizeCurrency(vtAmount, myLocale, "MB")
Response.Write "Minbar: " & Result & "<P>"

%>
</BODY>
</HTML>

See Also

DataFunctions Object

DataFunctions.Locale

DataFunctions.ConvertStringToCurrency


DataFunctions.Money

Use this method to convert a long that contains a monetary value to an equivalent string representation, based on the default or specified locale.

Definition

Function Money(
lMoney As Long,
vtLocale As Variant
) As Variant

Parameters

lMoney

A Long that contains the monetary value to convert to a string, specified in the base monetary unit of the locale used to perform the conversion. (This value is not an OLE currency type.)

vtLocale

A Variant that specifies the locale to use to convert the monetary value to a string. If this parameter is not specified, the value of the Locale property of the DataFunctions object is used.

Return Values

If this method completes successfully, it returns a string Variant that contains a string representation of the specified monetary value; otherwise, NULL is returned.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

<HTML>
<HEAD>
</HEAD>
<BODY>
<%
Dim Result
Dim Amount
' Amount is a long containing a monetary value in base currency units
' (base currency unit for US is cents)
Set MSCSDataFunctions = Server.CreateObject("Commerce.DataFunctions")
myLocale = "1036"
MSCSDataFunctions.Locale = myLocale
Result = MSCSDataFunctions.Money(Amount, myLocale)
Response.Write "France: " & Result & "<P>"
myLocale = "1033"
MSCSDataFunctions.Locale = myLocale
Result = MSCSDataFunctions.Money(Amount, myLocale)
Response.Write "USA: " & Result
%>
</BODY>
</HTML>

See Also

DataFunctions Object

DataFunctions.Locale

DataFunctions.ConvertMoneyStringToNumber


DataFunctions.Number

Use this method to convert a long integer to its equivalent string representation, based on the default or specified locale.

Definition

Function Number(
lNumber As Long,
vtLocale As Variant
) As Variant

Parameters

lNumber

A Long that contains the number to convert to a string.

vtLocale

A Variant that specifies the locale to use to convert the number to a string. If this parameter is not specified, the value of the Locale property of the DataFunctions object is used.

Return Values

If this method completes successfully, it returns a Variant that contains the string representation of the specified number; otherwise, NULL is returned.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

<HTML>
<HEAD>
</HEAD>
<BODY>
<%
Dim Result
Set MSCSDataFunctions = Server.CreateObject("Commerce.DataFunctions")
' Set Locale to USA
myLocale = "1033"
MSCSDataFunctions.Locale = myLocale
Result = MSCSDataFunctions.Number(9999999.99,myLocale)
Response.Write "USA: " & Result & "<P>"

' Set Locale to France
myLocale = "1036"
MSCSDataFunctions.Locale = myLocale

Result = MSCSDataFunctions.Number(9999999,myLocale)

Response.Write "France: " & Result & "<P>"
%>
</BODY>
</HTML>

See Also

DataFunctions Object

DataFunctions.Locale

DataFunctions.ConvertNumberString


DataFunctions.Time

Use this method to converts a Date to a string representation of the time.

Definition

Function Time(
dtDate As Date,
vtLocale As Variant
) As Variant

Parameters

dtDate

A Date type that contains the time value to convert.

vtLocale

A Variant that specifies the locale to use to convert the time value to a string. If this parameter is not specified, the value of the Locale property of the DataFunctions object is used.

Return Values

If this method completes successfully, it returns a string Variant that contains the string representation of the specified time value; otherwise, NULL is returned.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

<HTML>
<HEAD>
</HEAD>
<BODY>
<%
' vResult is a Variant, dDate is a Date
Set MSCSDataFunctions = Server.CreateObject("Commerce.DataFunctions")
' Set Locale to USA
myLocale = "1033"
MSCSDataFunctions.Locale = myLocale
vResult = MSCSDataFunctions.Time(dDate, myLocale)
Response.Write "USA: " & Result & "<P>"

%>
</BODY>
</HTML>

See Also

DataFunctions Object

DataFunctions.Locale

DataFunctions.ConvertTimeString


DataFunctions.ValidateDateTime

Use this method to check whether a string contains a valid date, time, or date and time, and optionally to check against a specified range.

Definition

Function ValidateDateTime(
vtDate As Variant,
vtMin As Variant,
vtMax As Variant
) As Variant

Parameters

vtDate

A Variant that contains the value to validate. This value can be a date, a time, or both.

vtMin

A Variant that contains a value specifying the low end of the range. The default value for this parameter is NULL, which means that the vtMin parameter is ignored in the range validation.

vtMax

A Variant that contains a value specifying the high end of the range. The default value for this parameter is NULL, which means that the vtMax parameter is ignored in the range validation.

Return Values

If this method completes successfully, it returns a Boolean Variant indicating whether the vtDate parameter is valid. A value of True indicates the vtDate parameter is a valid date, time, or date/time, and that it is within the given range, if any.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' vResult is a Variant, vSourceDate is a Variant containing
' a string representation of a date or date and time
Set MSCSDataFunctions = Server.CreateObject("Commerce.DataFunctions")
vResult = MSCSDataFunctions.ValidateDateTime(vSourceDate,"1/1/1900", _
    "12/31/2525")

See Also

DataFunctions Object

DataFunctions.Date

DataFunctions.DateTime

DataFunctions.Time

DataFunctions.ConvertDateString

DataFunctions.ConvertDateTimeString

DataFunctions.ConvertTimeString


DataFunctions.ValidateFloat

Use this method to check whether a string contains a valid floating-point number, and to optionally check the value of the number against a specified range.

Definition

Function ValidateFloat(
vtNumber As Variant,
vtMin As Variant,
vtMax As Variant
) As Variant

Parameters

vtNumber

A Variant that contains the floating-point number to validate.

vtMin

A Variant that contains a value specifying the low end of the range. The default value for this parameter is NULL, which means that the vtMin parameter is ignored in the range validation.

vtMax

A Variant that contains a value specifying the high end of the range. The default value for this parameter is NULL, which means that the vtMax parameter is ignored in the range validation.

Return Values

If this method completes successfully, it returns a Boolean Variant that indicates whether the vtNumber parameter is valid. A value of True indicates the vtNumber parameter is a valid floating-point number, and that it is within the given range, if any.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

<HTML>
<HEAD>
</HEAD>
<BODY>
<%
Dim Result
Dim Amount
Set MSCSDataFunctions = Server.CreateObject("Commerce.DataFunctions")
' Set Locale to USA
myFloat = 12.33
MSCSDataFunctions.Locale = myLocale
Result = MSCSDataFunctions.ValidateFloat(myFloat, 1, 10)
Response.Write myFloat & " Is this float between 1 & 10?: " & " " _
    & Result & "<P>"
myFloat = 2.33
Result = MSCSDataFunctions.ValidateFloat(myFloat, 1, 10)
Response.Write myFloat & " Is this float between 1 & 10?: " & " " _
    & Result & "<P>"
%>
</BODY>
</HTML>

See Also

DataFunctions Object

DataFunctions.Float

DataFunctions.ConvertFloatString


DataFunctions.ValidateNumber

Use this method to check whether a string representation of a number is valid, and optionally to check the value of the number against a specified range.

Definition

Function ValidateNumber(
vtNumber As Variant,
vtMin As Variant,
vtMax As Variant
) As Variant

Parameters

vtNumber

A Variant that contains a string representation of a number to validate.

vtMin

A Variant that contains a value specifying the low end of the range. The default value for this parameter is NULL, which means that the vtMin parameter is ignored in the range validation.

vtMax

A Variant that contains a value specifying the high end of the range. The default value for the vtMax parameter is NULL, which means that this parameter is ignored in the range validation.

Return Values

If this method completes successfully, it returns a Boolean Variant that indicates whether the vtNumber parameter is valid. A value of TRUE indicates the vtNumber parameter is a valid whole number, and that it is within the given range, if any.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

<HTML>
<HEAD>
</HEAD>
<BODY>
<%
Dim Result
Dim Amount
Set MSCSDataFunctions = Server.CreateObject("Commerce.DataFunctions")
' Set Locale to USA
MSCSDataFunctions.Locale = myLocale
myInt = 24
Result = MSCSDataFunctions.ValidateNumber(myInt , 1, 10)
Response.Write myInt & " Is this integer between 1 & 10?: " & _
    " " & Result & "<P>"
myInt = 2
Result = MSCSDataFunctions.ValidateNumber(myInt , 1, 10)
Response.Write myInt & " Is this integer between 1 & 10?: " & _
    " " & Result & "<P>"
%>
</BODY>
</HTML>

See Also

DataFunctions Object

DataFunctions.Number

DataFunctions.ConvertNumberString


DBStorage Object

Use this method to map Dictionary and SimpleList objects to and from the database, primarily for the storage of receipt and order information. The DBStorage object is created as needed on each page.

ProgID: | Commerce.DBStorage (Externally creatable)
COM Class Name: | MSCSDBStorage_3_0
Type Library Name: | Commerce 1.0 Type Library
DLL Name: | Commerce.dll
Threading Model: | Both

The single property of the DBStorage object is shown in the following table.

Property | Type | Description
Mapping | Object | Maps a database column to an entry in the OrderForm or Dictionary object that DBStorage uses to insert and retrieve data. This property is read/write.

The methods of the DBStorage object are shown in the following table.

Method | Description
CommitData | Updates one or more records in the database storage.
DeleteData | Deletes a row from the database storage, based on the data stored in a Dictionary or OrderForm object.
DeleteDataKey | Deletes a row of data from the database storage, based on the specified key.
GetData | Retrieves a row of data from the database storage, based on a specified key value.
InitStorage | Initializes the object. This method must be called prior to calling any other DBStorage method.
InsertData | Inserts the specified data into the database storage.
LookupData | Retrieves a single row from the database storage, based on the specified column names and values.
LookupMultipleData | Retrieves multiple results from the database storage.
ProcessData | Unpacks the data stored in the MarshalColumn column for a given row, and returns the resulting row in a Dictionary object.

Remarks

The DBStorage object serves as an interface between the site database and Dictionary and OrderForm objects. A DBStorage object contains methods for transferring data between the database and the data object.

Using the CreateObject method of the Server object to instantiate a DBStorage object will return an uninitialized instance of the DBStorage object. Use the InitStorage method to initialize the returned object instance. Attempting to call any other DBStorage method prior to calling the InitStorage method results in an error.

When the DBStorage object retrieves data from the database, it creates the appropriate type of data object (an OrderForm or Dictionary object), stores the requested data there, and then returns the data object. When the DBStorage object is used to save data in the database, you pass it the OrderForm or Dictionary object containing the data, and the DBStorage method copies the data from the data object into the database.

See Also

General Purpose Objects


DBStorage.CommitData

Use this method to update the database table based on the contents of the specified Dictionary or OrderForm object.

Definition

Sub CommitData(
vtReserved As Variant,
pdispData As Object
)

Parameters

vtReserved

A Variant reserved for future use. The CommitData method ignores the value of this parameter.

pdispData

An object reference to the OrderForm or Dictionary object that contains the updated data.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The CommitData method does not support database tables containing fields of type TimeStamp. Instead, use the vtChanged parameter to the DBStorage.InitStorage method, which provides the same functionality as using TimeStamp fields.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' Order is a Commerce.OrderForm object; OrderFormStorage is
' an initialized Commerce.DBStorage object

Order.order_id = "Order_tmp"
Order.shopper_id = "Shopper_tmp"
OrderFormStorage.CommitData(Null, Order)

See Also

DBStorage Object

DBStorage.InitStorage

DBStorage.InsertData


DBStorage.DeleteData

Use this method to delete a row from the data source, based on the data stored in the specified Dictionary or OrderForm object.

Definition

Sub DeleteData(
vtReserved As Variant,
pdispData As Object
)

Parameters

vtReserved

A Variant reserved for future use. This parameter is ignored by the DeleteData method.

pdispData

An object reference to the data object to delete. This data object can be either an OrderForm or a Dictionary, but must correspond in type to the object type specified as the ProgID in the initial call to the InitStorage method.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The DeleteDataKey method differs from the DeleteData method in that the DeleteDataKey requires only the value stored in the key column of the underlying table. This is the column specified as the key to the underlying table through a previous call to the InitStorage method.

Thus, if you specify an IDENTITY field in an SQL table as the key into the data source, you can delete all the columns for a specified row by simply providing the appropriate counter value. Alternatively, you can initialize a Dictionary object to the values stored in one or more columns, and pass this initialized object to the DeleteData method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' Order is a Commerce.OrderForm object; OrderFormStorage is
' an initialized Commerce.DBStorage object

Order.order_id = "Order_tmp"
OrderFormStorage.DeleteData(Null, Order)

See Also

DBStorage Object

DBStorage.InitStorage

DBStorage.DeleteDataKey

DBStorage.InsertData


DBStorage.DeleteDataKey

Use this method to delete a row of data, based on the specified key value.

Definition

Sub DeleteDataKey(
vtReserved As Variant,
vtKey As Variant
)

Parameters

vtReserved

This parameter is reserved for future use and is ignored by the current implementation of the DeleteDataKey method. This parameter is required for compatibility with Site Server 3.0 Commerce Edition, but is not used.

vtKey

A Variant that contains the key value for the row to delete. This key corresponds to the column designated as the table key in the initial call to the InitStorage method. Thus, if the call to the InitStorage method specifies column "some_column" as the table key, then the DeleteDataKey method searches "some_column" for the value stored in the vtKey parameter, and deletes the corresponding row of data.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The DeleteDataKey method differs from the DeleteData method in that the DeleteDataKey requires only the value stored in the key column of the underlying table. This is the column specified as the key to the underlying table through a previous call to the InitStorage method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' Order is a Commerce.OrderForm object; OrderFormStorage is
' an initialized Commerce.DBStorage object

Order.shopper_id = "Shopper_tmp"
OrderFormStorage.DeleteDataKey(Null, "1234567890WSXCDERFVBGTRESWER")

See Also

DBStorage Object

DBStorage.InitStorage

DBStorage.DeleteData

DBStorage.InsertData


DBStorage.GetData

Use this method to retrieve a row of data from the database, based on the specified key value. If the data is found, this method creates and returns an OrderForm or Dictionary object containing the requested data.

Definition

Function GetData(
vtReserved As Variant,
vtKey As Variant
) As Variant

Parameters

vtReserved

A Variant reserved for future use. The GetData method ignores any value stored in this parameter.

vtKey

A Variant that contains the key value on which to base the search. The GetData method searches for this value in the table column specified as the table key in the initial call to the InitStorage method.

Return Values

If this method completes successfully, a Variant containing a Dictionary or OrderForm object that contains the retrieved row is returned.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' Order is a Commerce.OrderForm object; OrderFormStorage is
' an initialized Commerce.DBStorage object; vtVar is a Variant

Order.order_id = "Order_tmp"
VtVar = OrderFormStorage.GetData(Null, Order.order_id)

See Also

DBStorage Object

DBStorage.InitStorage

DBStorage.LookupData


DBStorage.InitStorage

Use this method to initialize the DBStorage object. You must call this method immediately after object creation and before calling any other object methods. Attempting to call any other method prior to calling the InitStorage method results in an error.

Definition

Sub InitStorage(
vtDataSourceOrDSN As Variant,
Table As String,
bstrKey As String,
vtProgID As Variant,
vtMarshal As Variant,
vtChanged As Variant
)

Parameters

vtDataSourceOrDSN

A Variant that contains a valid object reference to a DataSource object, or data source name (DSN).

Table

A String that contains the name of the table within the data source in which to maintain the data.

bstrKey

A String that contains the column name that the DBStorage object uses as a key into the database table. This column should be marked to contain unique values.

vtProgID

A Variant that contains the ProgID of the object in which data passed to or retrieved by DBStorage methods will be stored. This parameter can be Commerce.Dictionary for storing Dictionary objects or Commerce.OrderForm for storing OrderForm objects. Methods (such as GetData) that return data from the database create an instance of the specified class with the requested data stored within it.

vtMarshal

A Variant that contains the text string that, if specified, indicates the name of a column in the database into which the CommitData or InsertData method will store all the data from the specified data object, serialized into an encoded binary format. (Objects in the stored item that have corresponding column names in the database are also stored in those columns in the database.) If this argument is specified, the database must contain a column by that name, or an error will result. If this argument is not specified, then no data from the object is serialized and saved in the database in binary format, and items in the object that do not have corresponding columns in the database are discarded. When using a Microsoft SQL Server database, the maximum size of the data in this column is the same as the maximum size for the SQL Server text/image data type (2,147,483,647 bytes).

vtChanged

A Variant that contains the name of a key or attribute in the database into which to write the date when the data is changed. (If you do not specify a column name that exists in the database, the change date will be included in the marshaled data.)

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' strDSN is the data source connection string; OrderFormStorage
' is an uninitialized Commerce.DBStorage object; "Site_basket"
' is the name of the table in the referenced data source;
' "shopper_id" is the primary key in the "Site_basket" table;
' "marshalled_order" is the name of the column for this DBStorage
' object instance to use for marshaling data; "date_changed"
' is the name of the database column that contains the date
' of the most recent change
' This sample initializes OrderFormStorage as an OrderForm storage object:

OrderFormStorage.InitStorage(strDSN, "Site_basket", "shopper_id", _
    "Commerce.OrderForm", "marshalled_order", "date_changed")

See Also

DBStorage Object


DBStorage.InsertData

Use this method to insert the contents of the specified Dictionary object into a database row.

Definition

Sub InsertData(
vtReserved As Variant,
pdispData As Object
)

Parameters

vtReserved

A Variant reserved for future use. This parameter is ignored by the InsertData method.

pdispData

An object reference to the Dictionary object or OrderForm object that contains the data to insert.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' Order is a Commerce.OrderForm object; OrderFormStorage is
' an initialized Commerce.DBStorage object

Order.order_id = "Order_tmp"
Order.shopper_id = "Shopper_tmp"
OrderFormStorage.InsertData(Null, Order)

See Also

DBStorage Object

DBStorage.InitStorage

DBStorage.CommitData


DBStorage.LookupData

Use this method to retrieve a single row from the data source based upon column names and values that you specify. If the data is found, this method creates and returns an OrderForm or Dictionary object (depending on the vtProgID parameter passed to the InitStorage method) containing the requested data.

Definition

Function LookupData(
vtReserved As Variant,
pvtKeys As Variant,
pvtValues As Variant
) As Variant

Parameters

vtReserved

A Variant reserved for future use. The LookupData method ignores any value stored in this parameter.

pvtKeys

A Variant that identifies the columns in which to search for the data. This Variant can be either a SimpleList object or an Array.

pvtValues

A Variant that identifies the values for which to search. This parameter can be either a SimpleList object or an Array.

Return Values

If this method completes successfully, it returns a Variant that contains the result of the lookup; this Variant references a Dictionary object that contains the row data.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The pvtKeys and pvtValues parameters are arrays that you pass to the LookupData method share in an index-to-index relationship. This means that they must contain an identical number of members and that the value stored in the pvtValues (N) parameter will be searched for in the column specified by the pvtKeys (N) parameter.

If the arrays contain more than one element, the LookupData method searches for a row in which all of the column/value pairs match.

Because the LookupData method returns only a single row of data, specifying column and value information that would result in the retrieval of more than one row results in an error.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' OrderFormStorage is an initialized DBStorage object instance.
' In the following example, the LookupData method searches
' for a row in which both the shopper_id column contains the
' value returned by the shopper_id variable and the shopper_name
' column contains the customer name returned by the Page.Request method:

' Attempt to determine if this shopper is already registered.
shopper_id = Page.GetShopperID

On Error Resume Next
Dim keys(1)
Dim values(1)
keys(0) = "shopper_id"
keys(1) = "shopper_name"
values(0) = shopper_id
values(1) = Page.Request("shopper_name", Null, 1, 60)

exists=NULL
set exists = OrderFormStorage.LookupData(Null, keys, values)
If IsNull(exists) Then
' This shopper id and name does not exist in the specified columns

See Also

DBStorage Object

DBStorage.InitStorage

DBStorage.GetData

DBStorage.LookupMultipleData


DBStorage.LookupMultipleData

Use this method to retrieve multiple results from the database table. If the data is found, this method creates a SimpleList object that contains OrderForm or Dictionary objects, depending on the vtProgID parameter passed to the InitStorage method.

Definition

Function LookupMultipleData(
vtReserved As Variant,
pvtKeys As Variant,
pvtValues As Variant
) As Variant

Parameters

vtReserved

A Variant reserved for future use. The LookupData method ignores any value stored in this parameter.

pvtKeys

A Variant that identifies the columns in which to search for the data. This Variant can be either a SimpleList object or an Array.

pvtValues

A Variant that identifies the values for which to search. This parameter can be either a SimpleList object or an Array.

Return Values

If this method completes successfully, it returns a Variant that references a SimpleList object that consists of one or more Dictionary objects, one for each row of data returned.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' Order is a Commerce.OrderForm object; OrderFormStorage is
' an initialized Commerce.DBStorage object

Order.order_id = "Order_tmp"
Order.shopper_id = "Shopper_tmp"
OrderFormStorage.InsertData(Null, Order)
OrderFormStorage.LookupMultipleData(Null, Array("order_id"), _
Array("Order_tmp"))

See Also

DBStorage Object

DBStorage.InitStorage

DBStorage.GetData

DBStorage.LookupData


DBStorage.Mapping

The Mapping property maps a database column to an entry in the OrderForm or Dictionary object that the DBStorage object uses to insert and retrieve data.

Definition

Property Mapping As Object

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

A mapping Dictionary object makes it possible to map the column names in a database table to one or more names that you choose, usually for display to the site user. Suppose, for example, that your database table contains a column named "shopper_name", but that you want to display the contents of this column as the more human-readable "Shopper Name". Consequently, you initialize a "shopper_name" key in a Dictionary object to "Shopper Name", and use this object to set the Mapping property. When you call a DBStorage object data retrieval method, such as GetData, to read a row of data into a Dictionary object, the Dictionary key for the "shopper_name" column reads "Shopper Name". This new mapping means that you do not have to translate the column name to a more human-readable name before displaying its values to the site user. You can simply display the keys and values as they appear in the Dictionary object returned by the GetData method.

See Also

DBStorage Object

DBStorage.InitStorage


DBStorage.ProcessData

Use this method to unpack the data stored in the MarshalColumn database column for a given row, and returns the resulting row in a Dictionary object.

Definition

Function ProcessData(
pdispData As IDispatch
) As Object

Parameters

pdispData

An object reference to a Dictionary object that contains the marshaled data.

Return Values

If this method completes successfully, it returns an object reference to a Dictionary object that contains the unmarshaled data.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' dSource is a Dictionary object; OrderFormStorage is
' an initialized Commerce.DBStorage object; dDictionary is a
' Dictionary object which will receive the unmarshaled data

Order.order_id = "Order_tmp"
Order.shopper_id = "Shopper_tmp"
dDictionary = OrderFormStorage.ProcessData(dSource)

See Also

DBStorage Object

DBStorage.InitStorage


Dictionary Object

Use this object to support the creation, storage, and retrieval of name/value pairs in memory. Every value in a Dictionary object is a Variant, which means you can create a Dictionary object that consists of almost any kind of value (including other Dictionary objects), and that you can store any combination of Variant types in the same Dictionary object.

ProgID: | Commerce.Dictionary (Externally creatable)
COM Class Name: | CDictionary
Type Library Name: | Microsoft Commerce 2000 Core Components Type Library
DLL Name: | MscsCore.dll
Threading Model: | Both

The properties of the Dictionary object are shown in the following table.

Property | Type | Description
Count | Long | Returns the number of elements in the Dictionary object. This property is read-only.
Prefix | String | Stores the string that acts as a filter when the contents of the Dictionary object are saved (usually to a database). When the name of a name/value pair begins with the specified prefix, that name/value pair is not saved. This property is read/write.
Value | Variant | Stores the value of a given Dictionary key. This property is read/write.

Remarks

Because a Dictionary object is designed to be a general-purpose collection, you can use it for almost anything that its internal structure supports.

When you need to create a Dictionary object explicitly (that is, when the object is not created for you by some other Commerce Server 2000 object), use the CreateObject method of the Active Server Pages (ASP) Server object, as follows:

Set dictUser = Server.CreateObject("Commerce.Dictionary")

After creating the object, you can add elements to it, as follows:

dictUser.first_name = "Steve"

In this example, first_name is a Dictionary key, and Steve becomes the assigned value of this key. Each statement actually accomplishes three functions: declaring the Dictionary key, adding that key to the Dictionary object, and setting the key to a value.

You can extract values from a Dictionary object in several ways. You can simply place the object.key identifier on the right side of the assignment statement. Such an assignment returns the value of the referenced key:

my_first_name = dictUser.first_name

Or you can use the Value method to get the value of a given key:

my_first_name = dictUser.Value("first_name")

You can also use the For Each statement in Microsoft Visual Basic Scripting Edition (VBScript) to enumerate through the keys or the values of a Dictionary object as follows (this example assumes that every value in the dictionary contains text):

' Get the key names
For Each element In dictUser
    Response.Write element
Next

' Get the values
For Each element In dictUser
    Response.Write dictUser.Value(element)
Next

The data in a Dictionary object can be saved in a database table by using the DBStorage object.

Commerce Server 2000 sites use implementations of the Dictionary object to store sets of data that are required by various other objects and pipeline components.

Unlike previous versions of the dictionary, the dictionary in Commerce Server 2000 is implemented as a hash of name value pairs. This enables the dictionary to perform fast lookups even when a large number of key/value pairs are stored. It also has the side effect that enumerations of dictionary keys may not be returned in the same order they are stored.

The dictionary object aggregates the Free Threaded Marshaller (FTM) for performance reasons (so that calls to the dictionary will never go through a proxy, no matter what COM apartment it is called from). Because of this, you may not store a reference to an apartment-threaded object in a dictionary. Doing so may result in errors such as RPC_E_WRONGTHREAD when the object pointer is retrieved and used.

The Dictionary object supports the ICloneable and IPersistXML interfaces. Use the ICloneable interface to deep copy all name/value pairs into a new dictionary. Use the IPersistXML interface to convert the Dictionary entries into an XML string and back again.

See Also

General Purpose Objects

IPersistXML Interface

SimpleList Object


Dictionary.Count

The Count property is a read-only Long that contains the number of elements in the Dictionary object instance.

Definition

Property Count As Long

Parameters

None.

Error Values

This property sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The Count parameter points to valid data only if the property is accessed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Dictionary Object


Dictionary.Prefix

The Prefix property is a read/write String that acts as a filter when the contents of the Dictionary object are saved (usually to a database). When the name of a name/value pair begins with the specified prefix, that name/value pair is not saved. By default, the prefix is "_", so that any keywords beginning with an underscore character are excluded.

Definition

Property Prefix As String

Parameters

None.

Error Values

This property sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

By default, the prefix is "_", so that any keywords beginning with an underscore character are excluded.

The pipeline component that saves receipts usually sets the prefix to "_cc_", so that all credit-card information is not saved in the database. The actual string used by the pipeline component is configurable.

See Also

Dictionary Object


Dictionary.Value

The Value property allows you to get or set a name/value pair in the Dictionary.

Definition

Property Value(
bstrName As String
) As Variant

Parameters

bstrName

A String that contains the name of the Dictionary key for which to retrieve a value or put a value.

Error Values

This property sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' dDict is a Commerce.Dictionary object
' first_name is a Dictionary key
' v_first_name is a Variant
v_first_name = dDict.value("first_name")
v_first_name = dDict("first_name")

' use this form if the value contains an object reference:
Set oSubObject = dDict("myObjectKey")

' Property syntax
' Note: There is a slight performance penalty for using
' these forms because a special implementation of IDispatch is used
v_first_name = dDict.first_name
' If the key begins with an underscore then use braces around the key name
v_first_name = dDict.[_first_name]

See Also

Dictionary Object


DictionaryXMLTransforms Object

Use this object to transform data from a Dictionary object into Extensible Markup Language (XML) and vice-versa, using a specified XML Data Reduced (XDR) schema.

ProgID: | Commerce.DictionaryXMLTransforms (Externally creatable)
COM Class Name: | DictionaryXMLTransforms
Type Library Name: | Microsoft Commerce 2000 DictionaryXMLTransform Type Library
DLL Name: | DictionaryXMLTransforms.dll
Threading Model: | Apartment

Important

  • The DictionaryXMLTransforms object is only capable of processing dictionary keys with names that would be allowable as XML Node names. Allowable characters include A-Z and the underscore "_" character. Disallowed characters include"*", "\", etc., and foreign-language characters.

  • Every dictionary key value must be URL-encoded.

The methods of the DictionaryXMLTransforms object are shown in the following table.

Method | Description
GenerateSampleXMLInstanceFromDictionary | Produces an XML instance based on the specified Dictionary object.
GenerateXMLForDictionaryUsingSchema | Extracts an XML instance from the specified Dictionary object that conforms to the specified schema.
GetXMLFromFile | Generates an XML Document Object Model (DOM) document from the specified file.
ReconstructDictionaryFromXML | Transforms the specified XML instance (which must comply with the specified schema) into a Dictionary object.

Remarks

The example code that calls this method can be found in the payment.asp and _recvpo.asp files. An example of the use of a XML schema can be found in the POSchema.xml file in the Solution Sites.

See Also

General Purpose Objects

Dictionary Object


DictionaryXMLTransforms.GenerateSampleXMLInstanceFromDictionary

Use this method to generate an XML Data Reduced (XDR) schema. This method produces an XML instance based on the specified Dictionary object. You can then import this XML instance into a tool (such as the BizTalk Editor) that can construct a schema based on a given instance.

Definition

Function GenerateSampleXMLInstanceFromDictionary(
Dictionary As Object,
ElementName As String,
bIgnoreUnderScore As Boolean
) As Object

Parameters

Dictionary

A Dictionary object that contains the data to convert into XML.

ElementName

A String that contains the element name.

bIgnoreUnderScore

A Boolean that that specifies whether to ignore dictionary keys with leading underscores in the dictionary. This value should generally be set to True.

Return Values

If this method completes successfully, it returns an object reference used to return the XML instance.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oDictionaryXMLTransforms is a Commerce.DictionaryXMLTransforms object
' dDict is a Dictionary object; sElement is a string
' oXMLDOMNode is a XMLDOMNode object
oXMLDOMNode = _
oDictionaryXMLTransforms.GenerateSampleXMLInstanceFromDictionary(dDict, _
    sElement, TRUE)

See Also

DictionaryXMLTransforms Object


DictionaryXMLTransforms.GenerateXMLForDictionaryUsingSchema

Use this method to extract an XML instance from the specified Dictionary object that conforms to the specified schema.

Definition

Function GenerateXMLForDictionaryUsingSchema(
Dictionary As Object,
xmlSchema As Object
) As Object

Parameters

Dictionary

A Dictionary object that contains the data to be converted.

xmlSchema

An XMLDOMDocument object that contains the XML schema.

Return Values

If this method completes successfully, it returns an XMLDOMDocument object that contains the XML schema.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oDictionaryXMLTransforms is a Commerce.DictionaryXMLTransforms object
' dDict is a Dictionary object
' oXMLDOMDocument is a XMLDOMDocument object
' oXMLDOMNode is a XMLDOMNode object
oXMLDOMNode = _
oDictionaryXMLTransforms.GenerateXMLForDictionaryUsingSchema(dDict, _
    oXMLDOMDocument)

See Also

DictionaryXMLTransforms Object


DictionaryXMLTransforms.GetXMLFromFile

Use this method to generate a XML Document Object Model (DOM) document from the specified file.

Definition

Function GetXMLFromFile(
sFileName As String
) As Object

Parameters

sFileName

A String that contains the name of the file to convert.

Return Values

If this method completes successfully, it returns an object reference to an XMLDOMDocument object containing the converted file data.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oDictionaryXMLTransforms is a Commerce.DictionaryXMLTransforms object
' dDict is a Dictionary object; sMyFileName.txt is a string
' oXMLDOMDocument is a XMLDOMDocument object
oXMLDOMDocument = _
    oDictionaryXMLTransforms.GetXMLFromFile("sMyFileName.txt")

See Also

DictionaryXMLTransforms Object


DictionaryXMLTransforms.ReconstructDictionaryFromXML

Use this method to transform the specified XML instance (which must comply with the specified schema) into a Dictionary object. This method performs the inverse operation of the GenerateXMLForDictionaryUsingSchema method.

Definition

Function ReconstructDictionaryFromXML(
szDictionaryXML As String,
xmlSchema As Object
) As Object

Parameters

szDictionaryXML

A String that contains the XML instance.

xmlSchema

An object reference to a XMLDOMDocument object that contains the XML schema.

Return Values

If this method completes successfully, it returns an object reference to a Dictionary object that contains the converted data.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oDictionaryXMLTransforms is a Commerce.DictionaryXMLTransforms object
' dDict is a Dictionary object; sMyXMLInstance is a string
' oXMLDOMDocument is a XMLDOMDocument object
dDict = _
oDictionaryXMLTransforms.ReconstructDictionaryFromXML(sMyXMLInstance, _
    oXMLDOMDocument)

See Also

DictionaryXMLTransforms Object


EuroDisplay Object

Use this object to convert and format currency amounts where multiple currencies must be displayed.

ProgID: | Commerce.EuroDisplay (Externally creatable)
COM Class Name: | EuroDisplay
Type Library Name: | Microsoft Commerce 2000 Euro Display Component Type Library
DLL Name: | EuroDisp.dll
Threading Model: | Both

The methods of the EuroDisplay object are shown in the following table.

Method | Description
ConvertAltStringToCurr | Converts a string representation of a monetary value in the currency specified by the alternate locale identifier to a currency Variant.
ConvertBaseStringToCurr | Converts a string representation of a monetary value in the currency specified by the base locale identifier to a currency Variant.
ConvertMoney | Converts the specified currency Variant (representing a monetary value in the base currency) to a currency Variant representing a monetary value in the alternate currency, using the initialized conversion rate.
FormatAltMoney | Creates a string representation of a currency Variant, based on the alternate locale identifier and the alternate currency symbol string.
FormatBaseMoney | Creates a string representation of a currency Variant, based on the base locale identifier and the base currency symbol string.
Initialize | Initializes the object with the specified alternate currency symbol, base currency symbol, alternate locale identifier, base locale identifier, and conversion rate.

See Also

Display Objects


EuroDisplay.ConvertAltStringToCurr

Use this method to convert a string representation of a monetary value in the currency specified by the alternate locale identifier to a currency Variant.

Definition

Function ConvertAltStringToCurr(
vtMoneyString As Variant
) As Variant

Parameters

vtMoneyString

A Variant that contains the currency string to convert.

Return Values

If this method completes successfully, it returns a currency Variant that contains the converted currency information.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oEuroDisp is a Commerce.EuroDisplay object
' vResult is a Variant
vResult = oEuroDisp.ConvertAltStringToCurr("23,444.53886")
' In the preceding example, the variable vResult is
' internally rounded to 23444.5389

See Also

EuroDisplay Object

EuroDisplay.ConvertBaseStringToCurr

EuroDisplay.FormatAltMoney


EuroDisplay.ConvertBaseStringToCurr

Use this method to convert a string representation of a monetary value in the currency specified by the base locale identifier to a currency Variant.

Definition

Function ConvertBaseStringToCurr(
vtMoneyString As Variant
) As Variant

Parameters

vtMoneyString

A Variant that contains the currency string to convert.

Return Values

If this method completes successfully, it returns a currency Variant that contains the converted currency information.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oEuroDisp is a Commerce.EuroDisplay object
' vResult is a Variant
vResult = oEuroDisp.ConvertBaseStringToCurr("99,333.53886")
' In the preceding example, the variable vResult is
' internally rounded to 99333.5389

See Also

EuroDisplay Object

EuroDisplay.ConvertAltStringToCurr

EuroDisplay.FormatBaseMoney


EuroDisplay.ConvertMoney

Use this method to convert the specified currency Variant (representing a monetary value in the base currency) to a currency Variant representing a monetary value in the alternate currency, using the initialized conversion rate.

Definition

Function ConvertMoney(
vtCurrVal As Variant
) As Variant

Parameters

vtCurrVal

A Variant that contains the monetary value in the base currency.

Return Values

If this method completes successfully, it returns a currency Variant representing a monetary value in the alternate currency.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

<%
Dim Result
Set MSCSEuroDisplay= Server.CreateObject("Commerce.EuroDisplay")
MSCSEuroDisplay.Initialize "$$",1033,"FF",1036, 2
Result = MSCSEuroDisplay.ConvertMoney(100)
Response.Write "Converted $100 from $ to F ($1 = 2F) : " & Result & "<P>"
%>

See Also

EuroDisplay Object


EuroDisplay.FormatAltMoney

Use this method to create a string representation of a currency Variant, based on the alternate locale identifier and the alternate currency symbol string.

Definition

Function FormatAltMoney(
vtConvMoney As Variant
) As String

Parameters

vtConvMoney

A currency Variant that contains the monetary value to convert.

Return Values

If this method completes successfully, it returns a String that contains the string representation of the specified currency Variant.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oEuroDisp is a Commerce.EuroDisplay object
' vTest is a Currency Variant
' vResult is a String
vTest = "$ 20.00"
vResult = oEuroDisp.FormatAltMoney (vTest)
' In the preceding example, if the Alt Currency symbol string
' is "$" and the Alt locale identifier is 1033, vResult will
' contain the string, "$ 20.00"

See Also

EuroDisplay Object

EuroDisplay.ConvertAltStringToCurr

EuroDisplay.FormatBaseMoney


EuroDisplay.FormatBaseMoney

Use this method to create a string representation of a currency Variant, based on the base locale identifier and the base currency symbol string.

Definition

Function FormatBaseMoney(
vtConvMoney As Variant
) As String

Parameters

vtConvMoney

A currency Variant that contains the monetary value to convert.

Return Values

If this method completes successfully, it returns a String that contains the string representation of the specified currency Variant.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oEuroDisp is a Commerce.EuroDisplay object
' vTest is a Currency Variant
' vResult is a String
vTest = "$ 40.08"
vResult = oEuroDisp.FormatBaseMoney (vTest)
' In the preceding example, if the Base Currency symbol string
' is "$" and the Base locale identifier is 1033, vResult will
' contain the string, "$ 40.08"

See Also

EuroDisplay Object

EuroDisplay.ConvertBaseStringToCurr

EuroDisplay.FormatAltMoney


EuroDisplay.Initialize

Use this method to initialize the object with the specified alternate currency symbol, base currency symbol, alternate locale identifier, base locale identifier, and conversion rate.

Definition

Sub Initialize(
szBaseCurr As String,
lBaseLCID As Long,
szAltCurr As String,
lAltLCID As Long,
flEuroConvRate As Double
)

Parameters

szBaseCurr

A String that contains the base currency symbol string.

lBaseLCID

A Long that contains the base locale identifier.

szAltCurr

A String that contains the alternate currency symbol string.

lAltLCID

A Long that contains the alternate locale identifier.

flEuroConvRate

A Double (8-byte floating point number) that contains the rate at which to convert the base currency into the alternate currency. For example, if the base currency is Swiss Francs which are exchanged at a rate of 1 SF = 2.1 Euros, and the alternate currency is Euro then this parameter will have a value of 2.1.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oEuroDisp is a Commerce.EuroDisplay object
' In this example, the Base Currency symbol string
' is "$" and the Base locale identifier is 1033; the Alt
' Currency symbol string is "DM"; the Base locale identifier
'  is 1037, and the conversion rate is $ 1 = 2.3 DM.

oEuroDisp.Initialize"$", 1033, "DM", 1037, 2.3

See Also

EuroDisplay Object


ExpressionEval Object

Use this object to evaluate one or more expressions against a specified context. In addition, use this object to parse and evaluate user-defined expressions written as Extensible Markup Language (XML) fragments.

ProgID: | Commerce.ExpressionEvaluator (Externally creatable)
COM Class Name: | ExpressionEval
Type Library Name: | Microsoft Commerce 2000 Expression System Type Library
DLL Name: | exprarch.dll
Threading Model: | Both

The properties of the ExpressionEval object are shown in the following table.

Property | Type | Description
ExprCount | Long | Retrieves the number of expressions loaded into the expression cache. This property is read-only.

The methods of the ExpressionEval object are shown in the following table.

Method | Description
Connect | Establishes communication between the ExpressionEval object and an expression store.
CreateEvalContext | Creates a new ExprEvalContext object in the context cache.
Eval | Evaluates an expression.
EvalInContext | Evaluates an expression in a context previously loaded into the context cache.
EvalXML | Evaluates the specified XML text as an expression.
FlushAll | Removes all expressions from the expression cache.
FlushExpr | Removes the specified expression from the expression cache.
LoadAll | Reads all expressions from the expression store and loads them into the expression cache.
LoadExpr | Reads the specified expression from the expression store and loads it into the expression cache.
ParseXML | Parses the specified XML text to determine if it represents a valid expression.

Remarks

Expressions are stored in a database referred to as the Expression Store and accessed through an ExpressionStore object. When it is created, the ExpressionEval object initializes an expression cache and a context cache. Expressions must be compiled and loaded into the expression cache before being evaluated. To improve evaluation performance, use the LoadExpr or LoadAll method to preload expressions into the expression cache.

An expression is evaluated against data contained in a set of profiles. The profiles may be ProfileObject objects, Dictionary objects, or other objects that support property access through the IDispatch interface. The set of profiles is referred to as an evaluation context. If an evaluation context will be used across multiple expressions, create a stored context in the context cache using the CreateEvalContext method to increase efficiency.

The Connect method must be called before loading or evaluating expressions.

See Also

Expression Objects

Expression Recordset

Expression XML Structures

ExpressionStore Object

ProfileObject Object


ExpressionEval.Connect

Use this method to establish communication with an expression store.

Definition

Sub Connect(
vConnectInfo As Variant
)

Parameters

vConnectInfo

[in] A Variant that describes the expression store connection information. This may be a String containing the connection information or a reference to an existing ExpressionStore object.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_EXPR_BADCONNECTION | &H8110001F | Invalid connection
E_EXPR_BADEXPRSTORE | &H8110001E | Specified database does not contain a valid expression store
E_EXPR_NOCONNECTIONSTRING | &H8110000D | No connection string specified
E_EXPR_STOREPERMISSIONS | &H8110000F | Insufficient access permissions on the expression store database

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

If a connection string is passed as the input parameter, the ExpressionEval object creates an ExpressionStore object that uses the connection string to access the expression store. Upon destruction, the ExpressionEval object destroys the ExpressionStore object.

The connection string for the expression store may be obtained through the SiteConfigReadOnly object or through the Commerce Server Manager console from the s_BizDataStoreConnectionString property under the key "Commerce Server Manager\Global Resources\Profiles".

The Connect method must be used before loading or evaluating expressions.

The ParseXML method and the flush methods may be used without connecting to an expression store.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' Connect through an existing ExpressionStore object.

oExpressionEval.Connect oExpressionStore

' Connect using an explicit connection string.

oExpressionEval.Connect "Provider=SQLOLEDB;Data Source=server;" _
& "Initial Catalog=Retail_commerce;User ID=userID;Password=psswrd"

' Connect using a string retrieved from the SiteConfigReadOnly object.
' sConn is a String, oSCRO is an initialized SiteConfigReadOnly object.

sConn = oSCRO.Fields("Biz Data Service").Value _
 .Fields("s_BizDataStoreConnectionString").Value
oExpressionEval.Connect sConn

See Also

ExpressionEval Object

ExpressionStore Object

ExpressionStore.Connect

SiteConfigReadOnly Object


ExpressionEval.CreateEvalContext

Use this method to create a new ExprEvalContext object and place it into the context cache. This allows evaluation of multiple expressions against the same set of profile objects in the most efficient manner possible.

Definition

Function CreateEvalContext(
pDictObjs As Object
) As Object

Parameters

pDictObjs

[in] A Dictionary object that contains the set of profiles to be cached.

Return Values

If this method completes successfully, it returns the newly created ExprEvalContext object.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The CreateEvalContext method creates an ExprEvalContext object that uniquely identifies a new evaluation context and stores the object in the context cache. Use the EvalInContext method to evaluate multiple expressions within the context defined by the ExprEvalContext object. This process is more efficient than using the Eval method which generates and destroys a new context for each expression evaluated.

A context is a set of profiles containing data to evaluate expressions against. Profiles may be ProfileObject objects, Dictionary objects, or other objects that support property access through the IDispatch interface. Initially only references to the profile objects are held in the context cache. During evaluation, when property values are read from the profiles, the property values may themselves be held in the cache for faster access during subsequent evaluations.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Caution

  • The state of the profile objects should not be externally changed during the lifetime of the ExprEvalContext object; doing so leads to non-deterministic evaluation results.

Example

' dictUser1, dictAddress1, & dictProfiles are Dictionary objects
' create 2 profiles

dictUser1.firstName = "Joe"
dictUser1.lastName = "User"
dictAddress1.city = "Somewhere"
dictAddress1.state = "WA"

' add the profiles to the context Dictionary

dictProfiles.User = dictUser1
dictProfiles.Address = dictAddress1

' create the evaluation context

oExprEvalContext = oExpressionEval.CreateEvalContext(dictProfiles)

See Also

ExpressionEval Object

ExpressionEval.EvalInContext


ExpressionEval.Eval

Use this method to evaluate an expression.

Definition

Function Eval(
nExprID As Long,
pDictObjs As Object
) As Variant

Parameters

nExprID

[in] A Long that contains the unique identifier for the expression in the expression store.

pDictObjs

[in] A Dictionary object that contains a set of profiles.

Return Values

This method returns a Variant indicating the result of evaluating the expression in the specified context. The result may be True, False, or Nothing. Nothing indicates the expression could not be evaluated.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors, and the standard COM errors with special meanings, that this method can return.

Constant | Value | Description
E_EXPR_BADCONNECTION | &H8110001F | Invalid connection
E_EXPR_BADEXPRID | &H8110000A | Invalid expression ID specified
E_EXPR_NOCONNECTIONSTRING | &H8110000D | No connection string specified
E_EXPR_NOTFOUND | &H81100012 | Could not find the specified expression ID, nExprID, in the expression store

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Expressions must be pre-compiled and loaded into the expression cache before being evaluated. The Eval method first checks the expression cache for the expression, and if not found, loads the expression from the expression store. Use the LoadExpr or LoadAll method to preload an expression into the expression cache and improve evaluation performance.

An expression is evaluated against data contained in a set of profiles. This set of profiles is referred to as an evaluation context. A new evaluation context is generated by the Eval method using the Dictionary object. The Eval method discards the new context after completing the evaluation. This process is not efficient if many expressions must be evaluated against the same context.

If an evaluation context will be used across multiple expressions, create a context in the context cache using the CreateEvalContext method. Use the EvalInContext method to evaluate expressions in this new common context.

The Connect method must be called before using the Eval method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' dictUser1, dictAddress1, & dictProfiles are Dictionary objects
' create 2 profiles

dictUser1.firstName = "Joe"
dictUser1.lastName = "User"
dictAddress1.city = "Somewhere"
dictAddress1.state = "WA"

' add the profiles to the context Dictionary

dictProfiles.User = dictUser1
dictProfiles.Address = dictAddress1

' evaluate the expression, vResult is a Variant

vResult = oExpressionEval.Eval(2134, dictProfiles)

See Also

ExpressionEval Object

ExpressionEval.Connect

ExpressionEval.CreateEvalContext

ExpressionEval.EvalInContext

ExpressionEval.LoadExpr


ExpressionEval.EvalInContext

Use this method to evaluate an expression against a pre-established context stored in the context cache.

Definition

Function EvalInContext(
nExprID As Long,
pContext As Object
) As Variant

Parameters

nExprID

[in] A Long that contains the unique identification of the expression in the expression store.

pContext

[in] An ExprEvalContext object that identifies the specific context for this evaluation.

Return Values

This method returns a Variant indicating the results of evaluating the expression in the specified context. This result may be True, False, or Nothing. Nothing indicates the expression could not be evaluated.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors, and the standard COM errors with special meanings, that this method can return.

Constant | Value | Description
E_EXPR_BADCONNECTION | &H8110001F | Invalid connection
E_EXPR_BADEXPRID | &H8110000A | Invalid expression ID specified
E_EXPR_NOCONNECTIONSTRING | &H8110000D | No connection string specified
E_EXPR_MISSINGPROP | &H8110001D | Invalid ExprEvalContext object
E_EXPR_NOTFOUND | &H81100012 | Could not find the specified expression ID, nExprID, in the expression store

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The Eval method creates and discards an evaluation context for every evaluation. Evaluating against a stored context optimizes performance when multiple expressions need to be evaluated in the same context. Create the context for evaluation using the CreateEvalContext method.

Expression results are also stored in the context cache. If the result of a particular expression is requested multiple times from the same ExprEvalContext object using the EvalInContext method, the result is retrieved from the cache rather than by re-evaluating the expression, further increasing efficiency.

Caution

  • The state of the profile objects that comprise the context should not be externally changed during the lifetime of the ExprEvalContext object; doing so leads to non-deterministic evaluation results.

The Connect method must be called before using the EvalInContext method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oEvalContext is an ExprEvalContext object
' vResult is a Variant

vResult = oExpressionEval.Eval(2134, oEvalContext)

See Also

ExpressionEval Object

ExpressionEval.Connect

ExpressionEval.CreateEvalContext

ExpressionEval.Eval

ExpressionEval.LoadExpr


ExpressionEval.EvalXML

Use this method to evaluate an expression represented as an Extensible Markup Language (XML) fragment.

Definition

Function EvalXML(
bstrXMLExpr As String,
DictObjs As Object
) As Variant

Parameters

btrXMLExpr

[in] A String that contains the XML fragment to be evaluated.

DictObjs

[in] A Dictionary object that contains a set of profiles.

Return Values

This method returns a Variant indicating the results of evaluating the expression in the specified context. This result may be True, False, or Nothing. Nothing indicates the expression could not be evaluated.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_EXPR_BADARGTYPE | &H81100018 | Argument datatype information missing from expression, or unrecognized argument data type encountered in expression
E_EXPR_BADARGVALUE | &H81100022 | Invalid expression argument value, or impossible conversion
E_EXPR_BADCLAUSE | &H81100016 | Invalid clause encountered
E_EXPR_BADCONNECTION | &H8110001F | Invalid connection
E_EXPR_BADOPER | &H81100017 | Operator missing, unrecognized operator encountered, or type mismatch
E_EXPR_BADTERM | &H81100015 | Term type missing, or unrecognized term type encountered
E_EXPR_BADXML | &H81100014 | An unrecognized XML element was encountered
E_EXPR_NOCONNECTIONSTRING | &H8110000D | No connection string specified
E_EXPR_XMLPARSE | &H81100013 | XML DOM object parsing error

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The XML is parsed before being evaluated. For information on the XML format, see Expression XML Structures.

Expressions evaluated with the EvalXML method are not persistent; that is, they are not stored in the expression store or loaded into the expression cache. Use the Eval method to evaluate persistent expressions.

A new ExprEvalContext object is created and then discarded for each XML fragment that is evaluated.

The Connect method must be called before using the EvalXML method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' sXMLExpr is a string.
' Note that this string is not formatted properly with respect to
' quotation marks or continuation in order to increase readability.

strXMLExpr = "<CLAUSE OPER="equal">
                  <PROPERTY ID="User.firstName" TYPE="string" />
                  <IMMED-VAL TYPE="string">Jill</IMMED-VAL>
              </CLAUSE>"

' vResult is a Variant
' dictProfiles is a Dictionary object containing a set of profiles

vResult = oExpressionEval.EvalXML(sXMLExpr, dictProfiles)

See Also

Expression Recordset

Expression XML Structures

ExpressionEval Object

ExpressionEval.Connect

ExpressionEval.Eval

ExpressionEval.ParseXML


ExpressionEval.ExprCount

The ExprCount property is a read-only integer that indicates the number of expressions that correctly pre-compiled and loaded into the expression cache. Expressions that contain syntactic errors will fail to pre-compile correctly.

Definition

Property ExprCount As Long

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

See Also

ExpressionEval Object

ExpressionEval.FlushAll

ExpressionEval.FlushExpr

ExpressionEval.LoadAll

ExpressionEval.LoadExpr


ExpressionEval.FlushAll

Use this method to remove all expressions from the expression cache.

Definition

Sub FlushAll()

Parameters

None.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The FlushAll method removes all expressions from the expression cache and resets the read-only ExprCount property to zero (0).

Use the FlushExpr method to remove a specific expression from the expression cache.

See Also

ExpressionEval Object

ExpressionEval.ExprCount

ExpressionEval.FlushExpr

ExpressionEval.LoadAll

ExpressionEval.LoadExpr


ExpressionEval.FlushExpr

Use this method to remove the specified expression from the expression cache.

Definition

Sub FlushExpr(
nExprID As Long
)

Parameters

nExprID

[in] A Long that contains the identifier of the expression to be removed from the expression cache.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_EXPR_BADEXPRID | &H8110000A | Invalid expression ID specified

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The FlushExpr method removes the specified expression from the expression cache and decrements the read-only ExprCount property by one (1).

Use the FlushAll method to remove all expressions from the expression cache.

See Also

ExpressionEval Object

ExpressionEval.ExprCount

ExpressionEval.FlushAll

ExpressionEval.LoadAll

ExpressionEval.LoadExpr


ExpressionEval.LoadAll

Use this method to pre-compile all expressions in the expression store. Each expression that pre-compiles correctly is loaded into the expression cache.

Definition

Sub LoadAll()

Parameters

None.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_EXPR_BADARGTYPE | &H81100018 | Argument datatype infomation missing from expression, or unrecognized argument data type encountered in expression
E_EXPR_BADARGVALUE | &H81100022 | Invalid expression argument value, or impossible conversion
E_EXPR_BADCLAUSE | &H81100016 | Invalid clause encountered
E_EXPR_BADCONNECTION | &H8110001F | Invalid connection
E_EXPR_BADOPER | &H81100017 | Operator missing, unrecognized operator encountered, or type mismatch
E_EXPR_BADTERM | &H81100015 | Term type missing, or unrecognized term type encountered
E_EXPR_BADXML | &H81100014 | An unrecognized XML element was encountered
E_EXPR_NOCONNECTIONSTRING | &H8110000D | No connection string specified
E_EXPR_XMLPARSE | &H81100013 | XML DOM object parsing error

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Any expressions in the expression cache at the time of the call are reloaded.

If there are many expressions in the expression store, the LoadAll method may be slow. Use the LoadExpr method to load only specific expressions into the expression cache.

For every expression loaded into the expression cache, the LoadAll method increments the read-only ExprCount property by one (1).

Use the FlushAll method to remove all expressions from the expression cache.

The Connect method must be called before using the LoadAll method.

See Also

ExpressionEval Object

ExpressionEval.Connect

ExpressionEval.ExprCount

ExpressionEval.FlushAll

ExpressionEval.FlushExpr

ExpressionEval.LoadExpr


ExpressionEval.LoadExpr

Use this method to pre-compile an expression, and if successful, load the expression into the expression cache.

Definition

Sub LoadExpr(
nExprID As Long
)

Parameters

nExprID

[in] A positive Long that contains the identifier of the expression to load into the expression cache.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_EXPR_BADARGTYPE | &H81100018 | Argument datatype info missing from expression, or unrecognized argument data type encountered in expression
E_EXPR_BADARGVALUE | &H81100022 | Invalid expression argument value, or impossible conversion
E_EXPR_BADCLAUSE | &H81100016 | Invalid clause encountered
E_EXPR_BADCONNECTION | &H8110001F | Invalid connection
E_EXPR_BADEXPRID | &H8110000A | Invalid expression ID specified
E_EXPR_BADOPER | &H81100017 | Operator missing, unrecognized operator encountered, or type mismatch
E_EXPR_BADTERM | &H81100015 | Term type missing, or unrecognized term type encountered
E_EXPR_BADXML | &H81100014 | An unrecognized XML element was encountered
E_EXPR_NOCONNECTIONSTRING | &H8110000D | No connection string specified
E_EXPR_NOTFOUND | &H81100012 | Could not find the specified expression ID, nExprID, in the expression store
E_EXPR_XMLPARSE | &H81100013 | XML DOM object parsing error

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

If the specified expression is already loaded in the expression cache at the time of the call, it will be reloaded.

The LoadExpr method increments the read-only ExprCount property by one when it loads an expression into the expression cache.

With the exception of XML fragments, only expressions that exist in the expression cache may be evaluated. The Eval method loads an expression from the expression store that is not preloaded into the expression cache.

Use the LoadAll method to load all expressions into the expression cache. Use the FlushExpr method to remove an expression from the expression cache.

The Connect method must be called before using the LoadExpr method.

See Also

ExpressionEval Object

ExpressionEval.Connect

ExpressionEval.ExprCount

ExpressionEval.FlushAll

ExpressionEval.FlushExpr

ExpressionEval.LoadAll


ExpressionEval.ParseXML

Use this method to check whether an Extensible Markup Language (XML) fragment is a syntactically correct expression.

Definition

Function ParseXML(
bstrXMLExpr As String
) As Boolean

Parameters

bstrXMLExpr

[in] A String that contains the XML text defining an expression.

Return Values

This method returns a Boolean value indicating the results of parsing the expression (bstrXMLExpr).

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_EXPR_BADARGTYPE | &H81100018 | Argument datatype information missing from expression, or unrecognized argument data type encountered in expression
E_EXPR_BADARGVALUE | &H81100022 | Invalid expression argument value, or impossible conversion
E_EXPR_BADCLAUSE | &H81100016 | Invalid clause encountered
E_EXPR_BADOPER | &H81100017 | Operator missing, unrecognized operator encountered, or type mismatch
E_EXPR_BADTERM | &H81100015 | Term type missing, or unrecognized term type encountered
E_EXPR_BADXML | &H81100014 | An unrecognized XML element was encountered
E_EXPR_XMLPARSE | &H81100013 | XML DOM object parsing error

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Since this method only checks syntax, the expression may still be invalid even though the method succeeds.

The expression store is not used for XML fragments.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' sXMLExpr is a string.
' Note that this string is not formatted properly with respect to
' quotation marks or continuation in order to increase readability.

strXMLExpr = "<CLAUSE OPER="equal">
                  <PROPERTY ID="User.firstName" TYPE="string" />
                  <IMMED-VAL TYPE="string">Jill</IMMED-VAL>
              </CLAUSE>"

' bResult is a Boolean

bResult = oExpressionEval.ParseXML(sXMLExpr)

See Also

Expression Recordset

Expression XML Structures

ExpressionEval Object

ExpressionEval.Eval

ExpressionEval.EvalXML


ExpressionStore Object

Use this object to manipulate expressions contained in an expression store. An expression store is a database of expressions along with information about the expressions. There is one expression store for each commerce site.

ProgID: | Commerce.ExpressionStore (Externally creatable)
COM Class Name: | ExpressionStore
Type Library Name: | Microsoft Commerce 2000 Expression System Type Library
DLL Name: | exprarch.dll
Threading Model: | Both

The methods of the ExpressionStore object are shown in the following table.

Method | Description
Connect | Validates and stores the connection string to the specified expression store.
DeleteExpression | Deletes an expression from the expression store.
Disconnect | Sets the connection string to an empty string.
Export | Exports expressions from the expression store to a file.
GetAllExprs | Retrieves all expressions from the expression store.
GetExpression | Retrieves an expression from the expression store.
GetExprID | Translates an expression name into its corresponding expression ID.
GetExprName | Translates an expression ID into its corresponding expression name.
Import | Imports a set of expressions to the expression store from a file.
NewExpression | Creates a new ADO Recordset object that contains an empty expression.
Query | Queries for a list of expressions based on one or more criteria.
RenameExpression | Renames an existing expression.
SaveExpression | Saves a new or changed expression to the expression store.

Remarks

The connection string to a valid expression store must be stored using the Connect method before calling any other method of the ExpressionStore object.

An ExpressionStore object is internally created when the Connect method of an ExpressionEval object is invoked.

See Also

Expression Objects

Expression Recordset

Expression XML Structures

ExpressionEval Object


ExpressionStore.Connect

Use this method to store the connection string to an expression store.

Definition

Sub Connect(
strConnStr As String
)

Parameters

strConnStr

[in] A String that contains the database connection information for the expression store.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_EXPR_BADCONNECTION | &H8110001F | Invalid connection
E_EXPR_BADEXPRSTORE | &H8110001E | Specified database does not contain a valid expression store
E_EXPR_NOCONNECTIONSTRING | &H8110000D | No connection string specified
E_EXPR_STOREPERMISSIONS | &H8110000F | Insufficient access permissions on the expression store database

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The ExpressionStore object does not maintain a persistent ADO connection. This method stores the connection string after validating that the connection string points to an actual expression store. The Disconnect method sets the connection string to an empty string.

Each method of the ExpressionStore object creates a connection when needed, and when done with it, closes the connection. This relies on ADO connection pooling and provides higher availability.

The connection string for the expression store may be obtained through the SiteConfigReadOnly object or through the Commerce Server Manager console from the s_BizDataStoreConnectionString property under the key "Commerce Server Manager\Global Resources\Profiles".

The Connect method must be successfully executed before calling any other method of an externally created ExpressionStore object.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' Connect using an explicit connection string .
' oExpressionStore is a valid ExpressionStore object

oExpressionStore.Connect "Provider=SQLOLEDB;Data Source=server;" _
& "Initial Catalog=Retail_commerce;User ID=userID;Password=psswrd"

' Connect using a string retrieved from the SiteConfigReadOnly object.
' sConn is a String, oSCRO is an initialized SiteConfigReadOnly object.

sConn = oSCRO.Fields("Biz Data Service") _
.Value.Fields("s_BizDataStoreConnectionString").Value
oExpressionStore.Connect sConn

See Also

ExpressionStore Object

ExpressionStore.Disconnect

SiteConfigReadOnly Object


ExpressionStore.DeleteExpression

Use this method to delete an existing expression from the expression store.

Definition

Sub DeleteExpression(
nExprID As Long,
flags As Long
)

Parameters

nExprID

[in] A Long that specifies the expression to be deleted.

flags

[in] A Long that contains the optional control flags. This parameter is currently unused and should be set to zero (0).

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_EXPR_BADCONNECTION | &H8110001F | Invalid connection
E_EXPR_BADEXPRID | &H8110000A | Invalid expression ID specified, or expression ID not found in store
E_EXPR_EXPRDELFAILED | &H81100010 | Delete operation failed, possibly due to other expressions having dependencies on this expression
E_EXPR_NOCONNECTIONSTRING | &H8110000D | No connection string specified

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

If the specified expression has a non-zero reference count, meaning that other expressions depend on the specified expression, the expression is not deleted.

Call the Connect method before calling the DeleteExpression method.

Example

' oExpressionStore is an ExpressionStore object connected to
' a valid expression store.
' 59552 is a valid expression ID retrieved by the GetExprID method.

oExpressionStore.Delete(59552, 0)

See Also

ExpressionStore Object

ExpressionStore.Connect

ExpressionStore.NewExpression


ExpressionStore.Disconnect

Use this method to set the connection string to the expression store to an empty string.

Definition

Sub Disconnect()

Parameters

None.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about connecting and disconnecting to an expression store, see ExpressionStore.Connect

See Also

ExpressionStore Object


ExpressionStore.Export

Use this method to export the expressions stored in the expression store to a file.

Definition

Sub Export(
bstrFileName As String
)

Parameters

bstrFileName

[in] A String that contains the name of the file used to store the expressions.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_EXPR_BADCONNECTION | &H8110001F | Invalid connection
E_EXPR_NOCONNECTIONSTRING | &H8110000D | No connection string specified

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The file being exported to should not exist prior to the call or the method will fail. If an absolute path is not specified, the file is placed in the \WINNT\system32 folder.

After the method successfully completes, the file contains the XML schema for the expression recordset followed by the XML representation of each expression recordset in the expression store.

Use the Import method to copy the expressions in a file to the expression store.

Call the Connect method before calling the Export method.

Example

' oExpressionStore is an ExpressionStore object connected to
' a valid expression store.

oExpressionStore.Export "Expressions.xml"

See Also

Expression Recordset

Expression XML Structures

ExpressionStore Object

ExpressionStore.Import


ExpressionStore.GetAllExprs

Use this method to retrieve an ADO hierarchical Recordset object that contains all the expressions residing in the expression store.

Definition

Function GetAllExprs() As Object

Parameters

None.

Return Values

This method returns an ADO hierarchical Recordset object. If successful, the Recordset object contains the expressions currently residing in the expression store. If unsuccessful, the Recordset object is set to Nothing.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_EXPR_BADCONNECTION | &H8110001F | Invalid connection
E_EXPR_NOCONNECTIONSTRING | &H8110000D | No connection string specified

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The Recordset object contains one record for each expression in the expression store. For information on the format and fields of the Recordset object, see Expression Recordset.

Use the GetExpression method to retrieve a single expression from the expression store.

Call the Connect method before calling the GetAllExprs method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ExpressionStore Object

ExpressionStore.Connect

ExpressionStore.GetExpression


ExpressionStore.GetExpression

Use this method to retrieve an ADO hierarchical Recordset object that contains the specified expression.

Definition

Function GetExpression(
nExprID As Long
) As Object

Parameters

nExprID

[in] A Long that contains the unique identifier of the expression.

Return Values

This method returns an ADO hierarchical Recordset object. If successful, the Recordset object contains the specified expression. If unsuccessful, the Recordset object is set to Nothing.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_EXPR_BADCONNECTION | &H8110001F | Invalid connection
E_EXPR_BADEXPRID | &H8110000A | Invalid expression ID specified, or expression ID not found in store
E_EXPR_NOCONNECTIONSTRING | &H8110000D | No connection string specified

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

To access all expressions in the connected expression store, use the GetAllExprs method.

Call the Connect method before calling the GetExpression method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Expression Recordset

ExpressionStore Object

ExpressionStore.Connect

ExpressionStore.GetAllExprs

ExpressionStore.NewExpression


ExpressionStore.GetExprID

Use this method to translate the name of an expression into its corresponding expression ID.

Definition

Function GetExprID(
strExprName As String
) As Long

Parameters

strExprName

[in] A String that contains the expression name.

Return Values

If this method completes successfully, it returns a Long that contains the expression ID. On failure, the expression ID is set to EXPRID_INVALID (defined as -1).

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_EXPR_BADCONNECTION | &H8110001F | Invalid connection
E_EXPR_BADEXPRNAME | &H81100003 | Invalid expression name, or expression name not found in store
E_EXPR_NOCONNECTIONSTRING | &H8110000D | No connection string specified

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Use the GetExprName method to translate the ID of an expression into its corresponding expression name.

Call the Connect method before calling the GetExprID method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' lExpressionID is a long
' oExpressionStore is an ExpressionStore object connected to
' a valid expression store.

lExpressionID = oExpressionStore.GetExprID("MyExpression")

See Also

ExpressionStore Object

ExpressionStore.Connect

ExpressionStore.GetExpression

ExpressionStore.GetExprName

ExpressionStore.RenameExpression


ExpressionStore.GetExprName

Use this method to translate the ID of an expression into its corresponding expression name.

Definition

Function GetExprName(
nExprID As Long
) As String

Parameters

nExprID

[in] A Long that contains a unique expression ID.

Return Values

If this method completes successfully, it returns a String that contains the name of the expression. An empty String is returned if the expression ID is a Long but does not represent an existing expression.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_EXPR_BADCONNECTION | &H8110001F | Invalid connection
E_EXPR_BADEXPRID | &H8110000A | Invalid expression ID specified, or expression ID not found in store
E_EXPR_NOCONNECTIONSTRING | &H8110000D | No connection string specified

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Use the GetExprID method to translate the name of an expression into its corresponding expression ID.

Call the Connect method before calling the GerExprName method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ExpressionStore Object

ExpressionStore.Connect

ExpressionStore.GetExprID


ExpressionStore.Import

Use this method to import expressions from a file into the expression store.

Definition

Sub Import(
bstrFileName As String
)

Parameters

bstrFileName

[in] A String that contains the path and name of the file from which to import the expressions.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_EXPR_BADCONNECTION | &H8110001F | Invalid connection
E_EXPR_NOCONNECTIONSTRING | &H8110000D | No connection string specified
E_EXPR_NONEMPTYSTORE | &H8110000C | Cannot import to a non-empty store

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The expression store must be empty in order to import expressions.

The import file must contain the XML schema for the expression recordset followed by the XML representation of each expression recordset. Expression recordsets with invalid expression bodies are imported but will cause an error upon evaluation.

Use the Export method to copy the XML schema for the expression recordset and all the expressions from the expression store to a file.

Call the Connect method before calling the Import method.

Example

' oExpressionStore is an ExpressionStore object connected to
' a valid expression store.

oExpressionStore.Import "\SomePath\Expressions.xml"

See Also

Expression Recordset

Expression XML Structures

ExpressionStore Object

ExpressionStore.Export


ExpressionStore.NewExpression

Use this method to return an ADO hierarchical Recordset object that contains an empty expression.

Definition

Function NewExpression() As Object

Parameters

None.

Return Values

If this method completes successfully, it returns a hierarchical Recordset object that contains an empty expression.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_EXPR_BADCONNECTION | &H8110001F | Invalid connection
E_EXPR_NOCONNECTIONSTRING | &H8110000D | No connection string specified

Remarks

Populate the returned Recordset object with data describing the new expression. For information on the format and required fields of the Recordset object, see Expression Recordset.

Save the newly defined expression to the expression store using the SaveExpression method. The SaveExpression method automatically generates a new, unique expression ID and stores it with the new expression.

Call the Connect method before calling the NewExpression method.

See Also

ExpressionStore Object

ExpressionStore.Connect

ExpressionStore.SaveExpression


ExpressionStore.Query

Use this method to retrieve a Recordset object containing expressions that match the specified query conditions. At least one of the optional arguments must be specified.

Definition

Function Query(
Optional vName As Variant,
Optional vCategory As Variant,
Optional vProfiles As Variant
) As Object

Parameters

vName

[in, optional] When specified, a String name to match expressions against. This is used in an SQL LIKE clause that permits wildcards.

vCategory

[in, optional] When specified, a String containing the category or SAFEARRAY of category strings to match expressions against. This is used in an SQL LIKE clause that permits wildcards.

vProfiles

[in, optional] When specified, a String containing the profile name or SAFEARRAY of profile names to match expressions against. Profile names must be specified without wildcards.

Return Values

This method returns an ADO hierarchical Recordset object. If successful, the Recordset object contains the result set of expressions. If unsuccessful, the Recordset object is set to Nothing.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_EXPR_BADCONNECTION | &H8110001F | Invalid connection
E_EXPR_NOCONNECTIONSTRING | &H8110000D | No connection string specified

Remarks

If a combination of the optional parameters is specified, the retrieved expressions satisfy all constraints (implicit AND applied). For example, if name = "Robert%" and category = "General", only expressions with names starting with "Robert" and with a category of "General" will be returned.

When multiple profile names are specified, the query result includes expressions with profile requirements (dependencies) that include any of the listed profile names (implicit OR applied). Thus, if name = "Robert%" and the profiles "User" and "Context" are specified as profiles, the Query method will return all expressions with names starting with "Robert" and profiles requiring only "User", only "Context", or both "User" and "Context".

For details on the ADO Recordset object that represents the expression, see Expression Recordset.

Call the Connect method before calling the Query method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oExpressionStore is an ExpressionStore object connected to
' a valid expression store.
' rsExpr is a Recordset object that will contain all expressions
' with a name starting with 'Express', having a category of
' Octogenarians' and a profile dependency on 'joeuser'.

rsExpr = oExpressionStore.Query("Express%", "Octogenarians", "joeuser")

See Also

ExpressionStore Object

ExpressionStore.Connect


ExpressionStore.RenameExpression

Use this method to rename an existing expression in the expression store. The new expression name must be unique or the operation will fail.

Definition

Sub RenameExpression(
nExprID As Long,
strNewName As String
)

Parameters

nExprID

[in] A Long that contains the expression ID.

strNewName

[in] A String that contains the new name.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_EXPR_BADCONNECTION | &H8110001F | Invalid connection
E_EXPR_BADEXPRID | &H8110000A | Invalid expression ID specified, or expression ID not found in store
E_EXPR_BADEXPRNAME | &H81100003 | Invalid expression name
E_EXPR_DUPEXPRNAME | &H81100007 | Duplicate expression name
E_EXPR_INVALIDFIELDSIZE | &H81100005 | The new name exceeds the maximum size of 30 characters
E_EXPR_NOCONNECTIONSTRING | &H8110000D | No connection string specified

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Use the GetExprID method to translate an expression name to its corresponding expression ID.

Call the Connect method before calling the RenameExpression method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oExpressionStore is an ExpressionStore object connected to
' a valid expression store.
' 52997 is a valid expression ID retrieved from the GetExprId method.

oExpressionStore.RenameExpression(52997, "MyNewName")

See Also

ExpressionStore Object

ExpressionStore.Connect

ExpressionStore.GetExprID


ExpressionStore.SaveExpression

Use this method to save a new or modified expression to the expression store. For a new expression, the SaveExpression method automatically generates a unique expression ID and stores it with the expression.

Definition

Sub SaveExpression(
pRSExpr As Object
)

Parameters

pRSExpr

[in] A Recordset object that contains the expression.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_EXPR_BADCONNECTION | &H8110001F | Invalid connection
E_EXPR_BADEXPRBODY | &H81100004 | Invalid or missing expression body
E_EXPR_BADEXPRCATEGORY | &H8110000A | Invalid expression category specified
E_EXPR_BADEXPRNAME | &H81100003 | Invalid expression name
E_EXPR_CYCLEDETECTED | &H81100006 | A cycle was detected in the expression dependencies of this expression
E_EXPR_DUPEXPRDEPS | &H81100009 | Duplicate expression dependency
E_EXPR_DUPEXPRNAME | &H81100007 | Duplicate expression name
E_EXPR_DUPPROFDEPS | &H81100008 | Duplicate profile dependency
E_EXPR_INVALIDEXPRDEPS | &H8110000B | One or more of the expression dependencies refers to an expression ID that does not exist
E_EXPR_INVALIDFIELDSIZE | &H81100005 | The new name exceeds the maximum size of 30 characters
E_EXPR_NOCONNECTIONSTRING | &H8110000D | No connection string specified
E_EXPR_NOPROFDEPS | &H81100002 | Expression must have at least one profile-dependency to be saved

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

If the expression being saved is not currently in the expression store, the SaveExpression method generates a unique identifier and populates the ExprID field of the Recordset object. The identifier is a positive integer. For more information about the format and fields of the Recordset object, see Expression Recordset.

The ExpressionStore object performs rudimentary checks for expression dependencies when an expression is saved or deleted. This includes any direct references, a test for cyclic referencing, and any references to non-existent expressions.

Call the Connect method before calling the SaveExpression method.

See Also

ExpressionStore Object

ExpressionStore.Connect

ExpressionStore.GetExpression

ExpressionStore.NewExpression


Expression Recordset

An expression is a statement constructed with Boolean and relational operators that is evaluated against the data in a given set of profiles. The part of an expression that is evaluated is stored as an Extended Markup Language (XML) string in the ExprBody field of an ActiveX Data Object (ADO) Recordset object. Recordset objects are contained in a database known as the Expression Store.

This section contains:

  • Expression Recordset Object. Describes the ADO hierarchical Recordset object that represents the expression.

  • Expression Recordset Example. Shows an example of an expression Recordset object.

See Also

Expression Objects

Expression XML Structures

ExpressionEval Object

ExpressionStore Object


Expression Recordset Object

The ExpressionStore object represents expressions and their dependencies using an ADO shaped hierarchical Recordset object. The structure of this Recordset object consists of a parent Recordset object with pointers to two child Recordset objects.

An empty Recordset object with the prescribed structure is created by calling the NewExpression method of the ExpressionStore object. Once the fields of the Recordset object have been filled in, the SaveExpression method is used to commit the expression to the expression store. In a similar fashion, those methods of the ExpressionStore object that return expressions from the store, such as GetExpression and GetAllExprs, return the expression data in this hierarchical Recordset object structure.

Parent Recordset

The fields in the parent Recordset object are shown in the following table.

Field | Type | Requirement | Description
ExprID | Integer | Generated by the SaveExpression method of the ExpressionStore object when a new expression is saved. | Unique identifier for the expression. This is a positive integer.
ExprName | String | Required field supplied by the user. | Unique name of the expression. The following characters are not allowed: ', ", &, \, /, <, >
Category | String | Optional field supplied by the user. | Category of the expression. May be used as a filter. The following characters are not allowed: ', ", &, \, /, <, >
ExprDesc | String | Optional field supplied by the user. | Description of the expression. Maximum length is 200 characters. The following characters are not allowed: &, <, >
ExprBody | String | Required field supplied by the user. | Extensible Markup Language (XML) body of the recordset. The evaluable expression. Maximum length is 3400 characters. For more information, see Expression XML Structures.
DateCreated | Date | Generated by the system. | Date the recordset was created.
DateModified | Date | Generated by the system. | Date the recordset was last modified.
rsExprDeps | Recordset pointer | Generated by the system. | A pointer to the child Recordset object listing the expression dependencies of this expression.
rsProfDeps | Recordset pointer | Generated by the system. | A pointer to the child Recordset object listing the profile type dependencies of this expression.

Expression Dependencies Child Recordset

This Recordset object contains a record for each expression that the parent expression is immediately dependent on. The information does not include nested dependencies. If the parent expression does not depend on any expressions, this recordset may be empty.

The fields in the expression dependencies child Recordset object are shown in the following table.

Field | Type | Description
ExprID | Integer | Identifier of the parent expression.
ExprDep | Integer | Identifier of the dependent expression.

Profile Dependencies Child Recordset

This Recordset object contains a record for each profile this expression is dependent on. The user must populate at least one record when creating a new expression.

The fields in the profile dependencies Recordset object are shown in the following table.

Field | Type | Description
ExprID | Integer | Identifier of the parent expression.
ProfDep | String | Name of the dependent profile.

Remarks

The ExprId fields of the two child Recordset objects contain the same value as the ExprID field of the parent Recordset object that is generated when a new expression is saved.


Expression Recordset Example

The following examples shows two Recordset objects containing expressions. The first is for an expression (ID = 7) dependent on one profile (User) and no expressions. The second is for an expression (ID = 24) dependent on one other expression (ID=7) and two hypothetical profiles (Product and User). The DateCreated, DateModified, rsExprDeps, and rsProfDeps fields are not shown.

Parent Recordset for Expression7

ExprID | ExprName | Category | ExprDesc | ExprBody
7 | "Expression7" | "Hair" | "Bald_people" | String7

Expression Dependencies Child Recordset for Expression7

ExprID | ExprDep

Profile Dependencies Child Recordset for Expression7

ExprID | ProfDep
7 | "User"

String7 = "<CLAUSE OPER="is-true">
             <PROPERTY ID="User.GeneralInfo.hair" TYPE="string"/>
             <IMMED-VAL TYPE="string">bald</IMMED-VAL>
           </CLAUSE>"

Parent Recordset for Expression24

ExprID | ExprName | Category | ExprDesc | ExprBody
24 | "Expression24" | "FeralOctogenarians" | "Bald_ginseng_users_over_80" | String24

Expression Dependencies Child Recordset for Expression24

ExprID | ExprDep
24 | 7

Profile Dependencies Child Recordset for Expression24

ExprID | ProfDep
24 | "Product"
24 | "User"

String24 = "<TERM TYPE="and">
              <CLAUSE OPER="is-true">
                <EXPR-REF ID=7/>
              </CLAUSE>
              <CLAUSE OPER="equal">
                <PROPERTY ID="Product.name" TYPE="string"/>
                <IMMED-VAL TYPE="string">ginseng</IMMED-VAL>
              </CLAUSE>
              <CLAUSE OPER="at-least">
                <PROPERTY ID="User.GeneralInfo.age" TYPE="number"/>
                <IMMED-VAL TYPE="number">80</IMMED-VAL>
              </CLAUSE>
            </TERM>"


ExprEvalContext Object

This object is created by the CreateEvalContext method of the ExpressionEval object. It is used to store a common context for evaluating multiple expressions. ExprEvalContext objects are stored in the context cache by the ExpressionEval object and deleted when the ExpressionEval object is destroyed.

Since the ExprEvalContext object is intended to be accessed solely through the ExpressionEval object, no documentation of the properties and methods of the ExprEvalContext object is provided.

Caution

  • Do not attempt to change any values internal to the ExprEvalContext object. Changing these values will corrupt the object and render it invalid. Use only the methods of the ExpressionEval object to create, access, and delete the ExprEvalContext object.

See Also

Expression Objects

ExpressionEval Object


ExprFltrQueryBldr Object

Use this object to translate an expression in Extensible Markup Language (XML) form into a SQL filter query string. A filter query returns a subset of items from a database based on a combination of attribute values.

ProgID: | Commerce.ExprFltrQueryBldr (Externally creatable)
COM Class Name: | ExprFltrQueryBldr
Type Library Name: | Microsoft Commerce 2000 Expression Builder Type Library
DLL Name: | exprfltrbldr.dll
Threading Model: | Apartment

The methods of the ExprFltrQueryBldr object are shown in the following table.

Method | Description
ConvertExprToSqlFltrStr | Converts an expression in XML form to a SQL filter string.
ConvertExprUsingDict | Converts an expression in XML form that references a Dictionary object into a SQL filter string.

Remarks

The expression in XML form may contain a reference to a Dictionary object.

See Also

Expression XML Structures


ExprFltrQueryBldr.ConvertExprToSqlFltrStr

Use this method to convert an expression in Extensible Markup Language (XML) form to a SQL filter query string.

Definition

Function ConvertExprToSqlFltrStr(
pExpression As String
) As String

Parameters

pExpression

A String that contains the expression in XML form.

Return Values

If this method completes successfully, it returns a String that contains the SQL filter string.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' sXMLExpr and sSqlFilter are Strings.
' Note that the sXMLExpr string is not properly formatted with respect
' to quotation marks or continuation to increase readability.

sXMLExpr = "<CLAUSE OPER="at-least">
              <PROPERTY ID="user.age" TYPE="number"/>
              <IMMED-VAL TYPE="number">80</IMMED-VAL>
            </CLAUSE>"

sSqlFilter = oExprFltrQueryBldr.ConvertExprToSqlFltrStr(sXMLExpr)
' The resulting sSQLFilter string is: user.age >= 80.

See Also

ExprFltrQueryBldr Object


ExprFltrQueryBldr.ConvertExprUsingDict

Use this method to convert an expression in Extensible Markup Language (XML) form containing a reference to a Dictionary object into a SQL filter query string.

Definition

Function ConvertExprUsingDict(
pExpr As String,
pDict As Object
) As String

Parameters

pExpr

A String that contains the expression in XML form.

pDict

A Dictionary object that contains the values referenced by the expression.

Return Values

If this method completes successfully, it returns a String that contains the SQL filter string.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

In the XML expression, a reference to a Dictionary object is made by preceding the value inside the IMMED-VAL tags with the keyword 'context'. If such a reference is found during conversion of the expression, the reference is replaced with the value read from the Dictionary object.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ExprFltrQueryBldr Object


GenID Object

Use this object to generate globally unique identifiers (GUID), or to create and maintain multiple, global sequential counters that are persisted in a database. A global counter is one that can work across multiple computers.

ProgID: | Commerce.GenID (Externally creatable)
COM Class Name: | GenID
Type Library Name: | Microsoft Commerce 2000 GenID Type Library
DLL Name: | GenID.dll
Threading Model: | Both

The methods of the GenID object are shown in the following table.

Method | Description
GenBase5GUIDString | Generates a base5 GUID string.
GenGUIDString | Generates a GUID string.
GetCounterValue | Retrieves the value of the specified counter and then increments the counter.
Initialize | Connects the GenID object to the database that stores the table of counters.
InitializeCounter | Initializes a new counter or resets an existing counter.


GenID.GenBase5GUIDString

Use this method to generate a base5 Globally Unique Identifier (GUID) string.

Definition

Function GenBase5GUIDString() As String

Parameters

None.

Return Values

If this method completes successfully, it returns a String that contains the base5 GUID.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

A base5 GUID is used to store a slightly more compact version of the traditional GUID. The 128 binary digits are divided into groups of 5 instead of 4 with each group represented by the characters 0-9, and 22 characters of the alphabet. This results in a 26-digit representation for the GUID rather than the customary 32-digit representation.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

GenID Object


GenID.GenGUIDString

Use this method to generate a Globally Unique Identifier (GUID) string.

Definition

Function GenGUIDString() As String

Parameters

None.

Return Values

If this method completes successfully, it returns a String that contains the GUID.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

GenID Object


GenID.GetCounterValue

Use this method to retrieve and increment the value stored in the specified counter.

Definition

Function GetCounterValue(
bstrCounterName As String,
cDigits As Long
) As String

Parameters

bstrCounterName

A String that contains the counter name.

cDigits

A Long that contains the number of digits to return.

Return Values

If this method completes successfully, it returns a String that contains the counter value.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

After the current value of the counter is returned, the counter is incremented by one. Use the InitializeCounter method to reset the counter.

If the value of the counter is less than the number of digits requested, the value is left padded with zeroes.

The Initialize method must be called before calling the GetCounterValue method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' sCounterValue is a String
' oGenID is a Commerce GenID object
' The value stored in the counter is 285.

sCounterValue = oGenID.GetCounterValue("OrderIDCounter", 4)

' sCounterValue = 0285
' The value now stored in the OrderIDCounter is 286.

See Also

GenID Object


GenID.Initialize

Use this method to connect the GenID object to the database that stores the table of counters.

Definition

Sub Initialize(
bstrDBConnectionString As String,
Optional cBlockSizeHint As Long
)

Parameters

bstrDBConnectionString

A String that contains the connection information to the database.

cBlockSizeHint

Not implemented, leave blank.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

This method must be called before calling the GetCounterValue and InitializeCounter methods.

The connection string may be obtained through the SiteConfigReadOnly object or through the Commerce Server Manager console from the connstr_db_Transactions property under Commerce Server Manager\Commerce Sites\<site name>\Site Resources\Transactions.

Example

' oGenID is a Commerce GenID object

' Connect using an explicit connection string.

oGenID.Initialize "Provider=SQLOLEDB;Data Source=server;" _
 & "User ID=user;Password=psswrd;Initial Catalog=Retail_commerce"

' Connect using a string retrieved from the SiteConfigReadOnly object.
' sConn is a String, oSCRO is an initialized SiteConfigReadOnly object

sConn = oSCRO.Fields("Transactions").Value.Fields("connstr_db_Transactions").Value
oGenID.Initialize sConn

See Also

GenID Object


GenID.InitializeCounter

Use this method to create or reset a global, sequential counter.

Definition

Sub InitializeCounter(
bstrCounterName As String,
dwInitialValue As Long
)

Parameters

bstrCounterName

A String that contains the counter name.

dwInitialValue

A Long that contains the initial value of the counter.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Any number of counters may be created. If the counter already exists, its value is reset to the specified initial value.

A global counter will work across multiple computers.

The Initialize method must be called before calling the InitializeCounter method.

Example

' oGenID is a Commerce GenID object

oGenID.InitializeCounter("OrderCounter", 213)

See Also

GenID Object


GlobalConfig Object

Use this object to accomplish the following:

  • Create or delete resource configuration information

  • Save any updated global configuration information to the Administration database

  • Add a site

Depending on how you add your own custom resource, you should be able to use this object to access configuration settings from the Administration database.

ProgID: | Commerce.GlobalConfig (Externally creatable)
COM Class Name: | GlobalConfig
Type Library Name: | Microsoft Commerce 2000 Configuration Type Library
DLL Name: | MSCSCfg.dll
Threading Model: | Apartment

The single property of the GlobalConfig object is shown in the following table.

Property | Type | Description
Fields | Fields | Returns group-level configuration data. This property is read-only.

The methods of the GlobalConfig object are shown in the following table.

Method | Description
CreateServiceConfig | Creates and writes configuration information for the specified resource to the Administration database.
CreateSiteConfig | Creates a site.
DeleteServiceConfig | Deletes configuration information for the specified resource.
DeleteSiteConfig | Deletes the specified configuration for the site and all configurations for the associated resources.
GetIfCollection | Converts values read from the Fields property into appropriate objects such as a SimpleList object or a Variant Array.
GetResourcePropAttrib | Gets a dictionary of key/value pairs that denote the attributes of the specified property of the specified resource.
Initialize | Loads the global configuration data from the Administration database.
MakeArrayFromSimpleList | Converts the specified SimpleList object into an Array.
MakeArrayFromString | Converts values read from the Fields property into an Array.
MakeSimpleListFromArray | Converts an Array into a SimpleList object.
MakeStringFromArray | Converts an Array into an encoded string, which can be written to the Fields property.
MakeStringFromSimpleList | Converts a SimpleList object into an encoded string, which can be written to the Fields property.
SaveConfig | Saves the global configuration settings to the Administration database.
Sites | Returns a list of all of the sites available in the administration data store.

See Also

Integrating Custom Resources

Configuration Objects

SiteConfig Object

SiteConfigReadOnly Object


GlobalConfig.CreateServiceConfig

Use this method to create an instance of the class specified by the bstrConfigSchemaClass parameter, set the Name property of the instance to the name specified in the bstrServiceName parameter, and load the instance into the site recordset. This method calls the SaveConfig method.

Definition

Sub CreateServiceConfig(
bstrServiceName As String,
bstrConfigSchemaClass As String
)

Parameters

bstrServiceName

A String that contains the new name for the resource configuration object instance.

bstrConfigSchemaClass

A String that contains the resource configuration schema class name.

Return Values

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The Initialize method must be called before this method can be called.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

The following table contains a list of schema classes for this method.

Administration Database Class Name | Resource Name
MSCS_AuthManager | Site CS Authentication
MSCS_DirectMailer | Direct Mailer
MSCS_Predictor | Predictor
MSCS_Datawarehouse_Group | Global Data Warehouse
MSCS_BizDataStore | Profiles

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' sMyPredictor is a String denoting the new resource name
' oGlobalConfig is a Commerce GlobalConfig object
oGlobalConfig.CreateServiceConfig(sMyPredictor, MSCS_Predictor)

See Also

GlobalConfig Object

GlobalConfig.DeleteServiceConfig


GlobalConfig.CreateSiteConfig

Use this method to create a site using the name specified in the bstrSiteName parameter. This method calls the SaveConfig method. This method is used primarily from Commerce Server Manager or by Commerce Server Site Packager. The correct ACLs are set on the entries in the IIS metabase by the Commerce Server Site Packager, to ensure that the Admin objects can only be operated on by site administrators.

Definition

Function CreateSiteConfig(
bstrSiteName As String
) As Object

Parameters

bstrSiteName

A String that contains the new site name.

Return Values

If this method completes successfully, it returns a SiteConfig object that contains the site configuration settings.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The Initialize method must be called before this method can be called.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' sMyNewSite is a string; oGlobalConfig is a Commerce GlobalConfig object
' oMSCSSiteConfig is a Commerce.SiteConfig object
oMSCSSiteConfig = oGlobalConfig.CreateSiteConfig(sMyNewSite)

See Also

GlobalConfig Object

_GlobalConfig::DeleteSiteConfig


GlobalConfig.DeleteServiceConfig

Use this method to delete the specified resource, and to delete the Administration database association that links this resource to the site instance.

Definition

Sub DeleteServiceConfig(
bstrServiceName As String
)

Parameters

bstrServiceName

A String that contains the name of the resource configuration object to be deleted.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The Initialize method must be called before this method can be called.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' sMyPredictor is the name of an existing resource
' oGlobalConfig is a Commerce GlobalConfig object
oGlobalConfig.DeleteServiceConfig (sMyPredictor)

See Also

GlobalConfig Object

GlobalConfig.CreateServiceConfig


GlobalConfig.DeleteSiteConfig

Use this method to delete a site configuration object instance for the current site from the Administration database. This method is primarily used by Commerce Server Manager or by Commerce Server Site Packager.

Definition

Sub DeleteSiteConfig(
bstrSiteName As String
)

Parameters

bstrSiteName

A String that contains the site name.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The Initialize method must be called before this method can be called.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' sMySiteName is an existing site name
' oGlobalConfig is a Commerce GlobalConfig object
oGlobalConfig.DeleteSiteConfig(sMySiteName)

See Also

GlobalConfig Object

GlobalConfig.CreateServiceConfig


GlobalConfig.Fields

The Fields property is a read-only Fields object. The Fields property contents include recordsets that hold the configuration settings of resources. A Fields object is an ADO disconnected recordset.

Definition

Property Fields As Object

Parameters

None.

Error Values

This property sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The Initialize method must be called before this method can be called.

The pFields parameter contains valid data only if the property is accessed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

GlobalConfig Object


GlobalConfig.GetIfCollection

Use this method to convert values read from the Fields property into appropriate objects such as a SimpleList object or a Variant Array. If the encoding in the string contained in the Fields property indicates a SimpleList object, then a SimpleList object is returned. If the encoding indicates a Variant Array, then a Variant Array is returned. If no collection object is indicated, then the method returns the original encoded input string.

Definition

Function GetIfCollection(
strList As Variant
) As Variant

Parameters

strList

A Variant that contains the encoded string to be converted.

Return Values

If this method completes successfully, it returns a Variant containing the converted data in the appropriate data type.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' vVariant is a Variant; vEncodedString is a Variant
' oGlobalConfig is a Commerce GlobalConfig object
vVariant = oGlobalConfig.GetIfCollection(vEncodedString)

See Also

GlobalConfig Object


GlobalConfig.GetResourcePropAttrib

Use this method to get a dictionary of key/value pairs that denote the attributes of the specified property of the specified resource.

Definition

Function GetResourcePropAttrib(
strResourceName As String,
strPropName As String
) As Object

Parameters

strResourceName

A String that contains the resource name.

strPropName

A String that contains the resource property name.

Return Values

If this method completes successfully, it returns an object reference to a Dictionary object containing the key/value pairs that denote the attributes of the specified property of the specified resource.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The Initialize method must be called before this method can be called.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' dDict is a Dictionary object
' sMyCatalog is an existing resource
' connstr_desc_Catalog is a valid Catalog resource property
' oGlobalConfig is a Commerce GlobalConfig object
dDict = _
oGlobalConfig.GetResourcePropAttrib(sMyCatalog, connstr_desc_Catalog)

See Also

GlobalConfig Object


GlobalConfig.Initialize

Use this method to load the global configuration from the Administration database.

Definition

Sub Initialize(
Optional bstrGroupName As String
)

Parameters

bstrGroupName

A String reserved for future use. This method ignores the value placed in this parameter.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

GlobalConfig Object


GlobalConfig.MakeArrayFromSimpleList

Use this method to convert the specified SimpleList object into an Array.

Definition

Function MakeArrayFromSimpleList(
list As Object
) As Variant

Parameters

list

An object reference to the SimpleList that you wish to convert into an Array.

Return Values

If this method completes successfully, it returns a Variant containing the converted Array.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

Important

  • There is a special group of methods used with multivalued arrays. These methods are the only approved and recommended way of storing and retrieving multivalued arrays in the Administration database. You must use the following methods with any property that has the structure of a multivalued array:
    • MakeArrayFromSimpleList

    • MakeSimpleListFromArray

    • MakeArrayFromString

    • MakeStringFromArray

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' vMyVariant is a Variant
' varMySimpleList is an object reference to a SimpleList object
' oGlobalConfig is a Commerce GlobalConfig object
vMyVariant = oGlobalConfig.MakeArrayFromSimpleList(varMySimpleList)

See Also

GlobalConfig Object


GlobalConfig.MakeArrayFromString

Use this method to convert an encoded string read from the Fields property into an Array. If the encoded string does not indicate Array properties, then the method returns the original string that was passed into it.

Definition

Function MakeArrayFromString(
strList As Variant
) As Variant

Parameters

strList

A Variant that contains the encoded string.

Return Values

If this method completes successfully, it returns a Variant that contains the converted Array or unconverted String.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

Important

  • There is a special group of methods used with multivalued arrays. These methods are the only approved and recommended way of storing and retrieving multivalued arrays in the Administration database. You must use the following methods with any property that has the structure of a multivalued array:
    • MakeArrayFromSimpleList

    • MakeSimpleListFromArray

    • MakeArrayFromString

    • MakeStringFromArray

Note

  • This method can only be used on values exposed by the Fields object. The client-side disconnected ADO recordset has no support for Variants, Arrays, or objects as Fields columns. Therefore, the GlobalConfig object resorts to storing data in an encoded string format.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' vEncoded is a Variant containing an encoded string read from the Fields
' property
' vArray is a Variant
' oGlobalConfig is a Commerce GlobalConfig object
vArray = oGlobalConfig.MakeArrayFromString(vEncoded)

See Also

GlobalConfig Object


GlobalConfig.MakeSimpleListFromArray

Use this method to convert an Array into a SimpleList object.

Definition

Function MakeSimpleListFromArray(
varArray As Variant
) As Object

Parameters

varArray

A Variant that contains the Array to convert.

Return Values

If this method completes successfully, it returns an object reference to the converted SimpleList object.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

Important

  • There is a special group of methods used with multivalued arrays. These methods are the only approved and recommended way of storing and retrieving multivalued arrays in the Administration database. You must use the following methods with any property that has the structure of a multivalued array:
    • MakeArrayFromSimpleList

    • MakeSimpleListFromArray

    • MakeArrayFromString

    • MakeStringFromArray

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' vMyArray is a Variant
' varMySimpleList is a SimpleList object
' oGlobalConfig is a Commerce GlobalConfig object
varMySimpleList = oGlobalConfig.MakeSimpleListFromArray(vMyArray)

See Also

GlobalConfig Object


GlobalConfig.MakeStringFromArray

Use this method to convert an Array object into an encoded string, which can be written to the Fields property.

Definition

Function MakeStringFromArray(
varArray As Variant
) As Variant

Parameters

varArray

A Variant that contains the Array to encode.

Return Values

If this method completes successfully, it returns Variant that contains the encoded string.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The Initialize method must be called before this method can be called.

Important

  • There is a special group of methods used with multivalued arrays. These methods are the only approved and recommended way of storing and retrieving multivalued arrays in the Administration database. You must use the following methods with any property that has the structure of a multivalued array:
    • MakeArrayFromSimpleList

    • MakeSimpleListFromArray

    • MakeArrayFromString

    • MakeStringFromArray

Note

  • This method can only be used when updating values exposed by the Fields object. The client-side disconnected ADO recordset has no support for Variants, Arrays, or objects as Fields columns. Therefore, the GlobalConfig object resorts to storing data in an encoded string format.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' vEncoded is a Variant
' vArray is a Variant
' oGlobalConfig is a Commerce GlobalConfig object
vEncoded = oGlobalConfig.MakeStringFromArray(vArray)

See Also

GlobalConfig Object


GlobalConfig.MakeStringFromSimpleList

Use this method to convert a SimpleList object into an encoded string, which can be written to the Fields property.

Definition

Function MakeStringFromSimpleList(
slist As Object
) As String

Parameters

slist

An object reference to the SimpleList object that you wish to convert into an encoded string.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The Initialize method must be called before this method can be called.

Important

  • There is a special group of methods used with multivalued arrays. These methods are the only approved and recommended way of storing and retrieving multivalued arrays in the Administration database. You must use the following methods with any property that has the structure of a multivalued array:
    • MakeArrayFromSimpleList

    • MakeSimpleListFromArray

    • MakeArrayFromString

    • MakeStringFromArray

Note

  • This method can only be used when updating values exposed by the Fields object. The client-side disconnected ADO recordset has no support for Variants, Arrays, SimpleLists, or objects as Fields columns. Therefore, the GlobalConfig object resorts to storing data in an encoded string format.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' vEncoded is a string
' vArray is a Variant
' varMySimpleList is an object reference to a SimpleList object
' oGlobalConfig is a Commerce GlobalConfig object
vEncoded = oGlobalConfig.MakeStringFromSimpleList(varMySimpleList)

See Also

GlobalConfig Object


GlobalConfig.SaveConfig

Use this method to save the global configuration settings to the Administration database.

Definition

Sub SaveConfig(

)

Parameters

None.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The Initialize method must be called before this method can be called.

See Also

GlobalConfig Object


GlobalConfig.Sites

Use this method to retrieve a list of all the sites available in the Administration database.This method returns a Recordset object that contains a single record; the number of fields in the Fields collection is equal to the number of sites in the Commerce Server 2000 installation. Each Fields collection contains the name of one of the sites.

Definition

Function Sites (

) As Object

Parameters

None.

Return Values

If this method completes successfully, it returns a Recordset object that contains a list of all the sites available in the Administration data store.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The Initialize method must be called before this method can be called.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

GlobalConfig Object


ListManager Object

Use this object to create and manage lists of users for the User Profile Management system, lists of e-mail addresses for the Direct Mailer, lists of segment members for the Predictor resource, lists generated from Analysis reports, and lists created from files and SQL queries.

ProgID: | Commerce.ListManager (Externally creatable)
COM Class Name: | ListManager
Type Library Name: | Microsoft Commerce 2000 ListManager Type Library
EXE Name: | listmanager.exe
Threading Model: | Both

The properties of the ListManager object are shown in the following table.

Property | Type | Description
ConnectionString | String | Stores the connection string to the database used by the ListManager object to store lists. This value is set when passing the ConnectionString parameter to the Initialize method. This property is read-only.
Status | Long | Stores the current status of the ListManager object. This property is read-only.

The methods of the ListManager object are shown in the following table.

Method | Description
AddUserToMailingList | Adds a user to a mailing list.
CancelOperation | Cancels a currently running asynchronous operation.
Copy | Makes a copy of a list.
CreateEmpty | Creates an empty list for subsequent operations.
CreateFromDWCalc | Creates a list from an Analysis report.
CreateFromFile | Creates a list from a file.
CreateFromSegment | Creates a list from a Predictor Resource segment.
CreateFromSql | Creates a list from an SQL query.
Delete | Deletes a list.
ExportToFile | Exports a list to a file.
ExportToSql | Exports a list to a database table.
ExtractMailingList | Creates a new mailing list from a generic list that contains an rcp_email column.
GetListFlags | Retrieves the Flags bitmask for a list.
GetListId | Retrieves the list ID.
GetListName | Retrieves the list name.
GetListProperty | Retrieves a list property.
GetLists | Enumerates all known lists at the time of the call.
GetListUserFlags | Retrieves the UserFlags bitmask for a list.
GetOperationInfo | Retrieves information on a list operation.
GetOperations | Enumerates all operations running at the time of the call.
Initialize | Initializes the ListManager object.
RemoveUserFromMailingList | Removes a user from a mailing list.
Rename | Renames a list.
SetDesc | Assigns a description to a list.
SetListProperty | Sets a list property.
Subtract | Subtracts one list from another list, and stores the results in a third list.
Union | Produces a union of two lists (combines the lists and eliminates duplicates), and stores the results in a third list.
WaitOnOperation | Waits for an operation to complete or a timeout to occur, then returns.

Remarks

List Manager has functionality to manipulate two types of lists, Generic and Mailing. Each type may also have User and Mailable attributes. Lists are designated as static or dynamic depending on when the data is imported.

A Generic list may have any set of column names and types - it essentially maps to a SQL table.

A Mailing list is a list for use with Direct Mailer. It contains a list of recipients to receive mail or a list of recipients who should be opted out of a mailing. Each mailing list has its own table.

The following table describes the columns of a Mailing list table.

Field | Type | Description
rcp_email | NVARCHAR [256] | E-mail address of the recipient.
rcp_guid | NVARCHAR [64] | (Optional) User ID. Usually a GUID which is a key to the profile of the user.
rcp_fmt | smallint | (Optional) Message format flag. Legal values are: 1 - TEXT 2 - MIME 3 - MHTML
rcp_locale | NVARCHAR[20] | (Optional) Preferred character set of the recipient. See DirectMailer specifications for details.
rcp_url | NVARCHAR[2084] | (Optional) URL used for retrieving personalized content for the user.

A Mailable list is any list with an rcp_email column.

A User list is any list with an rcp_guid column.

In a static list, records are imported at the time the list is created.

A dynamic list imports records on demand when referenced by another operation.

List Manager can import lists from the following sources:

  • An SQL query run against an ODBC data source

  • An Analysis report run from the Business Desk

  • A Predictor Resource segment

  • A text file (CSV format)

List Manager can export lists to the following destinations:

  • A SQL Server 2000 table in an external database

  • A text file (CSV format)

List Manager allows time consuming operations to run in an asynchronous manner wherein the operation returns immediately after the process has started and assigns an operation ID that can be used to access the operation.

List Manager stores information about lists and operations in the lm_master and lm_master_operations tables, respectively.

See Also

List Management Objects


ListManager.AddUserToMailingList

Use this method to add a user record to a mailing list.

Definition

Sub AddUserToMailingList(
listID As Variant,
UserEmail As Variant,
Optional UserGUID As Variant,
Optional UserFmt As Variant,
Optional UserLocale As Variant,
Optional UserUrl As Variant
)

Parameters

listID

A Variant that contains ID or name of the list.

UserEmail

A Variant that contains the e-mail address of the user.

UserGUID

A Variant that contains the ID of the user (usually a GUID).

UserFmt

An optional Variant that contains the message format flag. See the Remarks section for more information.

UserLocale

An optional Variant that contains the preferred character set of the user.

UserUrl

An optional Variant that contains a URL used for retrieving personalized content for the user.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_LM_LIST_BUSY | &H8C400008 | The specified list is currently busy with another operation.
E_LM_LIST_IN_FAILED_STATE | &H8C40001D | The specified list is in a FAILED state and may not be used for the operation.
E_LM_LIST_NOT_FOUND | &H8C400006 | The specified list does not exist.
E_LM_MAILABLE_LIST_NO_EMAILS | &H8C40000D | The list is designated as a Mailable list but does not contain an rcp_email column.
E_LM_MUST_BE_STATIC | &H8C400019 | The operation requires a static list and the specified list is dynamic.
E_LM_NOT_MAILING_LIST | &H8C400018 | The operation requires a Mailing list and the specified list is not a mailing list.
E_LM_SQLERROR | &H8C400003 | Error while executing SQL/ADO operation.
E_LM_USER_LIST_NO_GUIDS | &H8C40000E | The list is designated as a User list but does not contain an rcp_guid column.
OLE_E_BLANK | &H80040007 | The ListManager object has not been properly initialized.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The UserFmt parameter specifies the format of a message used by the Direct Mailer. The possible values are: text (1), MIME (2), and MHTML (3).

To specify that one or more of the fields should be inserted as NULL, pass VT_NULL, VT_EMPTY, or VT_ERROR as the optional parameter(s).

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

oListManager.AddUserToMailingList "{2B544800-4169-4C49-8713-1B794078B4C9}", _
 "JaneUser@somewhere.com", "{454799A2-312B-4F5F-90A0-F514FBA0EC5A}", _
 2, 1033, VT_NULL

See Also

ListManager Object


ListManager.CancelOperation

Use this method to cancel the specified ListManager operation.

Definition

Sub CancelOperation(
varOpID As Variant
)

Parameters

varOpID

A Variant that specifies the Operation ID of the operation to be cancelled.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors, and the standard COM errors with special meanings, that this method can return.

Constant | Value | Description
E_LM_OPERATION_NOT_FOUND | &H8C400004 | The operation ID does not represent a currently running operation.
E_LM_SQLERROR | &H8C400003 | Error while executing SQL/ADO operation.
OLE_E_BLANK | &H80040007 | The ListManager object has not been properly initialized.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The Operation ID passed to this method in the varOpID parameter can be obtained from any of the following calls when they are executed asynchronously:

  • Copy

  • CreateFromDWCalc

  • CreateFromFile

  • CreateFromSql

  • ExportToFile

  • ExportToSql

  • Subtract

  • Union

In addition, the Operation IDs of all known operations can be retrieved using the GetOperations method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ListManager Object


ListManager.ConnectionString

The ConnectionString property is a read-only string that contains the database connection string the List Manager uses to store lists. This property is set by the Initialize method.

Definition

Property ConnectionString() As String

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

See Also

ListManager Object


ListManager.Copy

Use this method to copy an existing list over another existing list.

Definition

Sub Copy(
srcList As Variant,
resList As Variant,
bAsync As Boolean,
Optional pvarOpID As Variant
)

Parameters

srcList

A Variant that contains the ID or name of the source list.

resList

A Variant that contains the ID or name of the result list.

bAsync

A Boolean that specifies whether the copy operation is performed synchronously or asynchronously. A value of True indicates asynchronous processing.

pvarOpID

An optional Variant used to return an Operation ID.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_LM_COPY_LIST_OVER_SELF | &H8C40001C | Cannot copy a list over itself.
E_LM_LIST_BUSY | &H8C400008 | The specified list is currently busy with another operation.
E_LM_LIST_IN_FAILED_STATE | &H8C40001D | The specified list is in a FAILED state and may not be used for the operation.
E_LM_LIST_NOT_FOUND | &H8C400006 | The specified list does not exist.
E_LM_OPER_CANCELED | &H8C40000B | The operation was canceled.
E_LM_SQLERROR | &H8C400003 | Error while executing SQL/ADO operation.
OLE_E_BLANK | &H80040007 | The ListManager object has not been properly initialized.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The result list must exist prior to calling the method; however, any data in the list will be overwritten.

The flags attribute of the destination list is replaced with the flags attribute of the source list. The UserFlags attribute is not changed.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' pvarOdID is a Variant
oListManager.Copy "{2B544800-4169-4C49-8713-1B794078B4C9}", _
 "{454799A2-312B-4F5F-90A0-F514FBA0EC5A}", True, pvarOpID

See Also

ListManager Object


ListManager.CreateEmpty

Use this method to create an empty list for subsequent operations.

Definition

Function CreateEmpty(
listName As String,
listDesc As String,
flags As Long,
userFlags As Long
) As Variant

Parameters

listName

A String that provides the name for the new list.

listDesc

A String that provides a description for the new list.

flags

A Long that specifies the bitmask flags that control the type of list created.

userFlags

A Long that contains application specific user flags. Not used by the ListManager object.

Return Values

If this method completes successfully, it returns a Variant that contains the ID of the new list.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_LM_INVALID_FLAGS | &H8C400005 | Invalid flags value.
E_LM_LIST_ALREADY_EXISTS | &H8C400007 | The specified list has already been created.
E_LM_SQLERROR | &H8C400003 | Error while executing SQL/ADO operation.
OLE_E_BLANK | &H80040007 | The ListManager object has not been properly initialized.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

This method is useful for creating an empty list for use as the result list of a copy, subtract, or union operation.

For a list of possible values for the flags parameter, see the GetListFlags method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' vListID is a Variant
vListID = oListManager.CreateEmpty("TequillaBuyers1", _
 "Tequilla buyers in January", 20, 0)

See Also

ListManager Object


ListManager.CreateFromDWCalc

Use this method to create a list from an Analysis report.

Definition

Function CreateFromDWCalc(
listName As String,
listDesc As String,
lFlags As Long,
userFlags As Long,
DWConnStr As String,
OLAPConnStr As String,
ReportStatusId As String,
bAsync As Boolean,
Optional pvarOpID As Variant
) As Variant

Parameters

listName

A String that provides the name for the new list.

listDesc

A String that provides a description for the new list.

lFlags

A Long that specifies the bitmask flags that control the type of list created.

userFlags

A Long that contains application specific user flags. Not used by the ListManager object.

DWConnStr

A String that contains the connection string for the Data Warehouse.

OLAPConnStr

A String that contains the OLAP connection string.

ReportStatusId

A String that contains the ReportStatusID of the report to be imported.

bAsync

A Boolean that specifies whether the creation operation is performed synchronously or asynchronously. A value of True indicates asynchronous processing.

pvarOpID

An optional Variant used to return an Operation ID.

Return Values

If this method completes successfully, it returns a Variant that contains the ID of the new list.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_LM_CONNECTIONFAILED | &H8C400001 | Failed to establish database connection.
E_LM_CREATE_OBJECT | &H8C400017 | Unable to create the object.
E_LM_INVALID_FLAGS | &H8C400005 | Invalid flags value.
E_LM_LIST_ALREADY_EXISTS | &H8C400007 | The specified list has already been created.
E_LM_MAILABLE_LIST_NO_EMAILS | &H8C40000D | The list is designated as a Mailable list but does not contain an rcp_email column.
E_LM_OPER_CANCELED | &H8C40000B | The operation was canceled.
E_LM_REPORTRENDERERFAILED | &H8C40001A | The report rendering object failed during Analysis report export to ListManager. See the Application event log message logged by that object describing the problem.
E_LM_SQLERROR | &H8C400003 | Error while executing SQL/ADO operation.
E_LM_USER_LIST_NO_GUIDS | &H8C40000E | The list is designated as a User list but does not contain an rcp_guid column.
OLE_E_BLANK | &H80040007 | The ListManager object has not been properly initialized.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

This method calls into the ReportRender object, passing it the DWConnStr, OLAPConnStr, and the ReportStatusId parameters along with a connection string to the database used by the ListManager object, and the table name that it should create.

For a list of possible values for the lflags parameter, see the GetListFlags method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' vListID is a Variant
vListID = oListManager.CreateFromDWCalc("TequillaBuyers1", _
 "Tequilla buyers in January", 20, 0, "URL=mscop:" & _
 "//InProcConnect/Server=myserver:Database=dbname:" & _
 "Catalog=DWSchema:User=userid:Password=********:FastLoad=True", _
 "2B54480041694C4987131B794078B4C9", False)

See Also

ListManager Object


ListManager.CreateFromFile

Use this method to create a list from a text file.

Definition

Function CreateFromFile(
listName As String,
listDesc As String,
lFlags As Long,
userFlags As Long,
fileName As String,
errLimit As Long,
bAsync As Boolean,
Optional pvarOpID As Variant
) As Variant

Parameters

listName

A String that provides the name for the new list.

listDesc

A String that provides a description for the new list.

lFlags

A Long that specifies the bitmask flags that control the type of list created.

userFlags

A Long that contains application specific user flags. Not used by the ListManager object.

fileName

A String that contains the name of the file from which to create the new list.

errLimit

A Long that specifies the maximum number of errors allowed before the operation is terminated. To specify no limit, set the errLimit parameter to zero (0).

bAsync

A Boolean that specifies whether the creation operation is performed synchronously or asynchronously. A value of True indicates asynchronous processing.

pvarOpID

An optional Variant used to return an Operation ID.

Return Values

If this method completes successfully, it returns a Variant that contains the ID of the new list.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors, and the standard COM errors with special meanings, that this method can return.

Constant | Value | Description
E_LM_BAD_FILE_PATH | &H8C40000A | The specified file path is not valid.
E_LM_FILE_ACCESS_DENIED | &H8C400009 | The ListManager service does not have permission to open the specified file.Check the permissions for the ListManager service account against the permissions for the file.
E_LM_FILE_NOT_FOUND | &H8C400015 | The specified file does not exist.
E_LM_FILESHARE_NOT_FOUND | &H8C400016 | The network share does not exist and a full path was not specified for the file.
E_LM_INVALID_FLAGS | &H8C400005 | Invalid flags value.
E_LM_LIST_ALREADY_EXISTS | &H8C400007 | The specified list has already been created.
E_LM_LISTPARSE_NO_GOOD_ROWS | &H8C40001B | All rows in the file contained parse errors. List import failed.
E_LM_NO_GENERIC_FROM_FILE | &H8C400014 | Generic lists may not be imported from files.
E_LM_OPER_CANCELED | &H8C40000B | The operation was canceled.
E_LM_SQLERROR | &H8C400003 | Error while executing SQL/ADO operation.
OLE_E_BLANK | &H80040007 | The ListManager object has not been properly initialized.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

If a list with the same name as the listName parameter already exists, the method fails. Lists imported from text files may not be generic lists; they are always mailing lists.

The user account that the List Manager is configured to run under must have permission to access the file. For example, if the file is on a network share, the service must be running under a domain account or must otherwise have permission to access the share.

If an absolute file path and name is not specified, List Manager will look for the file relative to a root folder named CommerceLists on the local computer running the List Manager service. If the folder does not exist, an error is returned.

List Manager recognizes the following input text file format:

   <Mail-to address>,<User ID>,<Message Format>,<Locale>,
   <Source URL><cr><lf>

Mail-to address is the only required field. The Message Format field should be one of the following: 1 = text, 2 = mime, or 3 = mhtml. The Message Format, Locale, and Source fields are provided for use with Direct Mailer.

Any of the fields may be enclosed in double quotation marks. This is required if the value in the field contains any comma or double quotation mark characters. Two double quotation marks together within a quoted field can be used to denote a double quotation mark. A trailing comma will produce an error.

For a list of possible values for the lflags parameter, see the GetListFlags method.

Rows with duplicate e-mail addresses in the file are ignored.

The parameter, pvarOpID, contains valid data only if the creation operation is performed asynchronously.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' vListID is a Variant
vListID = oListManager.CreateFromFile("TequillaBuyers1", _
 "Tequilla buyers in January", 20, 0, "Tequilla.csv", 10, False)

See Also

ListManager Object


ListManager.CreateFromSegment

Use this method to create a list from a Predictor resource segment.

Definition

Function CreateFromSegment(
listName As String,
listDesc As String,
lFlags As Long,
userFlags As Long,
modelName As String,
segmentName As String,
predHostName As String,
DWConnStr As String,
fpMinProbability As Double,
bAsync As Boolean,
Optional pvarOpID As Variant
) As Variant

Parameters

listName

A String that contains provides the name for the list.

listDesc

A String that contains the list description.

lFlags

A Long that specifies the bitmask flags that control the type of list created.

userFlags

A Long that contains application specific user flags. Not used by the ListManager object.

modelName

A String that contains the name of the Predictor segment model to use.

segmentName

A String that contains the name of the segment to import.

predHostName

A String that contains the name of the Predictor host server.

DWConnStr

A String that contains the Data Warehouse connection string.

fpMinProbability

A Double that contains the minimum probability associated with a given segment member for that member to be included in the list.

bAsync

A Boolean that specifies whether the creation operation is performed synchronously or asynchronously. A value of True indicates asynchronous processing.

pvarOpID

An optional Variant used to return an Operation ID.

Return Values

If this method completes successfully, it returns a Variant used to return the new list ID.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_LM_CONNECTIONFAILED | &H8C400001 | Failed to establish database connection.
E_LM_CREATE_OBJECT | &H8C400017 | Unable to create the object.
E_LM_INVALID_FLAGS | &H8C400005 | Invalid flags value.
E_LM_LIST_ALREADY_EXISTS | &H8C400007 | The specified list has already been created.
E_LM_MAILABLE_LIST_NO_EMAILS | &H8C40000D | The list is designated as a Mailable list but does not contain an rcp_email column.
E_LM_OPER_CANCELED | &H8C40000B | The operation was canceled.
E_LM_SQLERROR | &H8C400003 | Error while executing SQL/ADO operation.
E_LM_USER_LIST_NO_GUIDS | &H8C40000E | The list is designated as a User list but does not contain an rcp_guid column.
OLE_E_BLANK | &H80040007 | The ListManager object has not been properly initialized.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

This method calls into the PredictorServiceSiteAdmin object, passing it the modelName, segmentName, and fpMinProbability parameters along with a connection string to the database used by the ListManager object, and the table name that it should create.

For a list of possible values for the lflags parameter, see the GetListFlags method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' vListID is a Variant
vListID = oListManager.CreateFromSegment("TequillaBuyers", _
 "Thirty year old tequilla buyers ", 20, 0, "Tequilla", "Thirty", _
 "TequillaServer", "Provider=SQLOLEDB;Data Source=servername;" & _
 "Initial Catalog=Retail_dw;User ID=user;Password=********;", False)

See Also

ListManager Object

ListManager.GetListFlags


ListManager.CreateFromSql

Use this method to create a list from a SQL query.

Definition

Function CreateFromSql(
listName As String,
listDesc As String,
lFlags As Long,
userFlags As Long,
connStr As String,
queryStr As String,
errLimit As Long,
bAsync As Boolean,
pvarOpID As Variant
) As Variant

Parameters

listName

A String that provides the name for the list.

listDesc

A String that provides a description for the list.

lFlags

A Long that specifies the bitmask flags that control the type of list created.

userFlags

A Long that contains application specific user flags. Not used by the ListManager object.

connStr

A String that contains the connection string for the SQL Server database.

queryStr

A String that contains the SQL query for retrieving the contents of the new list.

errLimit

A Long that is not used.

bAsync

A Boolean that specifies whether the creation operation is performed synchronously or asynchronously. A value of True indicates asynchronous processing.

pvarOpID

An optional Variant used to return an Operation ID.

Return Values

If this method completes successfully, it returns a Variant that contains the ID of the new list.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_LM_CONNECTIONFAILED | &H8C400001 | Failed to establish database connection.
E_LM_INVALID_FLAGS | &H8C400005 | Invalid flags value.
E_LM_LIST_ALREADY_EXISTS | &H8C400007 | The specified list has already been created.
E_LM_MAILABLE_LIST_NO_EMAILS | &H8C40000D | The list is designated as a Mailable list but does not contain an rcp_email column.
E_LM_OPER_CANCELED | &H8C40000B | The operation was canceled.
E_LM_SQLERROR | &H8C400003 | Error while executing SQL/ADO operation.
E_LM_USER_LIST_NO_GUIDS | &H8C40000E | The list is designated as a User list but does not contain an rcp_guid column.
OLE_E_BLANK | &H80040007 | The ListManager object has not been properly initialized.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

It is recommended to use the MSDASQL (ODBC) OLEDB provider with this method.

The CreateFromSQL method uses the T-SQL OpenRowset command to run the query against the database. Therefore, any ODBC data source may be specified with the following restriction:

If the SQLOLEDB provider is used, any object names used in the query must be fully qualified. For example, on SQL Server 7.0 databases, use "SELECT * FROM database.dbo.tablename" instead of "SELECT * FROM tablename".

For a list of possible values for the lflags parameter, see the GetListFlags method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' vListID is a Variant
vListID = oListManager.CreateFromSql("LegalTequillaBuyers", _
 "Tequilla buyers at least 21", 20, 0, "Provider=sqloledb;" & _
 "Data Source=TequillaServer;Initial Catalog=Margaritas;" & _
 "User=userid;Password=******", "SELECT * FROM dbname.dbo.Tequilla " & _
 "WHERE Age >= 21", 10, False)

See Also

ListManager Object


ListManager.Delete

Use this method to delete a list.

Definition

Sub Delete(
listID As Variant
)

Parameters

listID

A Variant that specifies the ID or name of the list to be deleted.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_LM_LIST_BUSY | &H8C400008 | The specified list is currently busy with another operation.
E_LM_LIST_NOT_FOUND | &H8C400006 | The specified list does not exist.
E_LM_SQLERROR | &H8C400003 | Error while executing SQL/ADO operation.
OLE_E_BLANK | &H80040007 | The ListManager object has not been properly initialized.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

To be deleted, a list cannot be busy with any operation.

The list data is also deleted.

See Also

ListManager Object


ListManager.ExportToFile

Use this method to export a Mailing list to a text file.

Definition

Sub ExportToFile(
listID As Variant,
fileName As String,
bUnicode As Boolean,
bOverwrite As Boolean,
bAsync As Boolean,
Optional pvarOpID As Variant
)

Parameters

listID

A Variant that contains the ID or name of the list to be exported.

fileName

A String that contains the name of the file.

bUnicode

A Boolean that specifies the character format of the export file. A value of True indicates that Unicode characters should be used. A value of False indicates that the current system codepage character set should be used.

bOverwrite

A Boolean that specifies whether to overwrite the data in the export file, if it exists. A value of True indicates that the data should be overwritten. A value of False causes the method to fail if the file exists.

bAsync

A Boolean that specifies whether the creation operation is performed synchronously or asynchronously. A value of True indicates asynchronous processing.

pvarOpID

An optional Variant used to return an Operation ID.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_LM_BAD_FILE_PATH | &H8C40000A | The specified file path is not valid.
E_LM_FILE_ACCESS_DENIED | &H8C400009 | The ListManager service does not have permission to open the specified file.Check the permissions for the ListManager service account against the permissions for the file.
E_LM_FILE_ALREADY_EXISTS | &H8C400010 | The specified file cannot be created because it already exists.
E_LM_FILESHARE_NOT_FOUND | &H8C400016 | The network share does not exist and a full path was not specified for the file.
E_LM_LIST_BUSY | &H8C400008 | The specified list is currently busy with another operation.
E_LM_LIST_IN_FAILED_STATE | &H8C40001D | The specified list is in a FAILED state and may not be used for the operation.
E_LM_LIST_NOT_FOUND | &H8C400006 | The specified list does not exist.
E_LM_MAILABLE_REQUIRED | &H8C400011 | The operation requires a mailable list and the specified list is not a mailable list.
E_LM_OPER_CANCELED | &H8C40000B | The operation was canceled.
E_LM_SQLERROR | &H8C400003 | Error while executing SQL/ADO operation.
OLE_E_BLANK | &H80040007 | The ListManager object has not been properly initialized.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

If the list is a Mailable list but not a Mailing list, a temporary Mailing list is created and then exported.

If an absolute file path and name are not specified, ListManager exports the file relative to a root folder named CommerceLists on the local computer running the ListManager resource. If the folder does not exist, an error is returned.

ListManager exports the file in the following format. The is Message Format field is an integer, all other fields are strings and enclosed in double quotation marks.

   <Mail-to address>,<User ID>,<Message Format>,<Locale>,
   <Source URL><cr><lf>

The parameter pvarOpID contains valid data only if the export operation is performed asynchronously.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

oListManager.ExportToFile "{2B544800-4169-4C49-8713-1B794078B4C9}", _
 "Tequila.csv", False, True, False

See Also

ListManager Object


ListManager.ExportToSql

Use this method to export a list to the specified table in a Microsoft SQL Server database. This operation can be performed synchronously or asynchronously.

Definition

Sub ExportToSql(
listID As Variant,
connStr As String,
resTable As String,
bOverwrite As Boolean,
lOptions As Long,
bAsync As Boolean,
Optional pvarOpID As Variant
)

Parameters

listID

A Variant that contains the ID or name of the list to be exported.

connStr

A String that contains the connection string for the SQL Server database.

resTable

A String that contains the name of the table into which the list will be exported.

bOverwrite

A Boolean that specifies whether to overwrite the data in the table if the table already exists. A value of True indicates that the data should be overwritten. A value of False produces an error if the tables pre-exists.

lOptions

A Long that specifies the export options, for use by the Direct Mail resource. Other applications should generally pass the value zero (0). A value of one (1) causes special action to be taken. See the Remarks section below.

bAsync

A Boolean that specifies whether the creation operation is performed synchronously or asynchronously. A value of True indicates asynchronous processing. A value of False indicates synchronous processing.

pvarOpID

An optional Variant used to return an Operation ID. This Operation ID is used in subsequent processing concerning this operation.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_LM_CONNECTIONFAILED | &H8C400001 | Failed to establish database connection.
E_LM_LIST_BUSY | &H8C400008 | The specified list is currently busy with another operation.
E_LM_LIST_IN_FAILED_STATE | &H8C40001D | The specified list is in a FAILED state and may not be used for the operation.
E_LM_LIST_NOT_FOUND | &H8C400006 | The specified list does not exist.
E_LM_OPER_CANCELED | &H8C40000B | The operation was canceled.
E_LM_SQLERROR | &H8C400003 | Error while executing SQL/ADO operation.
E_LM_TABLE_ALREADY_EXISTS | &H8C40000F | The specified table cannot be created because it already exists.
OLE_E_BLANK | &H80040007 | The ListManager object has not been properly initialized.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

An existing table is expected to have the same format as the exported list. If the table does not exist, it will be created.

The ExportToSQL method works by opening a connection on the destination SQL Server database and executing the T-SQL OpenRowset command to select data from the List Manager database. Because of this, some special caveats apply:

  • The destination database must have the Bulk Copy/Select Into option selected.

  • If the List Manager was initialized with a connection string containing a DSN then the SQL server computer hosting the destination database must also have the DSN configured.

  • Unlike the CreateFromSQL command, ODBC data sources other than SQL Server 7.0 or greater are not supported.

The parameter pvarOpID contains valid data only if the export operation is performed asynchronously.

The lOptions parameter specifies whether the exported list is intended for use with Direct Mailer, controlling how it is processed during the export. The following table shows the legal values of the IOptions parameter.

lOptions value | Description
0 | Do not do any special processing for Direct Mailer.
1 | Export the list for use with Direct Mailer. The list must be a Mailable list or an error is returned. If the list is not a mailing list, it is converted to one.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

oListManager.ExportToSql "{2B544800-4169-4C49-8713-1B794078B4C9}", _
 "Provider=sqloledb;Data Source=TequillaServer;" & _
 "Initial Catalog=Margaritas;User=userid;Password=******", _
 "Tequila", False, 0, False

See Also

ListManager Object

ListManager.ExtractMailingList


ListManager.ExtractMailingList

Use this method to create a new mailing list from a generic list.

Definition

Function ExtractMailingList(
srcList As Variant,
reslistName As String,
reslistDesc As String,
userFlags As Long,
bAsync As Boolean,
Optional pvarOpID As Variant
) As Variant

Parameters

srcList

A Variant that contains the ID or name of the generic source list.

reslistName

A String that contains the new mailing list name.

reslistDesc

A String that contains the description of the new mailing list.

userFlags

A Long that contains application specific user flags. Not used by the ListManager object.

bAsync

A Boolean that specifies whether the export operation is performed synchronously or asynchronously. A value of True indicates asynchronous processing.

pvarOpID

An optional Variant used to return an Operation ID.

Return Values

If this method completes successfully, it returns a Variant that contains the ID of the new list.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_LM_LIST_ALREADY_EXISTS | &H8C400007 | The specified list has already been created.
E_LM_LIST_BUSY | &H8C400008 | The specified list is currently busy with another operation.
E_LM_LIST_IN_FAILED_STATE | &H8C40001D | The specified list is in a FAILED state and may not be used for the operation.
E_LM_LIST_NOT_FOUND | &H8C400006 | The specified list does not exist.
E_LM_MAILABLE_LIST_NO_EMAILS | &H8C40000D | The list is designated as a Mailable list but does not contain an rcp_email column.
E_LM_MAILABLE_REQUIRED | &H8C400011 | The operation requires a mailable list and the specified list is not a mailable list.
E_LM_OPER_CANCELED | &H8C40000B | The operation was canceled.
E_LM_SQLERROR | &H8C400003 | Error while executing SQL/ADO operation.
E_LM_USER_LIST_NO_GUIDS | &H8C40000E | The list is designated as a User list but does not contain an rcp_guid column.
OLE_E_BLANK | &H80040007 | The ListManager object has not been properly initialized.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The source list must be a Mailable list (contains an rcp_email column). Any duplicate e-mail addresses are removed in the result list.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' vListID & pvarOpId are Variants
vListID = oListManager.ExtractMailingList("{454799A2-312B-4F5F-90A0-" & _
 "F514FBA0EC5A}", "TequilaBuyers1", "Tequilla buyers in January", 0, _
 True, pvarOpID)

See Also

ListManager Object


ListManager.GetListFlags

Use this method to retrieve the flags attribute for a list.

Definition

Function GetListFlags(
listID As Variant
) As Long

Parameters

listID

A Variant that contains the ID of the ID or name of the list.

Return Values

If this method completes successfully, it returns a Long that contains the flags attribute.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_LM_LIST_NOT_FOUND | &H8C400006 | The specified list does not exist.
E_LM_SQLERROR | &H8C400003 | Error while executing SQL/ADO operation.
OLE_E_BLANK | &H80040007 | The ListManager object has not been properly initialized.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The following table lists the possible flag parameter values used to determine the type of list created. Values may be OR'ed together to specify more than one flag.

Type | Value | Description
DEFAULT | 0x0 | A Mailing list
HIDDEN | 0x1 | The list should not be exposed in the user interface
DYNAMIC | 0x2 | A dynamic list
USER | 0x4 | A User list (contains an rcp_guid column)
GENERIC | 0x8 | A Generic list
MAILABLE | 0x10 | A Mailable list (contains an rcp_email column)

See Also

ListManager Object


ListManager.GetListId

Use this method to retrieve the ID of a list given the list name.

Definition

Function GetListId(
listName As String
) As Variant

Parameters

listName

A String that contains the list name.

Return Values

If this method completes successfully, it returns a Variant containing the ID (a GUID) of the list.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_LM_LIST_NOT_FOUND | &H8C400006 | The specified list does not exist.
E_LM_SQLERROR | &H8C400003 | Error while executing SQL/ADO operation.
OLE_E_BLANK | &H80040007 | The ListManager object has not been properly initialized.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ListManager Object


ListManager.GetListName

Use this method to retrieve the name of a list given the list ID.

Definition

Function GetListName(
listID As Variant
) As String

Parameters

listID

A Variant that contains the list ID.

Return Values

If this method completes successfully, it returns a String that contains the name of the list.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_LM_LIST_NOT_FOUND | &H8C400006 | The specified list does not exist.
E_LM_SQLERROR | &H8C400003 | Error while executing SQL/ADO operation.
OLE_E_BLANK | &H80040007 | The ListManager object has not been properly initialized.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ListManager Object


ListManager.GetListProperty

Use this method to retrieve a property of a list.

Definition

Function GetListProperty(
listID As Variant,
listPropertyName As String
) As Variant

Parameters

listID

A Variant that contains the ID or name of the list.

listPropertyName

A String that contains the property name (column of the lm_master table).

Return Values

If this method completes successfully, it returns a Variant containing the value of the property.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_LM_LIST_NOT_FOUND | &H8C400006 | The specified list does not exist.
E_LM_SQLERROR | &H8C400003 | Error while executing SQL/ADO operation.
OLE_E_BLANK | &H80040007 | The ListManager object has not been properly initialized.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For information about the available list properties, see ListManager.GetLists.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' vSource is a Variant
vSource = _
 oListManager.GetListProperty("{454799A2-312B-4F5F-90A0-F514FBA0EC5A}", _
 "list_source")

See Also

ListManager Object


ListManager.GetLists

Use this method to enumerate all lists known to the ListManager object.

Definition

Function GetLists() As Object

Parameters

None.

Return Values

If this method completes successfully, it returns an ADO Recordset object that contains the details of the lists known to this instance of the ListManager object.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

This method returns an instance of a read-only ADO Recordset object that contains a record for each list in the ListManager object database. The Recordset object does not contain any lists that are not completely created at the time this method is invoked.

If there are not any lists completely created at the time this method is invoked, the method returns successfully, but the Recordset object is empty.

The following table describes the fields returned in the Recordset object.

Field | Type | Description
list_id | uniqueidentifier | Identification number of the list.
list_name | NVARCHAR [64] | Name of the list.
list_created | datetime | Date/time the list record was created.
list_creation_type | smallint | Method used to create the list. Legal values are: 1 - CreateFromFile 2 - CreateFromSQL 3 - CreateFromDWCalc 4 - CreateFromSegment 5 - Other (subtraction, union, extraction, etc.)
list_description | NVARCHAR [256] | List description.
list_err_limit | long | The error threshold for the list.
list_flags | int | Bit flags for the list. Can bitwise OR together to specify more than one flag. Legal values are: 0x0 - DEFAULT 0x1 - HIDDEN 0x2 - DYNAMIC 0x4 - USER 0x8 - GENERIC 0x10 - MAILABLE
list_location | NVARCHAR [256] | Location (table name) where the list data is stored.
list_query | NVARCHAR [1024] | Query used to create the list.
list_recent_operid | NVARCHAR [128] | ID of the most recent list operation. May be Null if the list is a new list created by the CreateEmpty method.
list_size | int | Number of rows in the list (-1 for dynamic lists).
list_source | NVARCHAR [512] | Name of the file, connection string, or filename used to create the list.
list_status | int | Status of the list. Legal values are: 1 - ready for processing 2 - being processed; other operations are not permitted 3 - failed
list_unique_emails | int | Number of unique rcp_email values in the list (-1 for dynamic lists).
list_unique_guids | int | Number of unique rcp_guid values in the list (-1 for dynamic lists).
list_userflags | int | Application specific. Not used by the ListManager object.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ListManager Object


ListManager.GetListUserFlags

Use this method to retrieve the UserFlags attribute for a list.

Definition

Function GetListUserFlags(
listID As Variant
) As long

Parameters

listID

A Variant that contains the ID of the ID or name of the list.

Return Values

If this method completes successfully, it returns a Long that contains the UserFlags attribute.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_LM_LIST_NOT_FOUND | &H8C400006 | The specified list does not exist.
E_LM_SQLERROR | &H8C400003 | Error while executing SQL/ADO operation.
OLE_E_BLANK | &H80040007 | The ListManager object has not been properly initialized.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The UserFlags attributes are for use by applications external to the List Manager. The List Manager merely stores the flags that were passed in at the time a list was created and does not interpret the UserFlags attributes value in any way.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ListManager Object


ListManager.GetOperationInfo

Use this method to retrieve a Recordset object containing columns describing the specified list operation.

Definition

Function GetOperationInfo(
varOpID As Variant
) As Object

Parameters

varOpID

A Variant that contains the Operation ID.

Return Values

If this method completes successfully, it returns a Recordset object containing the operation information.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about the returned Recordset object, see ListManager.GetOperations.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ListManager Object


ListManager.GetOperations

Use this method to enumerate all operations known to the ListManager object.

Definition

Function GetOperations() As Object

Parameters

None.

Return Values

If this method completes successfully, it returns an ADO Recordset object that contains information about the operations known to this instance of the ListManager object.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

This method returns an instance of a read-only ADO Recordset object that contains a record for each operation in the ListManager object database. There is a record for every operation that has ever been run on lists currently in the database. When a list is deleted, all operations associated with that list are also deleted.

The following table describes the fields returned in the Recordset object.

Field | Type | Description
op_id | NVARCHAR[128] | A "token" that identifies the operation and can be passed to the CancelOperation method to terminate the operation.
op_desc | NVCHAR[256] | A user-friendly operation description.
op_error_code | int | HRESULT of last failure associated with the list.
op_error_desc | NVARCHAR[1024] | Description of the last failure associated with the list.
op_list_destination | Nvarchar(256) | List destination (Export type operations only).
op_list_id | uniqueidentifier | The list ID on which this operation is taking place.
op_list_id_a | uniqueidentifier | Additional column if the operation has multiple lists involved.
op_list_id_b | uniqueidentifier | Additional column if the operation has multiple lists involved.
op_list_param1 | int | Additional column which stores any extra parameters involved in the operation.
op_list_param2 | int | Additional column which stores any extra parameters involved in the operation.
op_list_table | nvarchar(256) | Tablename (ExportToSql type operations only).
op_progress | int | Unused.
op_status | smallint | Status of the operation. Legal values are: 0 - complete 1 - executing -1 - failed
op_time_end | datetime | Date/time the operation completed or was aborted.
op_time_start | datetime | Date/time the operation started.
op_type | int | The type of operation. Legal values are: 1 - CreateFromFile 2 - CreateFromSQL 3 - ExportToFile 4 - ExportToSQL 5 - Copy 6 - Subtract 7 - Union 8 - CreateFromDWCalc. 9 - CreateFromSegment 10 - ExtractMailingList 11 - Other (unclassified or temporary)

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ListManager Object

ListManager.CancelOperation


ListManager.Initialize

Use this method to initialize the ListManager object.

Definition

Sub Initialize(
bstrConnStr As String,
)

Parameters

bstrConnStr

A String that contains the connection string for the database to which the List Manager will connect.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_LM_ALREADYINITIALIZED | &H8C400002 | The ListManager object has already been initialized and may not be re-initialized.
E_LM_CONNECTIONFAILED | &H8C400001 | Failed to establish database connection.
E_LM_SQLERROR |  | Error while executing SQL/ADO operation.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Initialize the ListManager object before calling any other ListManager object method or property.

Initializing connects the ListManager object to a database. If the database does not contain the tables and procedures required by the ListManager object, they are created.

A ListManager object can be connected to only one database. To connect to a different database, instantiate a new ListManager object.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

oListManager.Initialize "Provider=sqloledb;" & _
 "Data Source=TequillaServer;Initial Catalog=Margaritas;" & _
 "User=userid;Password=******"

See Also

ListManager Object

ListManager.ExportToSQL


ListManager.RemoveUserFromMailingList

Use this method to remove a user from a mailing list

Definition

Sub RemoveUserFromMailingList(
listID As Variant,
UserEmail As String
)

Parameters

listID

A Variant that contains the ID or name of the list.

UserEmail

A String that contains the e-mail address of the user.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_LM_LIST_BUSY | &H8C400008 | The specified list is currently busy with another operation.
E_LM_LIST_IN_FAILED_STATE | &H8C40001D | The specified list is in a FAILED state and may not be used for the operation.
E_LM_LIST_NOT_FOUND | &H8C400006 | The specified list does not exist.
E_LM_MAILABLE_LIST_NO_EMAILS | &H8C40000D | The list is designated as a Mailable list but does not contain an rcp_email column.
E_LM_MUST_BE_STATIC | &H8C400019 | The operation requires a static list and the specified list is dynamic.
E_LM_NOT_MAILING_LIST | &H8C400018 | The operation requires a Mailing list and the specified list is not a mailing list.
E_LM_SQLERROR | &H8C400003 | Error while executing SQL/ADO operation.
E_LM_USER_LIST_NO_GUIDS | &H8C40000E | The list is designated as a User list but does not contain an rcp_guid column.
OLE_E_BLANK | &H80040007 | The ListManager object has not been properly initialized.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

oListManager.RemoveUserFromMailingList _
 "{454799A2-312B-4F5F-90A0-F514FBA0EC5A}", "JaneUser@somewhere.com"

See Also

ListManager Object


ListManager.Rename

Use this method to rename a list.

Definition

Sub Rename(
listID As Variant,
newListName As String
)

Parameters

listID

A Variant that specifies the ID or name of the list to be renamed.

newListName

A String that contains the new name for the list.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_LM_LIST_ALREADY_EXISTS | &H8C400007 | The specified list has already been created
E_LM_LIST_BUSY | &H8C400008 | The specified list is currently busy with another operation.
E_LM_LIST_IN_FAILED_STATE | &H8C40001D | The specified list is in a FAILED state and may not be used for the operation.
E_LM_LIST_NOT_FOUND | &H8C400006 | The specified list does not exist.
E_LM_SQLERROR | &H8C400003 | Error while executing SQL/ADO operation.
OLE_E_BLANK | &H80040007 | The ListManager object has not been properly initialized.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The new name must not be the same as any existing list name.

Example

oListManager.Rename "{454799A2-312B-4F5F-90A0-F514FBA0EC5A}", "Tequila"

See Also

ListManager Object


ListManager.SetDesc

Use this method to provide a new description for a list.

Definition

Sub SetDesc(
listID As Variant,
newListDesc As String
)

Parameters

listID

A Variant that specifies the ID or name of the list.

newListDesc

A String that contains the description to be associated with the list.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_LM_LIST_BUSY | &H8C400008 | The specified list is currently busy with another operation.
E_LM_LIST_IN_FAILED_STATE | &H8C40001D | The specified list is in a FAILED state and may not be used for the operation.
E_LM_LIST_NOT_FOUND | &H8C400006 | The specified list does not exist.
E_LM_SQLERROR | &H8C400003 | Error while executing SQL/ADO operation.
OLE_E_BLANK | &H80040007 | The ListManager object has not been properly initialized.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Example

oListManager.SetDesc(listID, newListDesc)

See Also

ListManager Object


ListManager.SetListProperty

Use this method to set a property of a list.

Definition

Sub SetListProperty(
listID As Variant,
listPropertyName As String,
ListProp As Variant
)

Parameters

listID

A Variant that contains the ID or name of the list.

listPropertyName

A String that contains the property name (column of the lm_master table).

ListProp

A Variant that contains the value to set the property.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_LM_LIST_BUSY | &H8C400008 | The specified list is currently busy with another operation.
E_LM_LIST_IN_FAILED_STATE | &H8C40001D | The specified list is in a FAILED state and may not be used for the operation.
E_LM_LIST_MUST_BE_DYNAMIC | &H8C400012 | The operation requires a dynamic list and the specified list is not a dynamic list.
E_LM_LIST_NOT_FOUND | &H8C400006 | The specified list does not exist.
E_LM_LISTPROP_NOT_UPDATEABLE | &H8C400013 | The specified list property cannot be changed after the list has been created.
E_LM_SQLERROR | &H8C400003 | Error while executing SQL/ADO operation.
OLE_E_BLANK | &H80040007 | The ListManager object has not been properly initialized.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

This method is usually used to change properties of a dynamic list, such as the table name, connection string, or SQL query from which a dynamic list is created.

The following properties may be set by this method:

  • list_name

  • list_description

  • list_userflags

  • list_err_limit (dynamic lists only)

  • list_query (dynamic lists only)

  • list_source (dynamic lists only)

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

oListManager.SetListProperty "{454799A2-312B-4F5F-90A0-F514FBA0EC5A}", _
 "list_userflags", 12)

See Also

ListManager Object


ListManager.Status

The Status property is a read-only Long that contains the ListManager object status.

Definition

Property Status() As Long

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The following table shows the valid status codes and their descriptions.

Status | Value | Description
LMSTATUS_NEW | 0 | The ListManager object has been created but is not yet initialized.
LMSTATUS_READY | 1 | The ListManager object has been created and successfully initialized.
LMSTATUS_ERROR | -1 | The ListManager object failed to initialize.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ListManager Object


ListManager.Subtract

Use this method to subtract one mailing list from another mailing list, placing the result in a third list.

Definition

Sub Subtract(
srcList As Variant,
lessList As Variant,
resList As Variant,
errLimit As Long,
bAsync As Boolean,
Optional pvarOpID As Variant
)

Parameters

srcList

A Variant that contains the ID or name of the list from which elements will be subtracted.

lessList

A Variant that contains the ID or name of the less list.

resList

A Variant that contains the ID or name of the list into which the results of the subtraction operation will be placed.

errLimit

A Long that is not used.

bAsync

A Boolean that specifies whether the copy operation is performed synchronously or asynchronously. A value of True indicates asynchronous processing. A value of False indicates synchronous processing.

pvarOpID

An optional Variant used to return an Operation ID. This Operation ID is used in subsequent processing concerning this operation.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_LM_LIST_BUSY | &H8C400008 | The specified list is currently busy with another operation.
E_LM_LIST_IN_FAILED_STATE | &H8C40001D | The specified list is in a FAILED state and may not be used for the operation.
E_LM_LIST_NOT_FOUND | &H8C400006 | The specified list does not exist.
E_LM_MAILABLE_REQUIRED | &H8C400011 | The operation requires a mailable list and the specified list is not a mailable list.
E_LM_OPER_CANCELED | &H8C40000B | The operation was canceled.
E_LM_SQLERROR | &H8C400003 | Error while executing SQL/ADO operation.
OLE_E_BLANK | &H80040007 | The ListManager object has not been properly initialized.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The result list must exist prior to calling the method, however, any data in the list will be overwritten.

This method keys on the rcp_email column and thus, both the source (srcList parameter) and less (lessList parameter) lists must be Mailable lists (LISTFLAG_MAILABLE set to True). Records from the source list that do not have duplicate e-mail addresses (rcp_email) in the less list are copied to the result (resList parameter) list. Any existing data in the result list is deleted.

The parameter pvarOpID contains valid data only if the subtraction operation is performed asynchronously.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

oListManager.Subtract "{2B544800-4169-4C49-8713-1B794078B4C9}", _
 "{454799A2-312B-4F5F-90A0-F514FBA0EC5A}", _
 "{7131B794-5448-078B-B544-799A2311B79A}", 10, False

See Also

ListManager Object


ListManager.Union

Use this method to produce a union of two mailing lists, placing the result in a third mailing list. A union is a combination of the two lists with any duplicates eliminated.

Definition

Sub Union(
srcList As Variant,
addList As Variant,
resList As Variant,
errLimit As long,
bAsync As Boolean,
Optional pvarOpID As Variant
)

Parameters

srcList

A Variant that contains the ID or name of the source list.

addList

A Variant that contains the ID or name of the add list.

resList

A Variant that contains the ID or name of the list into which the results of the union operation will be placed.

errLimit

A Long that is not used.

bAsync

A Boolean that specifies whether the copy operation is performed synchronously or asynchronously. A value of True indicates asynchronous processing. A value of False indicates synchronous processing.

pvarOpID

An optional Variant used to return an Operation ID. This Operation ID is used in subsequent processing concerning this operation.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_LM_LIST_BUSY | &H8C400008 | The specified list is currently busy with another operation.
E_LM_LIST_IN_FAILED_STATE | &H8C40001D | The specified list is in a FAILED state and may not be used for the operation.
E_LM_LIST_NOT_FOUND | &H8C400006 | The specified list does not exist.
E_LM_MAILABLE_REQUIRED | &H8C400011 | The operation requires a mailable list and the specified list is not a mailable list.
E_LM_OPER_CANCELED | &H8C40000B | The operation was canceled.
E_LM_SQLERROR | &H8C400003 | Error while executing SQL/ADO operation.
OLE_E_BLANK | &H80040007 | The ListManager object has not been properly initialized.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The result list must exist prior to calling the method, however, any data in the list will be overwritten.

This method keys on the rcp_email column and thus, both the source (srcList parameter) and add (addList parameter) lists must be Mailable lists (LISTFLAG_MAILABLE set to True). All the records from the source list are copied to the result (resList parameter) list. All records from the add list that do not have duplicate e-mail addresses (rcp_email) in the source list are also copied to the result list. Any existing data in the result list is deleted.

The parameter pvarOpID contains valid data only if the union operation is performed asynchronously.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

oListManager.Union "{2B544800-4169-4C49-8713-1B794078B4C9}", _
 "{454799A2-312B-4F5F-90A0-F514FBA0EC5A}", _
 "{7131B794-5448-078B-B544-799A2311B79A}", 10, False

See Also

ListManager Object


ListManager.WaitOnOperation

Use this method to wait until an operation is complete or a specified time period has elapsed.

Definition

Sub WaitOnOperation(
varOpID As Variant,
Optional timeout As Long
)

Parameters

varOpID

A Variant that specifies the ID of the operation upon which to wait. For more information about where to obtain Operation IDs, see the Remarks section.

timeout

An optional Long that specifies a timeout. This method returns when either the specified operation completes, or when the number of seconds specified by timeout have elapsed, whichever happens first. A value of zero (the default) specifies an infinite time to wait for the operation to complete.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_LM_OPERATION_NOT_FOUND | &H8C400004 | The operation ID does not represent a currently running operation.
E_LM_SQLERROR | &H8C400003 | Error while executing SQL/ADO operation.
OLE_E_BLANK | &H80040007 | The ListManager object has not been properly initialized.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

This method cannot be called from a scripting language such as VBScript or JScript on an ASP page. ASP pages must use alternative techniques when dealing with asynchronous operations and should never wait on them explicitly.

The Operation ID passed to this method in the varOpID parameter can be obtained from any of the following calls when they are executed asynchronously:

  • Copy

  • CreateFromDWCalc

  • CreateFromFile

  • CreateFromSql

  • ExportToFile

  • ExportToSql

  • Subtract

  • Union

In addition, the Operation IDs of all known operations can be retrieved using the GetOperations method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

oListManager.WaitOnOperation "{454799A2-312B-4F5F-90A0-F514FBA0EC5A}", 900

See Also

ListManager Object


LRUCache Object

Use this object to support the creation, storage, and retrieval of name/value pairs, referred to as elements, from a cache in memory. The LRUCache object functions similarly to the Dictionary object, except that it only stores a limited number of elements, and internally ranks them according to use. When the cache is full and a new element needs to be added, the least recently used element is removed from the cache to make room for the new element.

ProgID: | Commerce.LRUCache (Externally creatable)
COM Class Name: | LRUCache
Type Library Name: | Microsoft Commerce 2000 Cache Manager Type Library
DLL Name: | mscscache.dll
Threading Model: | Both

The methods of the LRUCache object are shown in the following table.

Method | Description
Flush | Removes an element from the cache.
FlushAll | Removes all elements from the cache.
Insert | Inserts an element into the cache.
Lookup | Returns the value of an element in the cache when given the name of the element.
LookupObject | Returns an object in the cache when given the name of the object.
SetSize | Sets the maximum size of the cache.


LRUCache.Flush

Use this method to remove the specified element from the cache.

Definition

Sub Flush(
Optional bstrKey As String
)

Parameters

bstrKey

An optional String that contains the name of the element to be removed from the cache.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

If no element is specified, all elements are removed.

See Also

CacheManager Object

LRUCache Object


LRUCache.FlushAll

Use this method to remove all elements from the cache.

Definition

Sub FlushAll()

Parameters

None.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

See Also

CacheManager Object

LRUCache Object


LRUCache.Insert

Use this method to add an element to the cache.

Definition

Sub Insert(
bstrKey As String,
pvarValue As Variant
)

Parameters

bstrKey

A String that contains the name of the element to be added to the cache.

pvarValue

A Variant that contains the value of the element.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

'vManAd is a Variant that references an ad.
oLRUCache.Insert("ManufacturerAd", vManAd)

See Also

CacheManager Object

LRUCache Object


LRUCache.Lookup

Use this method to retrieve the value of an element from the cache.

Definition

Function Lookup(
bstrKey As String
) As Variant

Parameters

bstrKey

A String that contains the name of the element to be retrieved.

Return Values

If this method completes successfully, it returns a Variant that contains the value of the specified element.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' vFavAd is a Variant
vFavAd = myLRUCache.Lookup("Favorite Ad")

See Also

CacheManager Object

LRUCache Object


LRUCache.LookupObject

Use this method to retrieve an object from the cache.

Definition

Function LookupObject(
bstrKey As String
) As Object

Parameters

bstrKey

A String that contains the name of the object to be retrieved.

Return Values

If this method completes successfully, it returns an object.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

Set oMyObject = oLRUCache.LookupObject("My Object")

See Also

CacheManager Object

LRUCache Object


LRUCache.SetSize

Use this method to set the maximum size of the cache.

Definition

Sub SetSize(
lSize As Long
)

Parameters

lSize

A Long that specifies the size of the cache.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

See Also

CacheManager Object

LRUCache Object


MessageManager Object

Use this object to store error messages in multiple languages that the Order Processing pipeline (OPP) components use to describe error conditions generated during order processing.

ProgID: | Commerce.MessageManager (Externally creatable)
COM Class Name: | MSCSMessageManager_3_0
Type Library Name: | Commerce -- MSCSAspHelp Type Library
DLL Name: | MSCSAspHelp.dll
Threading Model: | Both

The single property of the MessageManager object is shown in the following table.

Property | Type | Description
defaultLanguage | String | Specifies the default message set for the MessageManager object. This property is read/write.

The methods of the MessageManager object are shown in the following table.

Method | Description
AddLanguage | Adds a new message set to the MessageManager object and associates that message set with a locale.
AddMessage | Adds a new message to the MessageManager object.
GetLocale | Returns the locale for the specified message set.
GetMessage | Returns the message associated with the specified message name constant.

See Also

Display Objects


MessageManager.AddLanguage

Use this method to add a message set to the MessageManager, and associate that message set with a locale. In subsequent calls to MessageManager object methods, the caller needs to identify the message set name, not the locale.

Any number of message sets can be associated with a single locale.

Definition

Sub AddLanguage(
bstrLanguage As String,
Locale As Long
)

Parameters

bstrLanguage

A String that contains the name for the message set to add to the MessageManager object.

Locale

A Long that uniquely identifies the locale to associate with the added message set.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oMessageManager is a Commerce.MessageManager object
oMessageManager.AddLanguage("usa", 1033)

See Also

MessageManager Object

MessageManager.DefaultLanguage

DataFunctions.Locale

MessageManager.GetMessage


MessageManager.AddMessage

Use this method to add a message to the MessageManager object.

Definition

Sub AddMessage(
bstrName As String,
bstrMessage As String,
vtLanguage As Variant
)

Parameters

bstrName

A String that contains the message name constant, which is a string that identifies the message to add. For a list of common messages and their constant names, see the Remarks section.

bstrMessage

A String that contains the text of the message to add.

vtLanguage

A Variant that contains the language name with which to associate the message. This value, if specified, must be a language name added through a previous call to the AddLanguage method. If this parameter is not supplied, the language specified in the DefaultLanguage property of the MessageManager object is used.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The following table lists the messages that are used by the default implementation of the OPP, showing the message name constant expected by the Order Processing pipeline (OOP) components that use these messages.

Message name constant | Used by OPP component | Added to this collection under this condition
pur_badplacedprice | RequiredItemAdjustPrice | _Basket_Errors when the price of an item does not correspond to the price contained in the OrderForm.
pur_badhandling | RequiredHandling | _Purchase_Errors when the handling cost for an order cannot be computed
pur_badpayment | RequiredPayment | _Purchase_Errors when authentication code (_payment_auth_code) is not set
pur_badshipping | RequiredShipping | _Purchase_Errors when the shipping for an order cannot be computed
pur_badsku | RequiredProdInfo | _Basket_Errors when a stockkeeping unit (SKU) in the OrderForm references an item that is not contained in the inventory for the site
pur_badtax | RequiredTax | _Purchase_Errors when the tax on a purchase cannot be computed
pur_badverify | RequiredTotal | _Purchase_Errors when the data stored by the ProcessVerifyWith method does not match the original data in the order form
pur_noitems | RequiredOrderCheck | _Purchase_Errors when there are no items in the OrderForm.
pur_out_of_stock | FlagInventory, LocalInventory | _Purchase_Errors when an item referenced in the OrderForm is out of stock.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oMessageManager is a Commerce.MessageManager object
oMessageManager.AddMessage("pur_out_of_stock", _
    "At least one item is out of stock.")

See Also

MessageManager Object

MessageManager.DefaultLanguage

MessageManager.GetMessage


MessageManager.DefaultLanguage

Use the DefaultLanguage property to specify the default message set for the MessageManager. When you use the GetMessage method, or use the AddMessage method to add messages to the MessageManager, without specifying a message set for those messages, then the messages are associated with the message set specified in this property.

Definition

Property DefaultLanguage As String

Parameters

None.

Error Values

This property sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

MessageManager Object

MessageManager.GetLocale


MessageManager.GetLocale

Use this method to return a number that identifies the locale for the specified message set.

Definition

Function GetLocale(
vtLanguage As Variant
) As Long

Parameters

vtLanguage

A Variant that contains the name of the message set for which you want to retrieve the locale. This message set must have been added to the MessageManager object through a previous call to the AddLanguage method.

Return Values

If this method completes successfully, it returns a Long used to identify the locale for the specified message set.

Error Values

This property sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Like the GetMessage method, the GetLocale method is usually not called from within a site. Instead, it is used by the pipeline component to retrieve the locale for a message that describes an error that the component has encountered.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oMessageManager is a Commerce.MessageManager object
oMessageManager.GetLocale("us")

See Also

MessageManager Object

MessageManager.GetMessage

MessageManager.AddLanguage


MessageManager.GetMessage

Use this method to return the text of the specified message.

Definition

Function GetMessage(
bstrName As String,
vtLanguage As Variant
) As String

Parameters

bstrName

A String that contains the message constant name of the message to return. This is the name associated with this message when it was added to the MessageManager object through a call to the AddMessage method.

vtLanguage

A Variant that specifies the name of the message set to which the message text belongs. This string specifies a message set that was added to the MessageManager object through a previous call to the AddLanguage method. If this parameter is not specified, or is NULL, the message is returned for the message set identified by the DefaultLanguage property of the MessageManager object.

Return Values

If this method completes successfully, it returns a String Variant that contains the text of the specified error message.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The GetMessage method is seldom called from within a site. Instead, it is used by pipeline components to retrieve messages that describe errors that have occurred.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oMessageManager is a Commerce.MessageManager object
oMessageManager.GetMessage("pur_out_of_stock", "us")

See Also

MessageManager Object

MessageManager.AddLanguage

MessageManager.GetLocale


MicroPipe Object

Use this object to run a single pipeline component from an Active Server Page (ASP) file without using a pipeline configuration file (.pcf).

ProgID: | Commerce.MicroPipe (Externally creatable)
COM Class Name: | CMicroPipeline
Type Library Name: | Microsoft Commerce 2000 MicroPipe Type Library
DLL Name: | micropipe.dll
Threading Model: | Both

The methods of the MicroPipe object are shown in the following table.

Method | Description
Execute | Runs the component indicated in the SetComponent method.
SetComponent | Indicates the pipeline component to load and execute.
SetLogFile | Identifies the file in which to log pipeline events.

Remarks

The MicroPipe object does not explicitly use Microsoft Transaction Server (MTS). To use transactions, mark the page as transacted or use the standard MtsTxPipline object. Distributed transactions have no meaning in the MicroPipe object because the object contains a single component.

Many pipeline components use configuration information in addition to the Context and Order dictionaries. Two common ways of passing this information to the component are:

  • To create a dictionary and pass the dictionary to the component.

  • To set individual or multiple properties directly.

The first method applies only to pipeline components that implement the IPipelineComponentAdmin interface. The second is common for components written in Microsoft Visual Basic, which usually do not implement the IPipelineComponentAdmin interface.

See Also

Pipeline Objects


MicroPipe.Execute

Use this method to run the pipeline component specified by the SetComponent method.

Definition

Function Execute(
pdispOrder As Object,
pdispContext As Object,
lFlags As Long
) As Long

Parameters

pdispOrder

A reference to a Dictionary object, usually an OrderForm object. The Order dictionary for the pipeline component to be run.

pdispContext

A reference to a Dictionary object. The Context dictionary for the pipeline component to be run.

lFlags

A Long integer. Reserved for future use. Must be set to zero (0).

Return Values

If this method completes successfully, it returns a Long integer indicating whether there were warnings or errors detected by the component. See the Error Values section for more details.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

In addition, the method returns one of the following three values:

Value | Description
1 | The pipeline component ran successfully.
2 | The pipeline component raised a warning. Generally, these are basket or user errors that would be reported to the user through the ASP page.
3 | The pipeline component failed to run.

Remarks

After the script has used the MicroPipe object, it should release the object by assigning Nothing to the object reference.

For more information about programming with pipeline objects, including code samples, see Pipeline Objects.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' pMicroPipeline is a Commerce.MicroPipeline object
' dOrder and dContext are Commerce.Dictionary objects

errVal = pMicropipeline.Execute(dOrder, dContext, 0)

See Also

MicroPipe Object

MicroPipe.SetComponent

MicroPipe.SetLogFile


MicroPipe.SetComponent

Use this method to specify the pipeline component to run.

Definition

Sub SetComponent(
pdispComponent As Object
)

Parameters

pdispComponent

A reference to the pipeline component to be run.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

A single MicroPipe object can be used to execute multiple components. Calling the SetComponent method on the MicroPipe object after setting and executing a different component earlier is permitted. In this case, the MicroPipe object releases the earlier component and sets up the new component in its place.

For more information about programming with pipeline objects, including code samples, see Pipeline Objects.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' pMicroPipeline is a Commerce.MicroPipeline object
' oCompPipe is an object that references the pipeline component
' to be run.

pMicropipeline.SetComponent(oCompPipe)

See Also

MicroPipe Object

MicroPipe.Execute

MicroPipe.SetLogFile


MicroPipe.SetLogFile

Use this method to identify the file in which to log the operations of the pipeline component.

Definition

Sub SetLogFile(
bstrFileName As String
)

Parameters

bstrFileName

A String containing the file name for logging.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

With logging, the MicroPipe object logs all of the read and write operations of the Dictionary and SimpleList objects. Errors are also recorded in the log. Because of the overhead involved, logging should be used only for debugging and should not be used in a production site.

The SetLogFile method should be called immediately before executing a pipeline. The SetLogFile method is exposed on the OrderGroup object as the LogFile property and should be called again before calling the RunPipe method.

For more information about programming with pipeline objects, including code samples, see Pipeline Objects.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' pMicroPipeline is a Commerce.MicroPipeline object

pMicroPipeline.SetLogFile("MicroPipeLog.txt")

See Also

MicroPipe Object

MicroPipe.Execute

MicroPipe.SetComponent


MtsPipeline Object

Use this object to execute a non-transacted Microsoft Commerce Server 2000 pipeline. The pipeline may be an Order Processing pipeline (OPP).

ProgID: | Commerce.MtsPipeline (Externally creatable)
COM Class Name: | CMtsPipeline
Type Library Name: | Microsoft Commerce 2000 Order Pipeline Type Library
DLL Name: | pipeline.dll
Threading Model: | Apartment

The methods of the MtsPipeline object are shown in the following table.

Method | Description
Execute | Runs the components in the pipeline.
LoadPipe | Loads a pipeline configuration file (.pcf) into the pipeline.
SetLogFile | Identifies the file in which to log pipeline events.

Remarks

The MtsPipeline object is registered under Microsoft Transaction Server (MTS) as "transactions not supported." Use this pipeline where transactions are not needed. For more information about transactions and pipelines, see Pipeline Basics.

The MtsPipeline is usually created on each page in which it is used.

The MtsPipeline is not a pooled pipeline. For more information about pooled pipelines, see About Pooled Pipelines.


MtsPipeline.Execute

Use this method to run the stages in the pipeline configuration file, which was previously specified by the LoadPipe method.

Definition

Function Execute(
lMode As Long,
pdispOrder As Object,
pdispContext As Object,
lFlags As Long
) As Long

Parameters

lMode

A Long indicating the mode in which to run the pipeline. This parameter is provided only for backward compatibility with Site Server 3.0 Commerce Edition sites. In Site Server 3.0 Commerce Edition and later, the mode is set by loading an appropriately configured pipeline with the LoadPipe method. Use a value of one (1). A value of zero (0) prevents any stages from running.

pdispOrder

A reference to a Dictionary object, usually an OrderForm object. The Order dictionary that will be used by the pipeline.

pdispContext

A reference to a Dictionary object. The Context dictionary that will be used by the pipeline.

lFlags

An unused Long parameter. Must be set to zero (0).

Return Values

If this method completes successfully, it returns a Long indicating whether there were warnings or errors detected by components in the pipeline. See the Error Values section for more details.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

In addition, the method returns one of the following three values:

Value | Description
1 | The pipeline ran successfully.
2 | A pipeline component raised a warning. Generally, these are basket or user errors that would be reported to the user through the ASP page.
3 | A pipeline component failed to run.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' pMtsPipeline is a Commerce.MtsPipeline object
' dOrder and dContext are Commerce.Dictionary objects

errVal = pMtsPipelineExecute(1, dOrder, dContext, 0)

See Also

MtsPipeline Object

MtsPipeline.LoadPipe

MtsPipeline.SetLogFile

PooledPipeline Object


MtsPipeline.LoadPipe

Use this method to load a pipeline configuration file (.pcf) into the pipeline.

Definition

Sub LoadPipe(
pszFileName As String
)

Parameters

pszFileName

A String containing the pipeline configuration file name.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The LoadPipe method must be called to initialize all pipelines.

The LoadPipe method fails if you attempt to load a pipeline configuration file designated for transactions (for use in the MtsTxPipeline object).

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' pMtsPipeline is a Commerce.MtsPipeline object

errVal = pMtsPipeline.Load("CustomShip.pcf")

See Also

MtsPipeline Object

MtsPipeline.Execute

MtsPipeline.SetLogFile

PooledPipeline Object


MtsPipeline.SetLogFile

Use this method to identify the file in which to log the operations of the pipeline component.

Note

  • This method is for use by developers who want to analyze pipeline configuration file information. Logging should never be used in a production environment: it degrades performance and may compromise the security of credit card numbers in non-set transactions.

Definition

Sub SetLogFile(
pszFileName As String
)

Parameters

pszFileName

A String containing the name of the file in which to log events.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

When logging is set, the pipeline logs the pipeline components that are called and the error values each component returns. The pipeline also logs all Dictionary and SimpleList object read and write operations.

Calling the method with an empty string turns off logging.

The SetLogFile method should be called immediately before executing a pipeline. The SetLogFile method is exposed on the OrderGroup object as the LogFile property and should be set before calling the RunPipe method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' pMtsPipeline is a Commerce.MtsPipeline object

errVal = pMtsPipeline.SetLogFile("CustomShipping.log")

' pOrderGroup is an OrderGroup object

pOrderGroup.LogFile = "CustomShipping.log"

See Also

MtsPipeline Object

MtsPipeline.Execute

MtsPipeline.LoadPipe

PooledPipeline Object


MtsTxPipeline Object

Use this object to execute a transacted Microsoft Commerce Server 2000 pipeline configuration. The pipeline may be an Order Processing pipeline (OPP).

ProgID: | Commerce.MtsTxPipeline (Externally creatable)
COM Class Name: | CTxPipeline
Type Library Name: | Microsoft Commerce 2000 Order Pipeline Type Library
DLL Name: | pipeline.dll
Threading Model: | Apartment

The methods of the MtsTxPipeline object are shown in the following table.

Method | Description
Execute | Runs the components in the pipeline.
LoadPipe | Loads a pipeline configuration file (.pcf) into the pipeline.
SetLogFile | Identifies the file in which to log pipeline events.

Remarks

The MtsTxPipeline is usually created on each page in which it is used.

The MtsTxPipeline object is registered under Microsoft Transaction Server (MTS) as "transactions required." This object holds a transaction that spans all components in the pipeline configuration. For more information about transactions and pipelines, see Pipeline Basics.

When used with a database, the MtsTxPipeline object requires an ODBC-compliant database that supports MTS.

The Microsoft Distributed Transaction Coordinator (MSDTC) service must be running in order to use the MtsTxPipeline object.

To verify that the Distributed Transaction Coordinator service is running

  1. Click Start, point to Programs, point to Administrative Tools, and then click Services.

  2. Scroll to Distributed Transaction Coordinator and verify that the Status is Started.


MtsTxPipeline.Execute

Use this method to run the stages in the pipeline configuration file, which was previously specified by the LoadPipe method.

Definition

Function Execute(
lMode As Long,
pdispOrder As Object,
pdispContext As Object,
lFlags As Long
) As Long

Parameters

lMode

A Long indicating the mode in which to run the pipeline. This parameter is provided only for backward compatibility with Site Server 3.0 Commerce Edition sites. In Site Server 3.0 Commerce Edition and later, the mode is set by loading an appropriately configured pipeline with LoadPipe. Use a value of one (1). A value of zero (0) prevents any stages from running.

pdispOrder

A reference to a Dictionary object. The Order dictionary that will be used by the pipeline, usually an OrderForm object.

pdispContext

A reference to a Dictionary object. The Context dictionary that will be used by the pipeline.

lFlags

An unused Long parameter. Must be set to zero (0).

Return Values

If this method completes successfully, it returns a Long indicating whether there were warnings or errors detected by components in the pipeline. See the Error Values section for more details.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

In addition, the method returns one of the following three values:

Value | Description
1 | The pipeline ran successfully.
2 | A pipeline component raised a warning. Generally, these are basket or user errors that would be reported to the user through the ASP page.
3 | A pipeline component failed to run.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' pMtsTxPipeline is a Commerce.MtsTxPipeline object
' dOrder and dContext are Commerce.Dictionary objects

errVal = pMtsTxPipeline.Execute(1, dOrder, dContext, 0)

See Also

MtsTxPipeline Object

MtsTxPipeline.LoadPipe

MtsTxPipeline.SetLogFile


MtsTxPipeline.LoadPipe

Use this method to load a pipeline configuration file (.pcf) into the pipeline.

Definition

Sub LoadPipe(
pszFileName As String
)

Parameters

pszFileName

A String containing the pipeline configuration file (.pcf) name.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The LoadPipe method must be called to initialize all pipelines.

The LoadPipe method fails if you attempt to load a configuration file designated for non-transacted pipelines.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' pMtsTxPipeline is a Commerce.MtsTxPipeline object

errVal = pMtsTxPipeline.LoadPipe("CustomShip.pcf")

See Also

MtsTxPipeline Object

MtsTxPipeline.Execute

MtsTxPipeline.SetLogFile


MtsTxPipeline.SetLogFile

Use this method to identify the file in which to log the operations of the pipeline component.

Note

  • This method is for use by developers who want to analyze pipeline configuration file information. Logging should never be used in a production environment: it degrades performance and may compromise the security of credit card numbers in non-set transactions.

Definition

Sub SetLogFile(
pszFileName As String
)

Parameters

pszFileName

A String containing the name of the file in which to log events.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

When logging is set, the pipeline logs the pipeline components that are called and the error values each component returns. The pipeline also logs all Dictionary and SimpleList object read and write operations.

Calling this method with an empty string turns off logging.

The SetLogFile method should be called immediately before executing a pipeline. The SetLogFile method is also exposed on the OrderGroup object as the LogFile property and should be called before calling its RunPipe method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' pMtsPipeline is a Commerce.MtsTxPipeline object

errVal = pMtsTxPipeline.SetLogFile("CustomShipping.log")

See Also

MtsTxPipeline Object

MtsTxPipeline.LoadPipe

MtsTxPipeline.Execute


OrderForm Object

The OrderForm object provides for the in-memory storage of user and purchase information. Commerce Server 2000 sites use the OrderForm object to store the items that a user has chosen to purchase, and to store receipt information that reflects the purchase history for a given user.

ProgID: | Commerce.OrderForm (Externally creatable)
COM Class Name: | COrderForm
Type Library Name: | Microsoft Commerce 2000 Core Components Type Library
DLL Name: | MscsCore.dll
Threading Model: | Both

The methods of the OrderForm object are shown in the following table.

Method | Description
AddItem | Adds the specified item to the items collection of the object.
ClearItems | Clears the items collection of the object.
ClearOrderForm | Clears the entire OrderForm object.

Remarks

The OrderForm object is defined internally as a structured group of SimpleList and Dictionary objects, and includes the methods required to add items, clear items, and clear the entire OrderForm object itself.

The base of the OrderForm object is a Dictionary object, which contains information that describes the entire order. This includes user information, such as the shopper ID, name, and address, as well as order cost information, such as purchase subtotal, tax, shipping, and total.

The OrderForm object does not directly support storage of its data on disk. The DBStorage and OrderGroupManager objects enable persistent storage of OrderForm object data.

A number of the elements in the base Dictionary object of the OrderForm object include underscore (_) characters. The appearance of an underscore character in an element name indicates that these items are not saved to the OrderForm storage for the site. These elements are saved instead to the receipt storage of the site when the purchase is finalized.

See Also

Business Process Objects

OrderGroup Object

OrderGroupManager Object

SimpleFindSearchInfo Object

SimpleFindResultInfo Object


OrderForm.AddItem

Use this method to add the specified item to the items collection of an OrderForm object. The items collection is a SimpleList object containing Dictionary objects.

Definition

Function AddItem(
varSKU As Variant,
lCount As Long,
lPlacedPrice As Long
) As Object

Parameters

varSKU

A Variant that contains the SKU of the item to add.

lCount

A Long that contains the item count.

lPlacedPrice

A Long that is reserved for future use. This parameter must be set to 0 (zero).

Return Values

If this method completes successfully, it returns an object reference that holds the Dictionary object that contains the added item.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' Order is a Commerce.OrderForm object; a quantity of 5 is
' being added of the product whose SKU is SKUnumber.
Order.AddItem("SKUnumber", 5,0)

See Also

OrderForm Object

OrderForm.ClearItems

OrderForm.ClearOrderForm


OrderForm.ClearItems

Use this method to clear the items collection of the OrderForm object.

Definition

Sub ClearItems()

Parameters

None.

Return Values

None.

Error Values

This property sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

A site uses the ClearItems method to respond to a user choosing to cancel a purchase. This method affects only the information in the items collection. Other OrderForm object information, such as _oadjust_subtotal and _total_total, is modified only if you run the Order Processing Pipeline (OPP) on this OrderForm object.

To empty the entire contents of the OrderForm object, call the ClearOrderForm method.

See Also

OrderForm Object

OrderForm.AddItem

OrderForm.ClearOrderForm


OrderForm.ClearOrderForm

Use this method to clear the entire OrderForm object.

Definition

Sub ClearOrderForm()

Parameters

None.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

See Also

OrderForm Object

OrderForm.AddItem

OrderForm.ClearItems


OrderGroup Object

The OrderGroup object is used in Commerce Server 2000 to store, access, and compute basket and order information for a site. The OrderGroupManager object works in conjunction with the OrderGroup object, providing search and other management operations for orders.

ProgID: | Commerce.OrderGroup (Externally creatable)
COM Class Name: | OrderGroup
Type Library Name: | Microsoft Commerce 2000 OrderGroup Type Library
DLL Name: | requisition.dll
Threading Model: | Apartment

The properties of the OrderGroup object are shown in the following table.

Property | Type | Description
LogFile | String | Log file name for pipeline runs. Allows pipeline logging when set to a non-empty string. This property is read/write.
SavePrefix | String | Specifies a key prefix that will prevent a dictionary entry from being saved to the database.
Value | Variant | Returns the OrderGroup object attributes. This property is read-only.

The methods of the OrderGroup object are shown in the following table.

Method | Description
AddItem | Adds an item to the specified OrderForm object.
AddItemsFromTemplate | Adds the line items associated with an on-disk OrderGroup to the current OrderGroup object.
AddOrderform | Adds an OrderForm object with all of its contents to the OrderGroup object.
AddXMLAsOrderForm | Converts an XML string to an OrderForm object and adds it to the OrderGroup object.
AggregateOrderFormValues | Iterates across all OrderForm objects, computes a total of the specified key, then stores the total at the OrderGroup level.
Clear | Clears the OrderGroup object of all OrderForm objects.
GetAddress | Gets the specified address dictionary object.
GetItemInfo | Gets a reference to the line item dictionary from the specified OrderForm at the specified index.
GetOrderFormAsXML | Converts an OrderForm object into an XML string.
GetOrderFormValue | Gets the OrderForm value specified by the supplied OrderForm key.
Initialize | Initializes the OrderGroup object.
LoadOrder | Loads the specified OrderGroup from the database.
LoadTemplate | Loads the specified template from the database.
LoadBasket | Loads the basket for the current user from the database.
PurgeUnreferencedAddresses | Removes all addresses in the OrderGroup object that are not being referenced by any line item shipping address.
PutItemValue | Puts the specified values into the specified keys of the line item.
PutOrderFormValue | Puts the specified values into the specified keys of the OrderForm object.
RemoveItem | Removes a line item from the specified OrderForm object. The item index specified indicates which line item to remove.
RemoveOrderForm | Removes the specified OrderForm object from the OrderGroup object.
RunPipe | Runs the Pipeline Component File on each OrderForm object in the OrderGroup object.
SaveAsBasket | Saves the OrderGroup object to the database with a basket status.
SaveAsOrder | Saves the OrderGroup object to the database with an order status.
SaveAsTemplate | Saves the OrderGroup object to the database with a template status.
SetAddress | Sets the OrderGroup object address dictionary values as specified by the address dictionary object supplied.
SetAddressFromFields | Sets the OrderGroup object address dictionary values as specified by the fields object supplied.
SetShippingAddress | Sets the shipping address to that referenced by the database address ID supplied.

See Also

Business Process Objects

OrderGroupManager Object

OrderForm Object

SimpleFindSearchInfo Object

SimpleFindResultInfo Object


OrderGroup.AddItem

Use this method to add a line item to the specified OrderForm object.

This method adds a line-item dictionary to the given OrderForm (the strOrderFormName parameter). If the strOrderFormName is not supplied, the parameter strOrderFormName defaults to "default"; if "default" does not exist, it is created. This method also increments the aggregated quantity total at the OrderGroup and OrderForm level.

Definition

Function AddItem(
dictItem As Object,
Optional strOrderFormName As Variant
) As Long

Parameters

dictItem

A Dictionary object that contains the line-item information.

strOrderFormName

A Variant that specifies the name of the OrderForm to add the item to. Depending on how a site is structured, you may choose to specify the vendor name of the item as the strOrderFormName. (This will result in items from different vendors being added to different OrderForms).

Return Values

If this method completes successfully, it returns a Long that specifies the index at which the item was added.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Note

  • Each line item that is added should contain a quantity.

  • If you are using the QueryCatalogInfo component in your pipeline, you will also need:
    • product_catalog

    • product_id

    • product_variant_id (if this is a product variant)

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' dDict is a Dictionary object
' lLineItemIndex is a Long
' sMyOrder is a String
' oOrderGroup is a Commerce.OrderGroup object
lLineItemIndex = oOrderGroup.AddItem(dDict, sMyOrder)

See Also

OrderGroup Object

OrderGroup.RemoveItem


OrderGroup.AddItemsFromTemplate

Use this method to add the line items associated with an on-disk OrderGroup to the current OrderGroup object.

This method iterates across all the OrderForms in the specified template and adds them to the current OrderGroup. If the OrderForms being added already exist, the line items on the template OrderGroup are simply added. When non-existing OrderForms are encountered, the method will add the OrderForm in its entirety to the OrderGroup including OrderForm-level dictionary values.

The OrderGroup keeps a counter of total line items at OrderForm and OrderGroup levels. For the OrderGroup level, it keeps track of the number of line items in all the OrderForms. This value is held under the key "total_lineitems".

Definition

Sub AddItemsFromTemplate(
OrderGroupID As String
)

Parameters

OrderGroupID

A String that specifies the OrderGroup ID for the template.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Note

  • It is the responsibility of the application to implement security. This method does not check that the user ID of the template is the same as the user ID specified in the initialization call.

This method also works on previously submitted orders and baskets, as well as OrderGroups with Template (Saved Order) status.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oOrderGroup is a Commerce.OrderGroup object
' myOGID is a GUID String
myOGID ="754C40C6-EAA9-454C-A8AB-02789FBE0FB9"
oOrderGroup.AddItemsFromTemplate(myOGID)

See Also

OrderGroup Object


OrderGroup.AddOrderform

Use this method to add an OrderForm with all of its contents to the OrderGroup object.

If the strOrderFormName is not supplied, it defaults to "default".

Definition

Sub AddOrderform(
orderform As Object,
Optional strOrderFormName As Variant
)

Parameters

orderform

A Dictionary object that contains the OrderForm object that will be added.

strOrderFormName

A Variant that specifies the OrderForm name.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' dOrderForm is a Dictionary object
' sMyOrderName is a string
' oOrderGroup is a Commerce.OrderGroup object
oOrderGroup.AddOrderform(dOrderForm,sMyOrderName)

See Also

OrderGroup Object


OrderGroup.AddXMLAsOrderForm

Use this method to add items previously saved as XML (by using the GetOrderformAsXML method) back into an OrderGroup.

Definition

Sub AddXMLAsOrderForm(
strXML As String,
nXMLLocale As Long,
Optional strOrderFormName As Variant
)

Parameters

strXML

A String that specifies the XML string containing the line items to add.

nXMLLocale

A Long that specifies the locale to use in the XML string conversion.

strOrderFormName

A Variant that specifies the OrderForm name to add.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Note

  • Use of the DictionaryXMLTransforms object is recommended when exchanging XML via BizTalk Server. DictionaryXMLTransforms allows you to write out XML to a well-defined schema.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oOrderGroup is a Commerce.OrderGroup object
' sXMLString is an string containing order-form data
' lLocale is a long specifying the locale to use in conversion
oOrderGroup.AddXMLAsOrderForm(sXMLString, lLocale)

See Also

OrderGroup Object

OrderGroup.GetOrderFormAsXML


OrderGroup.AggregateOrderFormValues

Use this method to iterate across all OrderForms, compute a total of the specified key, and store the total at the OrderGroup level.

Definition

Sub AggregateOrderFormValues(
strOrderFormKey As String,
strOrderGroupKey As String
)

Parameters

strOrderFormKey

A String that specifies the OrderForm key of the value to be aggregated.

strOrderGroupKey

A String that specifies the OrderGroup key of the value to which the aggregated total will be written.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oOrderGroup is a Commerce.OrderGroup object
oOrderGroup.AggregateOrderFormValues("saved_cy_handling_total", _
"_cy_handling_total")

See Also

OrderGroup Object


OrderGroup.Clear

Use this method to clear the OrderGroup object of all OrderForm objects and Address dictionaries.

Definition

Sub Clear()

Parameters

None.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

See Also

OrderGroup Object


OrderGroup.GetAddress

Use this method to get the specified address Dictionary object.

Definition

Function GetAddress(
strAddressId As String
) As Object

Parameters

strAddressId

A String that specifies the address ID.

Return Values

If the specified address is found, this method returns a reference to that dictionary, otherwise it returns a Nothing object.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oOrderGroup is a Commerce.OrderGroup object
' dDict is a Dictionary object

dDict = oOrderGroup.GetAddress("{C4F9C9CC-C33E-11D0-B8A0-00C04FB616C7}")

See Also

OrderGroup Object


OrderGroup.GetItemInfo

Use this method to get a reference to the line-item dictionary from the specified OrderForm at the specified index. If the strOrderFormName parameter is not supplied, it defaults to "default".

Definition

Function GetItemInfo(
nItemIndex As Long,
Optional strOrderFormName As Variant
) As Object

Parameters

nItemIndex

A Long that specifies the line-item index.

strOrderFormName

A Variant that specifies the OrderForm name.

Return Values

If this method completes successfully, it returns a Dictionary object that contains the line item information.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oOrderGroup is a Commerce.OrderGroup object
' dDict is a Dictionary object
dDict = oOrderGroup.GetItemInfo(3, "testOrderFormName")

See Also

OrderGroup Object


OrderGroup.GetOrderFormAsXML

Use this method to convert an OrderForm object into an XML string.

Definition

Function GetOrderFormAsXML(
nXMLLocale As String,
Optional strOrderFormName As Variant
) As String

Parameters

nXMLLocale

A String that specifies the locale used in the XML string conversion.

strOrderFormName

A Variant that specifies the OrderForm.

Return Values

If this method completes successfully, it returns a String that contains the XML string.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Note: Use of the DictionaryXMLTransforms object is recommended when exchanging XML via BizTalk Server. The DictionaryXMLTransforms object allows you to write out XML to a well-defined schema.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oOrderGroup is a Commerce.OrderGroup object
' lLocale is a valid Locale identifier
sXMLResultString is a string
sXMLResultString = oOrderGroup.GetOrderFormAsXML(lLocale, myOrderFormName)

See Also

OrderGroup Object

OrderGroup.AddXMLAsOrderForm


OrderGroup.GetOrderFormValue

Use this method to get an attribute from an OrderForm, based on a specified key.

Definition

Function GetOrderFormValue(
strKey As String,
Optional strOrderFormName As Variant
) As Variant

Parameters

strKey

A String that contains the key that specifies the attribute to get.

strOrderFormName

A Variant that specifies the OrderForm name.

Return Values

If this method completes successfully, it returns a Variant that contains the attribute.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

If the strOrderformName parameter is not supplied, the strOrderFormName parameter defaults to "default".

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oOrderGroup is a Commerce.OrderGroup object
vResult is a Variant

vResult = oOrderGroup.GetOrderFormValue(handling_total, _
"testOrderFormName")

See Also

OrderGroup Object


OrderGroup.Initialize

Use this method to initialize the OrderGroup object.

Definition

Sub Initialize(
strConnectionString As String,
strUser ID As String
)

Parameters

strConnectionString

A String that contains the database connection string.

strUser ID

A String that specifies the user ID. All Commerce Server 2000 user ID values are GUIDs.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Use this method to specify the connection string that the OrderGroup uses for its database operations. You also specify a user_id that the object will use as an OrderGroup_id when performing basket operations. This same user_id value will be stored in the g_User IDChangedBy field.

Note

  • If you are loading an OrderGroup on behalf of another user (for example as an administrator), you should specify the administrator user ID (or a placeholder user ID GUID which signifies administrative authority) so that g_UserDChangedBy is updated with the appropriate value when the OrderGroup is saved back to the database. If you wish to load an OrderGroup with a Basket status in the role of an administrator, you must specify strUser ID as the user ID of the user whose basket you wish to load. In this case g_User IDChangedBy will not be updated with an administrator user ID.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oOrderGrp is a Commerce.OrderGroup object
' sConnString is a valid connection string to the Commerce database
oOrderGrp.Initialize(sConnString, _
    "{D4F9C9CC-C33E-11D0-B8A0-00C04FB616C7}")

See Also

OrderGroup Object


OrderGroup.LoadBasket

Use this method to load the basket for the current user from the database. If the basket for the user id specified in the Initialize method cannot be found, this method initializes an empty in-memory basket.

Definition

Sub LoadBasket()

Parameters

None.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

See Also

OrderGroup Object

OrderGroup.LoadOrder

OrderGroup.LoadTemplate

OrderGroup.SaveAsBasket


OrderGroup.LoadOrder

Use this method to load an OrderGroup from disk. This method returns an error if the OrderGroup cannot be found.

Definition

Sub LoadOrder(
strOrderGroupID As String
)

Parameters

strOrderGroupID

A String that specifies the OrderGroupID of the OrderGroup to be loaded.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The LoadOrder method can be used to load any OrderGroup whose status does not equal basket or template.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oOrderGroup is a Commerce.OrderGroup object
oOrderGroup.LoadOrder("{EEF9C9CC-C33E-11D0-B8A0-00C04FB616C7}")

See Also

OrderGroup Object

OrderGroup.LoadBasket

OrderGroup.LoadTemplate

OrderGroup.Initialize

OrderGroup.SaveAsOrder


OrderGroup.LoadTemplate

Use this method to load the specified template from the database.

Definition

Sub LoadTemplate(
strOrderGroupID As String
)

Parameters

strOrderGroupID

A String that specifies the OrderGroupID of the template to be loaded.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Example

' oOrderGroup is a Commerce.OrderGroup object
oOrderGroup.LoadTemplate("{EEF9C9CC-C33E-11D0-B8A0-00C04FB616C7}")

See Also

OrderGroup Object

OrderGroup.LoadOrder

OrderGroup.LoadBasket

OrderGroup.SaveAsTemplate


OrderGroup.LogFile

The LogFile property is a read/write String that specifies the file name used for pipeline logging during the execution of the RunPipe method.

Definition

Property LogFile As String

Parameters

None.

Error Values

This property sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Set the LogFile parameter to an empty string ("") to disable logging.

See Also

OrderGroup Object


OrderGroup.PurgeUnreferencedAddresses

Use this method to remove all addresses in the OrderGroup object that are not being referenced by any line-item shipping_address_id or OrderForm billing_address_id.

Definition

Sub PurgeUnreferencedAddresses()

Parameters

None.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

See Also

OrderGroup Object


OrderGroup.PutItemValue

Use this method to put the specified values into the specified keys of the line item.

Definition

Sub PutItemValue(
strKey As String,
vtValue As Variant,
Optional bOverWrite As Boolean,
Optional nItemIndex As Variant,
Optional strOrderFormName As Variant
)

Parameters

strKey

A String that specifies the key whose attribute will store the value specified by the vtValue parameter.

vtValue

A VARIANT that specifies the value to store in the attribute of the key specified by the strKey parameter.

bOverWrite

A Boolean that indicates whether to overwrite the existing attribute of the key specified by the strKey parameter. A value of True indicates that the attribute will be overwritten. A value of False indicates that the attribute will not be overwritten.

nItemIndex

A Variant that specifies the line-item index.

strOrderFormName

A Variant that specifies the OrderForm name.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

If the line-item index is specified, this method sets the name value pair for the specified line item on the OrderForm specified in the strOrderFormName parameter. (The strOrderFormName parameter defaults to "default" if unspecified.)

If the line item index is not specified, this method sets the name value pair for all line items for the specified OrderForm. If no OrderForm name is specified, this method sets the name value pair for all line items in the OrderGroup.

If there is no OrderForm for the strOrderFormName specified in the strOrderFormName parameter, one is created.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oOrderGroup is a Commerce.OrderGroup object
oOrderGroup.PutItemValue(payment_method, credit_card, False)

See Also

OrderGroup Object


OrderGroup.PutOrderFormValue

Use this method to set an attribute on an OrderForm. If the strOrderFormName parameter is supplied, and the OrderForm does not exist in the OrderGroup, then a new OrderForm with the supplied name is created.

If strOrderFormName is not supplied, the parameter defaults to "default".

Definition

Sub PutOrderFormValue(
strKey As String,
vtValue As Variant,
Optional strOrderFormName As Variant
)

Parameters

strKey

A String that specifies the key whose attribute will store the value specified by the vtValue parameter.

vtValue

A VARIANT that specifies the value to store in the attribute of the key specified by the strKey parameter.

strOrderFormName

A Variant that specifies the OrderForm name.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oOrderGroup is a Commerce.OrderGroup object
oOrderGroup.PutOrderFormValue(handling_total, "$ 421.23")

See Also

OrderGroup Object


OrderGroup.RemoveItem

Use this method to remove a line item from the specified OrderForm object. The item index specified indicates which line item to remove.

If the the strOrderFormName parameter is not supplied, the strOrderFormName parameter defaults to "default".

Definition

Sub RemoveItem(
Optional nItemIndex As Variant,
Optional strOrderFormName As Variant
)

Parameters

nItemIndex

A Variant that specifies the line item index.

strOrderFormName

A Variant that specifies the OrderForm name.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

OrderGroup Object

OrderGroup.AddItem


OrderGroup.RemoveOrderForm

Use this method to remove the specified OrderForm from the OrderGroup object.

Definition

Sub RemoveOrderForm(
strOrderFormName As String
)

Parameters

strOrderFormName

A String that specifies the OrderForm to remove.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oOrderGroup is a Commerce.OrderGroup object
oOrderGroup.RemoveOrderForm("myOrderFormName")

See Also

OrderGroup Object

OrderGroup.AddOrderform


OrderGroup.RunPipe

Use this method to run the Pipeline Component File on each OrderForm in the OrderGroup object.

Definition

Function RunPipe(
strPCF As String,
strPipelineProgID As String,
oContext As Object
) As Long

Parameters

strPCF

A String that specifies the Pipeline Component File file path (for example, c:\SampleDir\SampleFile.pcf).

strPipelineProgID

A String that specifies the pipeline ProgID.

oContext

An object reference that specifies the pipeline context.

Return Values

If this method completes successfully, it returns a Long that specifies the maximum error level encountered by the pipeline runs.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

When OrderGroup.RunPipe is called, the OrderGroup object instantiates and runs the pipeline for each of its contained OrderForms. The pipeline objects themselves continue to be passed a regular OrderForm, as if they were run in a stand-alone pipeline. In fact, a pipeline component has no way of knowing whether it is running on an OrderForm within an OrderGroup, or on a stand-alone OrderForm.

There are cases where you want the pipeline component to know about all items in the OrderGroup, regardless of whether those items are from differing vendors (ie a discount component). If this is the case, you should not use the multiple-OrderForm feature of the OrderGroup object (adding all items to the same OrderForm). In these cases, you can use the Splitter pipeline component to produce views of items from different vendors on your OrderForm.

When calling OrderGroup.RunPipe, you can rely on the aggregation features of the OrderGroup to produce grand totals across all OrderForms. OrderGroup.RunPipe automatically aggregates many common fields. If you wish to aggregate additional fields, use OrderGroup.AggregateOrderformValues.

Additionally, this method computes grand totals across each OrderForm for each of the following properties:

Orderform Value | Grand Total on the OrderGroup
_cy_oadjust_subtotal | saved_cy_oadjust_subtotal
_cy_total_total | saved_cy_total_total
_cy_shipping_total | saved_cy_shipping_total
_cy_handling_total | saved_cy_handling_total
_cy_tax_total | saved_cy_tax_total
_cy_tax_included | saved_cy_tax_included

Many pipeline keys are prefixed by "_", which by default means they will not be persisted to the database. Occasionally, you may want to take snapshots of these keys, and by convention, the prefix "saved_" is used in this situation. By using the "saved_" prefix they can be referred to later and can be searched via SQL statements or the OrderGroupManager object. Copied keys should not necessarily be trusted as being up-to-date. Also, they should not be used by pipeline components directly.

The OrderGroup object has a LogFile property that can be used to set the log file for the RunPipe method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oOrderGroup is a Commerce.OrderGroup object
' lResult is a long
' oContext specifies the pipeline context
lResult = oOrderGroup.RunPipe("c:\myPCFFile.pcf", _
    "Commerce.PooledPipeline, oContext)

See Also

Pipeline Basics

OrderGroup Object

OrderGroup.LogFile


OrderGroup.SaveAsBasket

Use this method to save the OrderGroup object to the database with a basket status.

Definition

Function SaveAsBasket() As Variant

Parameters

None.

Return Values

If this method completes successfully, it returns a Variant that specifies the OrderGroupID.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The pvtRetVal parameter points to valid data only if the method completed successfully.

This method sets the OrderGroup status to "basket", and sets the OrderGroupID equal to the user ID.

If the OrderGroup object was not loaded from a basket, this method deletes any existing on-disk basket before inserting into the data storage.

If the OrderGroup object was loaded from a basket, this method performs an update or insert depending on whether the OrderGroup was found on-disk on the load call. If you load a template or order and call the SaveAsBasket method, the template or order which was originally loaded remains unchanged on disk.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oOrderGroup is a Commerce.OrderGroup object
' vResult is a Variant
vResult = oOrderGroup.SaveAsBasket()

See Also

OrderGroup Object

OrderGroup.LoadBasket

OrderGroup.SaveAsOrder

OrderGroup.SaveAsTemplate


OrderGroup.SaveAsOrder

Use this method to save the OrderGroup to the database with an order status.

Definition

Function SaveAsOrder(
Optional vtOutTrackingNumber As Variant
) As Variant

Parameters

vtOutTrackingNumber

A Variant that specifies the tracking number. If specified, this Variant must be a non-literal value; when the method returns, it will contain the tracking number.

Return Values

If this method completes successfully, it returns a Variant that specifies the OrderGroupID.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

This method sets the OrderGroup status to "order" if the current status is Template, Basket, or undefined. (All other states are left alone; this allows orders to be in many states, such as pending approval, rejected, and so on.) You can set the state to any value except basket or template before calling the SaveAsOrder method; this method will not overwrite the state.

If this is the first time the order is saved, a special field will be written that records the order creation date. If an OrderTrackingNumber already exists on the OrderForm (under the key order_number) before the save, a new one will not be generated. This feature allows for ERP-based tracking numbers.

If the OrderGroup was loaded from a template, or from a basket, this method will generate a new OrderGroupID and tracking number, and perform a database insert. If the OrderGroup does not yet exist on disk, this method will generate an OrderGroupID and tracking number and perform a database insert. If the OrderGroup was loaded from any other state, this method will perform a database update.

If you load a basket or template and call the SaveAsOrder method, the basket or template remains unchanged on disk. For this reason,a call to the SaveAsOrder method is typically followed by a call to OrderGroupManager.DeleteOrderGroupFromDisk.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oOrderGroup is a Commerce.OrderGroup object
' vResult is a Variant
' vTrackingNumber is a Variant
vResult = oOrderGroup.SaveAsOrder(vTrackingNumber)

See Also

OrderGroup Object

OrderGroup.SaveAsBasket

OrderGroup.SaveAsTemplate


OrderGroup.SaveAsTemplate

Use this method to save the OrderGroup to the database with a template status.

Definition

Function SaveAsTemplate(
Optional strTemplateName As Variant
) As Variant

Parameters

strTemplateName

A Variant that specifies the template name.

Return Values

If this method completes successfully, it returns a Variant that specifies the OrderGroupID of the template.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

This method updates the OrderGroup template name field if the strTemplateName parameter is supplied.

If you originally loaded the OrderGroup from another state (ie a basket) and call SaveAsTemplate method, the original OrderGroup remains on disk unchanged.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oOrderGroup is a Commerce.OrderGroup object
' vResult is a Variant
vResult = oOrderGroup.SaveAsTemplate()

See Also

OrderGroup Object

OrderGroup.SaveAsBasket

OrderGroup.SaveAsOrder


OrderGroup.SavePrefix

Specifies a key prefix that will prevent a dictionary entry from being saved to the database.

Definition

Property SavePrefix() As String

Parameters

None.

Error Values

This property sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The Value parameter contains valid data only if the property is accessed successfully.

No dictionary entry that has a key name that begins with the value of the SavePrefix property will be saved to the database. Assuming that the SavePrefix property is set to the underscore character ("_"), if the value of _adjusted_price is $ 200 and the value of total_price is $ 400, then $ 200 will not be persisted, but $ 400 will be persisted.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

OrderGroup Object


OrderGroup.SetAddress

Use this method to add a specified address dictionary to the OrderGroup Addresses collection of the OrderGroup.

Definition

Sub SetAddress(
strAddressId As String,
oAddressDict As Object
)

Parameters

strAddressId

A String that specifies the address ID of the address to be added.

oAddressDict

A Dictionary object that contains the address information to be added.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oOrderGroup is a Commerce.OrderGroup object
' oAddDict is an address Dictionary object
oOrderGroup.SetAddress("{AABBC9CC-C33E-11D0-B8A0-00C04FB616C7}", oAddDict)

See Also

OrderGroup Object

OrderGroup.SetAddressFromFields


OrderGroup.SetAddressFromFields

Use this method to set the OrderGroup address dictionary values as specified by the supplied Fields object. The column names in the field object will be mapped to dictionary keys names in the resultant address dictionary.

Definition

Sub SetAddressFromFields(
strAddressId As String,
flds As Object
)

Parameters

strAddressId

A String that specifies the address ID of the address dictionary to be added.

flds

A Fields object that contains the address information to be added.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oOG is a Commerce.OrderGroup object
' oFlds is a Fields object
oOG.SetAddressFromFields("{34ECC9CC-C33E-11D0-B8A0-00C04FB616C7}", _
    oFlds)

See Also

OrderGroup Object

OrderGroup.SetAddress


OrderGroup.SetShippingAddress

Use this method to set the shipping address id for the specified line items.

Definition

Sub SetShippingAddress(
address_id As String,
Optional bOverWrite As Boolean,
Optional nItemIndex As Variant,
Optional strOrderFormName As Variant
)

Parameters

address_id

A String that specifies the address ID to designate as the shipping address.

bOverWrite

A Boolean that indicates whether to overwrite the shipping_address_id, if it already exists. A value of True indicates that an overwrite should occur. A value of False indicates that an overwrite should not occur.

nItemIndex

A Variant that specifies the line item index where the shipping_address_id will be set. If not specified, all line items will be set.

strOrderFormName

A Variant that specifies the OrderForm to perform the operation. If not specified, all OrderForms will be used if nItemIndex is unspecified; otherwise, the "default" OrderForm will be used.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The bOverWrite, nItemIndex, and strOrderFormName parameters work in a way similar to the same parameters in the PutItemValue method. Before performing the set operations, this method first ensures that the address id exists.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oOrdGrp is a Commerce.OrderGroup object
oOrdGrp.SetShippingAddress(("{34ECC9CC-C33E-11D0-B8A0-00C04FB616C7}", _
    True, 4, "testOrderFormName")

See Also

OrderGroup Object


OrderGroup.Value

The Value property is a read-only Variant that contains the OrderGroup-level attributes as a dictionary.

Definition

Property Value As Variant

Parameters

None.

Error Values

This property sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The Value parameter contains valid data only if the property is accessed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

OrderGroup Object


OrderGroupManager Object

Use this object to manage OrderGroups and their contents. This object allows you to search for orders or baskets without having to use SQL queries. It also allows for OrderGroup deletions.

ProgID: | Commerce.OrderGroupManager (Externally creatable)
COM Class Name: | OrderGroupManager
Type Library Name: | Microsoft Commerce 2000 OrderGroup Type Library
DLL Name: | requisition.dll
Threading Model: | Apartment

The properties of the OrderGroupManager object are shown in the following table.

Property | Type | Description
OrderFormHeaderColumns | Variant | Returns a string of comma-separated OrderFormHeader table column names. This property is read-only.
OrderFormLineItemsColumns | Variant | Returns a string of comma-separated OrderFormLineItems table column names. This property is read-only.
OrderGroupColumns | Variant | Returns a string of comma-separated OrderGroup table column names. This property is read-only.

The methods of the OrderGroupManager object are shown in the following table.

Method | Description
DeleteOrderGroupFromDisk | Checks whether a connection to the database has been established for the specified OrderGroup then deletes the OrderGroup and all objects contained within it from the database.
Find | Performs a SQL search based on the specified SQL clause fragments.
FindTemplatesForUser | Finds an ADO recordset of OrderGroup templates for the specified user. Returns an ADO recordset of the search results.
Initialize | Creates a connection to the specified database.
SimpleDelete | Deletes all entries that meet the search criteria as specified by the supplied SimpleFindSearchInfo and SimpleFindResultInfo objects.
SimpleFind | Returns an ADO recordset of OrderGroup items based on the specified SimpleFindSearchInfo values and SimpleFindResultInfo values. These object values contain the search criteria.

See Also

Business Process Objects

OrderGroup Object

OrderForm Object

SimpleFindSearchInfo Object

SimpleFindResultInfo Object


OrderGroupManager.DeleteOrderGroupFromDisk

Use this method to check whether a connection to the database has been established for the specified OrderGroup, then delete the OrderGroup and all objects contained within it from the database.

Definition

Sub DeleteOrderGroupFromDisk(
OrderGroupID As String
)

Parameters

OrderGroupID

A String that contains the OrderGroup ID.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' sOrderGroupID is a string containing a valid OrderGroupID
' oOrderGroupManager is a Commerce OrderGroupManager object
oOrderGroupManager.DeleteOrderGroupFromDisk(sOrderGroupID)

See Also

OrderGroupManager Object


OrderGroupManager.Find

Use this method to perform a SQL search based on the specified SQL clause fragments.

Definition

Function Find(
OrderGroupCriteriaArray As Variant,
OrderFormCriteriaArray As Variant,
LineItemCriteriaArray As Variant,
Optional SearchDateTimeColumn As Variant,
Optional SearchDateTimeStart As Variant,
Optional SearchDateTimeEnd As Variant,
Optional StatusFilter As Long,
Optional JoinOrderFormInfo As Boolean,
Optional JoinLineItemInfo As Boolean,
Optional Columns As Variant,
Optional OrderGroupSortColumn As Variant,
Optional SortDirection As Variant,
Optional PageSize As Long,
Optional PageNumber As Long,
Optional outTotalRecordsFound As Variant
) As Variant

Parameters

OrderGroupCriteriaArray

A Variant that contains the SQL clause used to search for a specific set of OrderGroups.

OrderFormCriteriaArray

A Variant that contains the SQL clause used to search for a specific set of OrderForms.

LineItemCriteriaArray

A Variant that contains the SQL clause used to search for a specific set of line items.

SearchDateTimeColumn

A Variant that specifies the DateTime column name to search for; if left null, the DateTime column name does not become part of the search criteria. This parameter is optional.

SearchDateTimeStart

A Variant that specifies the DateTime start value to search for; if left null, the DateTime start value does not become part of the search criteria. This parameter is optional.

SearchDateTimeEnd

A Variant that specifies the DateTime end value to search for; if left null, the DateTime end value does not become part of the search criteria. This parameter is optional.

StatusFilter

A Long that stores the OrderGroup status. This parameter is optional.

JoinOrderFormInfo

A Boolean indicating whether to include the OrderFormHeader table in the results. This parameter is optional.

JoinLineItemInfo

A Boolean indicating whether to include the OrderFormLineItems table in the results. This parameter is optional.

Columns

A Variant that contains the names of the columns to return in addition to the default columns. This parameter is optional.

OrderGroupSortColumn

A Variant that contains the OrderGroup column name to sort on. This parameter is optional.

SortDirection

A Variant that contains the sort direction. This parameter is optional; possible values for this parameter are the SQL strings "ASC" or "DESC".

PageSize

With this method, you can implement a paging mechanism that allows you to page through your orders. (These could be viewed in a list sheet, for example.) The PageSize parameter is a Long that contains the number of line items per page. This parameter setting must be coordinated with the PageNumber parameter. This parameter is optional and has a default value of 20.

PageNumber

With this method, you can implement a paging mechanism that allows you to page through your orders. (These could be viewed in a list sheet, for example.) The PageNumber parameter is a Long that contains the page number to jump to. This parameter setting must be coordinated with the PageSize parameter. This parameter is optional.

outTotalRecordsFound

A Variant that specifies the total number of records found.

Return Values

If this method completes successfully, it returns Variant that contains the recordset containing the result set that meets the search criteria.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' vRecordset is a Variant
' vOrderGroupCriteriaArray is a Variant
' vOrderFormCriteriaArray is a Variant
' vLineItemCriteriaArray is a Variant
' oOrderGroupManager is a Commerce OrderGroupManager object
vRecordset = oOrderGroupManager.Find(vOrderGroupCriteriaArray, _
    vOrderFormCriteriaArray, vLineItemCriteriaArray)

See Also

OrderGroupManager Object

OrderGroupManager.SimpleFind


OrderGroupManager.FindTemplatesForUser

Use this method to build and return an ADO recordset of OrderGroup templates for the specified user.

Definition

Function FindTemplatesForUser(
UserId As String,
SearchDateTimeColumn As Variant,
SearchDateTimeStart As Variant,
SearchDateTimeEnd As Variant,
JoinOrderFormInfo As Variant,
JoinLineItemInfo As Variant,
Columns As Variant,
OrderGroupSortColumn As Variant,
SortDirection As Variant,
PageSize As Long,
PageNumber As Long,
outTotalRecordsFound As Variant
) As Variant

Parameters

UserId

A String that contains the User ID GUID.

SearchDateTimeColumn

A Variant that contains the DateTime column name to use in the search.

SearchDateTimeStart

A Variant that contains the search DateTime start value.

SearchDateTimeEnd

A Variant that contains the search DateTime end value.

JoinOrderFormInfo

A Boolean that indicates whether the OrderFormHeader table is included in the search. A value of True indicates that the table is included. A value of False indicates that the table is not included.

JoinLineItemInfo

A Boolean that indicates whether the OrderFormLineItem table is included in the search. A value of True indicates that the table is included. A value of False indicates that the table is not included.

Columns

A Variant that contains the names of columns that you want returned in addition to the default columns.

OrderGroupSortColumn

A Variant that contains the OrderGroup sort column.

SortDirection

A Variant that contains the sort direction.

PageSize

A Long that contains the page size.

PageNumber

A Long that contains the page number.

outTotalRecordsFound

A Variant that contains the total number of records found. This parameter is optional.

Return Values

If this method completes successfully, it returns a Variant that contains an ADO recordset of the search results.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oOrderGroupManager is a Commerce OrderGroupManager object
oOrderGroupManager.FindTemplatesForUser("{11223344-1122-1122-1122- _
    AABBCCDDEEFF}")

See Also

OrderGroupManager Object

Business Process Objects


OrderGroupManager.Initialize

Use this method to create a connection to the specified database.

Definition

Sub Initialize(
ConnectionString As Variant
)

Parameters

ConnectionString

A Variant that contains the database connection string.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' vConnectionString is a Variant containing a database connection string
' oOrderGroupManager is a Commerce OrderGroupManager object
oOrderGroupManager.Initialize(vConnectionString)

See Also

OrderGroupManager Object


OrderGroupManager.OrderFormHeaderColumns

The OrderFormHeaderColumns property is a read-only Variant that contains a collection of OrderFormHeader table column names.

Definition

Property OrderFormHeaderColumns As Variant

Parameters

None.

Error Values

This property sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

See Also

OrderGroupManager Object


OrderGroupManager.OrderFormLineItemsColumns

The OrderFormLineItemsColumns property is a read-only Variant that contains a collection of OrderFormLineItems table column names.

Definition

Property OrderFormLineItemsColumns As Variant

Parameters

None.

Error Values

This property sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

See Also

OrderGroupManager Object


OrderGroupManager.OrderGroupColumns

The OrderGroupColumns property is a read-only Variant that contains a collection of OrderGroup table column names.

Definition

Property OrderGroupColumns As Variant

Parameters

None.

Error Values

This property sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

See Also

OrderGroupManager Object


OrderGroupManager.SimpleDelete

Use this method to delete all entries that meet the search criteria as specified by the supplied SimpleFindSearchInfo and SimpleFindResultInfo objects.

Definition

Sub SimpleDelete(
sfSearchInfo As Object,
sfResultInfo As Object
)

Parameters

sfSearchInfo

A SimpleFindSearchInfo object that contains the search criteria.

sfResultInfo

A SimpleFindResultInfo object that contains the search criteria.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' vResult is a Variant
' oSimpleFindSearchInfo is a Commerce SimpleFindSearchInfo object
' oSimpleFindResultInfo is a Commerce SimpleFindResultInfo object
' oOrderGroupManager is a Commerce OrderGroupManager object
oOrderGroupManager.SimpleDelete(oSimpleFindSearchInfo, _
    oSimpleFindResultInfo)

See Also

OrderGroupManager Object


OrderGroupManager.SimpleFind

Use this method to retrieve an ADO recordset of OrderGroup items based on the specified SimpleFindSearchInfo and SimpleFindResultInfo object values. These object values contain the search criteria.

Definition

Function SimpleFind(
sfSearchInfo As Object,
sfResultInfo As Object,
Optional outTotalRecordsFound As Variant
) As Variant

Parameters

sfSearchInfo

A SimpleFindSearchInfo object that contains the search criteria.

sfResultInfo

A SimpleFindResultInfo object that contains the search criteria.

outTotalRecordsFound

A Variant that contains the total number of records found.

Return Values

If this method completes successfully, it returns an ADO recordset that contains the search result OrderGroup items.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

Dim oSFSearch, sReqID, oOGMgr
' oOGMgr is a Commerce.OrderGroupManager object
Set oSFSearch = Server.CreateObject("Commerce.SimpleFindSearchInfo")
' Search for this OrderGroup ID
sReqID ="754C40C6-EAA9-454C-A8AB-02789FBE0FB9"
oSFSearch.ordergroup_id = sReqID

Dim oSFResult
Set osfResult =Server.CreateObject("Commerce.SimpleFindResultInfo")
oSFResult.JoinLineItemInfo = True
oSFResult.JoinOrderFormInfo = True

Dim oRSResults
Set oRSResults=Server.CreateObject("ADODB.Recordset")

Set oRSResults= oOGMgr.SimpleFind(oSFSearch, oSFResult)

See Also

Business Process Objects

OrderGroupManager Object


OrderPipeline Object

Use this object to execute a Microsoft Commerce Server 2000 Content Selection pipeline. Order Processing pipelines (OPP) should generally use a PooledPipeline, PooledTxPipeline, MtxPipeline, or MtsTxPipeline object.

ProgID: | Commerce.OrderPipeline (Externally creatable)
COM Class Name: | COrderPipeline
Type Library Name: | Microsoft Commerce 2000 Order Pipeline Type Library
DLL Name: | pipeline.dll
Threading Model: | Both

Note

  • The OrderPipeline should be used in Content Selection pipelines because Content Selection pipelines do not require transactions and because the OrderPipeline is fully re-entrant by multiple threads. Other objects, such as MtsPipeline and MtsTxPipeline, must be used once, destroyed and recreated by each thread due to the rules of COM+ transactions.

The methods of the OrderPipeline object are shown in the following table.

Method | Description
LoadPipe | Loads a pipeline configuration file (.pcf) into the pipeline.
OrderExecute | Runs the components in the pipeline.
SetLogFile | Identifies the file in which to log pipeline events.

Remarks

The OrderPipeline object creates and executes an Order Processing pipeline (OPP). The OrderPipeline object is not registered under Microsoft Transaction Server (MTS).

The OrderPipeline is usually created in the Global.asa and put into an application collection.


OrderPipeline.LoadPipe

Use this method to load a pipeline configuration file (.pcf) into the pipeline.

Definition

Sub LoadPipe(
pszFileName As String
)

Parameters

pszFileName

A String containing the pipeline configuration file name.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The LoadPipe method must be called to initialize all pipelines.

The LoadPipe method fails if you attempt to load a pipeline configuration file designated for transactions (for use with the MtsTxPipeline or PooledTxPipeline objects).

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' pOrdPipeline is a Commerce.OrderPipeline object

errVal = pOrdPipeline.Load("CustomShip.pcf")

See Also

OrderPipeline Object

OrderPipeline.OrderExecute

OrderPipeline.SetLogFile


OrderPipeline.OrderExecute

Use this method to run the stages in the pipeline configuration file, which was previously specified by the LoadPipe method.

Definition

Function OrderExecute(
lMode As Long,
pdispOrder As IDispatch,
pdispContext As IDispatch,
lFlags As Long
) As Long

Parameters

lMode

A Long indicating the mode in which to run the pipeline. This parameter is provided only for backward compatibility with Site Server 2.0 sites.

pdispOrder

A reference to a Dictionary object, usually an OrderForm object. The Order dictionary that will be used by the pipeline.

pdispContext

A reference to a Dictionary object. The Context dictionary that will be used by the pipeline.

lFlags

An unused Long parameter. Must be set to zero (0).

Return Values

If this method completes successfully, it returns a Long indicating whether there were warnings or errors detected by components in the pipeline. See the Error Values section for more details.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

In addition, the method returns one of the following three values:

Value | Description
1 | The pipeline ran successfully.
2 | A pipeline component raised a warning. Generally, these are basket or user errors that would be reported to the user through the ASP page.
3 | A pipeline component failed to run.

Remarks

The lMode parameter is included only for backward compatibility with sites created in Site Server 2.0. In Site Server 3.0 Commerce Edition and later, the selection of pipeline stages is made by loading an appropriate pipeline configuration file with the LoadPipe method. Commerce Server 2000 applications should use the value one (1) for this parameter; zero (0) will cause no stages to run.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' pOrdPipeline is a Commerce.OrderPipeline object
' lMode is a Long
' dOrder and dContext are Commerce.Dictionary objects

errVal = pOrdPipeline.Execute(l, dOrder, dContext, 0)

See Also

OrderPipeline Object

OrderPipeline.LoadPipe

OrderPipeline.SetLogFile


OrderPipeline.SetLogFile

Use this method to identify the file in which to log the operations of the pipeline component.

Note

  • This method is for use by developers who want to analyze pipeline configuration file information. Logging should never be used in a production environment: it degrades performance and may compromise the security of credit card numbers in non-set transactions.

Definition

Sub SetLogFile(
pszFileName As String
)

Parameters

pszFileName

A String containing the name of the file in which to log events.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

When logging is set, the pipeline logs the pipeline components that are called and the error values each component returns. The pipeline also logs all Dictionary and SimpleList object read and write operations.

Calling this method with an empty string turns off logging.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' pOrdPipeline is a Commerce.OrderPipeline object

errVal = pOrdPipeline.SetLogFile("CustomShipping.log")

See Also

OrderPipeline Object

OrderPipeline.LoadPipe

OrderPipeline.OrderExecute


Page Object

Use this object to simplify forms processing in Active Server Pages (ASP).

ProgID: | Commerce.Page (Externally creatable)
COM Class Name: | MSCSPage_3_0
Type Library Name: | Commerce -- MSCSAspHelp Type Library
DLL Name: | MSCSAspHelp.dll
Threading Model: | Both

Important

  • This object is included for backward compatibility with Site Server 3.0 Commerce Edition. For more information, see the AuthManager and AppFrameWork objects, which provide similar functionality to many of the methods in this object.

The Page object methods fall into the following categories:

  • Formatting methods. These methods include Encode, Option, and Check. These methods make it possible for you to easily format HTML page items, and where applicable, to determine HTML item values based upon a run-time evaluation of other variables used in your page.

  • Validation methods. These methods begin with Request. They are used to retrieve values from a URL query string, convert the values to given data types based on a locale value, and validate these values against a specified range.

The single property of the Page object is shown in the following table.

Property | Type | Description
Context | IDispatch | A value that contains the Microsoft Internet Information Services (IIS) scripting context. This property is read-only.

The methods of the Page object are shown in the following table.

Method | Description
Check | Generates the word CHECKED for use in an HTML page based upon a supplied value.
Encode | Encodes text in HTML.
GetShopperId | Returns the unique shopper ID for the current shopper.
HTMLEncode | Encodes text in HTML.
Option | Generates an option button on a page.
ProcessVerifyWith | Copies the contents of hidden fields created using the VerifyWith method into an OrderForm object's _verify_with Dictionary object.
PutShopperId | Writes the specified shopper ID for use in a URL or a secure URL (or as a cookie).
RequestDate | Retrieves a value from a URL query string or form post variable and converts it to a date value (Date Variant), based on the specified or default locale.
RequestDateTime | Retrieves a value from a URL query string or form post variable and converts it to a date/time value (Date Variant), based on the specified or default locale.
RequestDefault | Retrieves a value from a URL query string or form post variable and returns the value as a string.
RequestFloat | Retrieves a value from a URL query string or form post variable and converts it to a floating-point value, based on the specified or default locale. It then checks the value against a specified range and validates the value, based on the specified locale.
RequestMoneyAsNumber | Retrieves a value from a URL query string or form post variable and converts it to a number in the base monetary units of the specified or default locale.
RequestNumber | Retrieves a value from a URL query string or form post variable and converts it to a number, based on the specified or default locale.
RequestString | Retrieves a value from a URL query string or form post variable and performs string processing on it, based on the specified locale.
RequestTime | Retrieves a value from a URL query string or form post variable and converts the string to a Date Variant, based on the specified or default locale.
SiteRoot | Returns the physical directory that contains the Commerce Server site.
SURL | Generates a secure URL based on the local path to a file. This URL includes the shopper ID, where applicable.
SURLPrefix | Returns the secure root domain, which can be used as the prefix of a complete URL.
URL | Generates a full URL based on the local path to a file. This URL can include arguments and the shopper ID, where applicable.
URLArgs | Generates a series of query string arguments appropriate for passing in a URL.
URLEncode | Applies URL encoding rules to a specified string.
URLPrefix | Returns the non-secure root domain, which can be used as the prefix to a complete URL.
URLShopperArgs | Generates a series of query string arguments appropriate for passing in a URL. It also includes in the arguments the shopper ID if the StandardSManager has been initialized to URL mode.
VerifyWith | Sends outputs to the page hidden fields that contain verification values.
VirtualDirectory | Returns the name of the s for the site.

See Also

Backward Compatibility Objects

AppFrameWork Object

AuthManager Object


Page.Check

Use this method to generate the word CHECKED into a page if the value specified in the vtCheck parameter is a nonzero value. CHECKED is a parameter to an HTML <INPUT> tag, which sets a check box or radio button to selected when the form first loads.

Important

  • This method is included for backwards compatibility with Site Server 3.0 Commerce Edition.

Definition

Function Check(
vtCheck As Variant
) As String

Parameters

vtCheck

A Variant that contains the expression that is evaluated to determine whether the word CHECKED should be inserted at the location on a page where the call to Check appears.

Return Values

If this method completes successfully, it returns a String that contains the string "CHECKED" or "".

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' The following example could be used in an ASP file
' to generate three radio buttons in an HTML form:
' oPage is a Commerce.Page object
<% my_color="Green" %>
<INPUT TYPE="RADIO" NAME="CONTROL1" VALUE="0"<% = _
    oPage.Check(my_color="Red")%>>Red
<INPUT TYPE="RADIO" NAME="CONTROL1" VALUE="1"<% = _
    oPage.Check(my_color="Green")%>>Green
<INPUT TYPE="RADIO" NAME="CONTROL1" VALUE="2"<% = _
    oPage.Check(my_color="Blue")%>>Blue
' Assuming that my_color contains "Green" this produces
' the following HTML output:
<INPUT TYPE="RADIO" NAME="CONTROL1" VALUE="0">Red
<INPUT TYPE="RADIO" NAME="CONTROL1" VALUE="1"CHECKED>Green
<INPUT TYPE="RADIO" NAME="CONTROL1" VALUE="2">Blue
' This HTML output produces three radio buttons labeled Red,
' Green, and Blue, with the Green option selected.

See Also

Page Object

Page.Option


Page.Context

The Context property is a read-only property that contains the ASP scripting context.

Normally, the contents of the Context property do not need to be retrieved. The Context property is used only as a parameter to other Commerce Server methods that need access to the ASP scripting context.

Important

  • This method is included for backwards compatibility with Site Server 3.0 Commerce Edition.

Definition

Property Context As Object

Parameters

None.

Error Values

This property sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

See Also

Page Object


Page.Encode

Use this method to apply HTML encoding to the specified text string.

This method is identical to the HTMLEncode method, which is the preferred name for this function. The Encode method applies HTML encoding to the specified text string. Characters in the string, such as "<" and "&" that have special meanings in HTML, are converted into their HTML equivalents, such as &lt; and &amp; so that they will be displayed correctly by the client browser.

Important

  • This method is included for backwards compatibility with Site Server 3.0 Commerce Edition.

Definition

Function Encode(
vtValue As Variant
) As String

Parameters

vtValue

A Variant that contains the text string to encode.

Return Values

If this method completes successfully, it returns a String that contains encoded HTML text.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oPage is a Commerce.Page object
' sEncoded is a String
' vOriginal is a String Variant
sEncoded = oPage.Encode(vOriginal)

See Also

Page Object

Page.HTMLEncode


Page.GetShopperId

This method returns the unique shopper ID for the current user. (The shopper ID is returned from a URL query string or a cookie, depending on the initialization mode of the StandardSManager for the site.)

If the current customer does not have a shopper ID, GetShopperID returns NULL.

Important

  • This method is included for backwards compatibility with Site Server 3.0 Commerce Edition. See the AuthManager object, which provides similar functionality to that found in the GetShopperID method. Using the AuthManager methods is the preferred way of adding this type of functionality to your site, and will ensure better compatibility with future versions of Microsoft Commerce Server.

Definition

Function GetShopperId() As Variant

Parameters

None.

Return Values

If this method completes successfully, it returns a Variant that contains the shopper ID.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

See Also

Page Object

StandardSManager Object

AuthManager Object

Page.PutShopperId


Page.HTMLEncode

Use this method to apply HTML encoding to the specified text string. Its typical use is to display the contents of text fields contained in the database in HTML. Characters in the string, such as "<" and "&" that have special meanings in HTML, are converted into their HTML equivalents, such as &lt; and &amp; so that they will be displayed correctly by the client browser.

Important

  • This method is included for backwards compatibility with Site Server 3.0 Commerce Edition.

Definition

Function HTMLEncode(
vtValue As Variant
) As String

Parameters

vtValue

A String Variant that contains the text string to encode.

Return Values

If this method completes successfully, it returns a String that contains encoded HTML text.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

If the text field to be displayed already contains HTML encoding, do not use the HTMLEncode method. For example, suppose your product_description field contains HTML-encoded text such as "The <I>Classic Diner Clock</I> brings the age of the &quot;Golden Oldies&quot; to your kitchen." This string uses the <I> tag to format italic text and the &quot; sequence to display quotation marks when displayed by the client browser. Because the string is already coded in HTML, you do not need to encode it again. Double-encoding the string would produce incorrect results.

The Page.HTMLEncode method is identical to the Page.Encode method, but the HTMLEncode method is the preferred name. The method is similar to Server.HTMLEncode except that the Page.HTMLEncode method handles NULL values by returning an empty string (the Server.HTMLEncode method fails when the vtValue parameter is NULL). This distinction is important because database queries can return NULL.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oPage is a Commerce.Page object
Assume that the company_name field contains the name Freeman & Sons
' The following HTML example displays the contents of the company_name
' field as an <H1> tag:
<H1><% = oPage.HTMLEncode(companyinfo.company_name) %></H1>
' This example returns the following HTML string:

<H1>Freeman &amp; Sons</H1>

See Also

Page Object

Page.URLEncode


Page.Option

Use this method to generate an OPTION item in an HTML form selection list, and then assign it the value and selection state that you specify. Although this functionality can be created without the Option method, using the method can speed your site development.

Important

  • This method is included for backwards compatibility with Site Server 3.0 Commerce Edition. See the AppFrameWork object, which provides similar functionality to that found in this method. Using the AppFrameWork methods is the preferred way of adding this type of functionality to your site, and will ensure better compatibility with future versions of Microsoft Commerce Server.

Definition

Function Option(
vtVal1 As Variant,
vtVal2 As Variant
) As String

Parameters

vtVal1

A Variant that contains the value of the option in the selection list.

vtVal2

A Variant that contains a value that indicates whether the list option is the selected option. If vtVal2 is equal to vtVal1, then the HTML keyword SELECTED is inserted in the definition of the option list.

Return Values

If this method completes successfully, it returns a String that contains the OPTION item.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oPage is a Commerce.Page object
' The following example generates a selection field in an
' HTML form to enable the customer to select the expiration
' year of the credit card. The Option method generates
 <OPTION VALUE="> tags and marks the current year
as selected:
iyear = Year(date) %>

<SELECT NAME="_cc_expyear">
    <% = oPage.Option(2000, iyear) %> 2000
    <% = oPage.Option(2001, iyear) %> 2001
    <% = oPage.Option(2002, iyear) %> 2002
    <% = oPage.Option(2003, iyear) %> 2003
</SELECT>
' Following is the HTML output that is produced by the ASP script
'  shown previously, assuming that the current year is 2001:
<SELECT NAME="_cc_expyear">
    <OPTION VALUE="2000"> 2000
    <OPTION VALUE="2001" SELECTED> 2001
    <OPTION VALUE="2002"> 2002
    <OPTION VALUE="2003"> 2003
</SELECT>

See Also

Page Object

Page.Check


Page.ProcessVerifyWith

Use this method in an ASP file that is activated when the shopper submits an HTML form containing an order. The ProcessVerifyWith method reads the posted contents of hidden fields in the HTML form that were created using the VerifyWith method and writes these values into a Dictionary object. This Dictionary object, called _verify_with, is stored in the OrderForm object.

When the pipeline processes the OrderForm, the contents of the _verify_with Dictionary object are compared to the original values of the fields in the OrderForm object to ensure that a page has not been altered between presentation and final purchase.

If the fields do not match, the RequiredTotal pipeline component generates an error, using the MessageManager message name constant pur_badverify.

Important

  • This method is included for backwards compatibility with Site Server 3.0 Commerce Edition. See the AppFrameWork object, which provides similar functionality to that found in this method. Using the AppFrameWork methods is the preferred way of adding this type of functionality to your site, and will ensure better compatibility with future versions of Microsoft Commerce Server.

Definition

Sub ProcessVerifyWith(
pdispOrder As Object
)

Parameters

pdispOrder

An object reference that supplies the OrderForm object that contains the basket for the current shopper.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oPage is a Commerce.Page object
' oOrderForm is a Commerce.Page object

call oPage.ProcessVerifyWith(oOrderForm)

See Also

Page Object

Page.VerifyWith

Message Manager Object

OrderForm Object


Page.PutShopperId

Use this method to write the specified shopper ID to a cookie, and/or store it for use in a URL or secure URL, depending on the initialization mode of the StandardSManager for the site.

Important

  • This method is included for backwards compatibility with Site Server 3.0 Commerce Edition. See the AuthManager object, which provides similar functionality to that found in the PutShopperID method. Using the AuthManager methods is the preferred way of adding this type of functionality to your site, and will ensure better compatibility with future versions of Microsoft Commerce Server.

Definition

Sub PutShopperId(
bstrShopperID As String
)

Parameters

bstrShopperID

A String that contains the shopper ID.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Where the PutShopperID method will store the specified shopper ID depends upon the StandardSManager initialization mode. In URL mode, this method writes the shopper ID to the request, so that the URL and SURL methods add the shopper ID to a query string in the URL from this page.

If the shopper ID is stored in a URL query string, you can retrieve it by passing the value you set for the application-level MSCSSIDURLKey to the IIS Request object.

If you initialize the StandardSManager in URL mode, you cannot use the StandardSManager's implementation of PutShopperID to store the shopper ID on the client system. Instead, you must use the implementation from the Page object.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oPage is a Commerce.Page object
' sShopperID is a String containing the shopper ID GUID
oPage.PutShopperID(sShopperID)

See Also

Page Object

StandardSManager Object

AuthManager Object

Page.GetShopperId

Page.SURL

Page.URL


Page.RequestDate

Use this method to retrieve a value from a URL query string or form post variable and convert it to a date value (Date Variant), based on the specified or default locale.

Optionally, RequestDate also checks the date against a specified date range.

Important

  • This method is included for backwards compatibility with Site Server 3.0 Commerce Edition. See the AppFrameWork object, which provides similar functionality to that found in this method. Using the AppFrameWork methods is the preferred way of adding this type of functionality to your site, and will ensure better compatibility with future versions of Microsoft Commerce Server.

Definition

Function RequestDate(
bstrName As String,
vtDefault As Variant,
vtMin As Variant,
vtMax As Variant,
vtLocal As Variant
) As Variant

Parameters

bstrName

A String that contains the name of the URL query string or form-post variable to retrieve.

vtDefault

A Variant that contains the date to return if the requested URL query string or form-post variable does not exist or contains no value. If this parameter is not supplied, the method returns NULL. The default cannot contain DateTime or Time values. This parameter is optional.

vtMin

A Variant that contains a date value that specifies the low end of the range against which to validate the value of the bstrName parameter. The default value is NULL, indicating that this parameter is ignored. If the converted date is less than vtMin, the method returns NULL. This parameter is optional.

vtMax

A Variant that contains a date value that specifies the high end of the range against which to validate the value of the bstrName parameter. The default value is NULL, indicating that this parameter is ignored. If the converted value is greater than vtMax, the method returns NULL. This parameter is optional.

vtLocale

A Variant that that contains a number that specifies the locale to use to convert the date. If this value is not specified, the RequestDate method uses the value of the Locale property of the DataFunctions object. This parameter is optional.

Return Values

If this method completes successfully, it returns a Date Variant that contains the processed date value.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oPage is a Commerce.Page object
' This example assumes that the date value is entered using
' the following form:
<FORM METHOD ="POST" ACTION="PROCESS.ASP">
<INPUT TYPE="Text" NAME="Date">
<INPUT TYPE="SUBMIT" NAME="ACTION" VALUE="Send Info">
</FORM>
If the user enters the date into the form and clicks the Send Info button, the value of this form field can be retrieved by the RequestDate method as follows:
vDate = Page.RequestDate("Date", "2/27/01", "1/1/01", "12/31/01", 1033)

See Also

Page Object

DataFunctions.Locale

Page.RequestDateTime

DataFunctions.ConvertDateString

DataFunctions.Date


Page.RequestDateTime

Use this method to retrieve a value from a URL query string or form post variable and convert it to a date/time value (Date Variant), based on the specified or default locale.

Important

  • This method is included for backwards compatibility with Site Server 3.0 Commerce Edition. See the AppFrameWork object, which provides similar functionality to that found in this method. Using the AppFrameWork methods is the preferred way of adding this type of functionality to your site, and will ensure better compatibility with future versions of Microsoft Commerce Server.

Definition

Function RequestDateTime(
bstrName As String,
vtDefault As Variant,
vtMin As Variant,
vtMax As Variant,
vtLocal As Variant
) As Variant

Parameters

bstrName

A String that contains the name of the URL query string or form-post variable to retrieve.

vtDefault

A Variant that contains the value to return if the requested URL query string or form-post variable does not exist or contains no value. If this parameter is not supplied, the method returns NULL. The default cannot contain Time values. This parameter is optional.

vtMin

A Variant that contains a DateTime value that specifies the low end of the range against which to validate the value of the bstrName parameter. The default value is NULL, indicating that this parameter is ignored. If the converted date is less than vtMin, the method returns NULL. This parameter is optional.

vtMax

A Variant that contains a DateTime value that specifies the high end of the range against which to validate the value of the bstrName parameter. The default value is NULL, indicating that this parameter is ignored. If the converted value is greater than vtMax, the method returns NULL. This parameter is optional.

vtLocale

A Variant that contains the number that identifies the locale to be used to convert the date/time string. If this parameter is not specified, the RequestDateTime method uses the value of the Locale property of the DataFunctions object. This parameter is optional.

Return Values

If this method completes successfully, it returns a Variant that contains a date/time value.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oPage is a Commerce.Page object
' This example assumes that the date-time value is entered using
' the following form:
<FORM METHOD ="POST" ACTION="PROCESS.ASP">
<INPUT TYPE="Text" NAME="DateTime">
<INPUT TYPE="SUBMIT" NAME="ACTION" VALUE="Send Info">
</FORM>
' If the user enters the date into the form and clicks the
' Send Info button, the value of this form field can be
' retrieved by the RequestDateTime method as follows:
vDate = oPage.RequestDateTime("DateTime", "1/1/01 12:00:01 AM", "1/1/01 _
    12:00:01 AM", "12/31/01 11:59:59 PM", 1033)

See Also

Page Object

DataFunctions.Locale

Page.RequestDate

DataFunctions.ConvertDateTimeString

Page.RequestTime


Page.RequestDefault

Use this method to retrieve a value from a URL query string or form post variable and return the value as a string.

Important

  • This method is included for backwards compatibility with Site Server 3.0 Commerce Edition.

Definition

Function RequestDefault(
bstrName As String,
vtDefault As Variant
) As Variant

Parameters

bstrName

A String that contains the name of the URL query string variable to retrieve.

vtDefault

A VARIANT that contains the value to return if the requested URL query string or form post variable contains an empty or a NULL value, or is not present in the request string. If this parameter is not supplied, the method returns NULL.

Return Values

If this method completes successfully, it returns a Variant that contains the processed value.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

This method is designed so that if a field on a form is blank, or the form does not contain the field, the value returned by default is NULL. NULL is generally the appropriate value to store to a database when a value is not present. If you need the result to be an empty string in the case of a missing value, supply an empty string as the Default parameter.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' The following example attempts to retrieve the value for
' the URL query string variable shopper_phone. Because no
' Default argument is supplied, if this URL query string
' variable has no value, the call returns Null.
' vShopper_phone is a Variant
' oPage is a Commerce.Page object
vShopper_phone = oPage.RequestDefault("shopper_phone")

See Also

Page Object


Page.RequestFloat

Use this method to retrieve a value from a URL query string or form post variable and convert it to a floating-point value, based on the specified or default locale.

Optionally, the RequestFloat method also checks the converted number against the specified range.

Important

  • This method is included for backwards compatibility with Site Server 3.0 Commerce Edition. See the AppFrameWork object, which provides similar functionality to that found in this method. Using the AppFrameWork methods is the preferred way of adding this type of functionality to your site, and will ensure better compatibility with future versions of Microsoft Commerce Server.

Definition

Function RequestFloat(
bstrName As String,
vtDefault As Variant,
vtMin As Variant,
vtMax As Variant,
vtLocal As Variant
) As Variant

Parameters

bstrName

A String that contains the name of the URL query string or form-post variable to retrieve.

vtDefault

A Variant that contains the value to return if the requested URL query string or form-post variable is not present or contains no value. If this parameter is not supplied, the method returns NULL. This parameter is optional.

vtMin

A Variant that contains the number that specifies the low end of the range of values against which to validate the converted value. The default value is NULL, indicating that this parameter is ignored. If the converted value is less than vtMin, the method returns NULL. This parameter is optional.

vtMax

A Variant that contains the number that specifies the high end of the range of values against which to validate the converted value. The default value is NULL, indicating that this parameter is ignored. If the converted value is greater than vtMax, the method returns NULL. This parameter is optional.

vtLocale

A Variant that contains the number that identifies the locale to use to convert the value. If this value is not specified, the RequestFloat method uses the value of the Locale property of the DataFunctions object. This parameter is optional.

Return Values

If this method completes successfully, it returns a Variant containing the floating-point value.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oPage is a Commerce.Page object
' vFloat is a Variant
' This example assumes that the float value is entered using
' the following form:
<FORM METHOD ="POST" ACTION="PROCESS.ASP">
<INPUT TYPE="Text" NAME="Float">
<INPUT TYPE="SUBMIT" NAME="ACTION" VALUE="Send Info">
</FORM>
' If the user enters the number into the form and clicks the
' Send Info button, the value of this form field can be
' retrieved by the RequestFloat method as follows:
vFloat = oPage.RequestFloat("Float", 0, 0, 100, 1033)

See Also

Page Object

DataFunctions.Locale

Page.RequestNumber

DataFunctions.ConvertFloatString

DataFunctions.Float

DataFunctions.Float

Page.RequestNumber


Page.RequestMoneyAsNumber

Use this method to retrieve a value from a URL query string or form post variable and convert it to a number in the base monetary units of the specified or default locale.

This method is used for backwards compatibility with Site Server 3.0 Commerce Edition sites, and relies on the Site Server 3.0 Commerce Edition monetary format.

Important

  • This method is included for backwards compatibility with Site Server 3.0 Commerce Edition. See the AppFrameWork object, which provides similar functionality to that found in this method. Using the AppFrameWork methods is the preferred way of adding this type of functionality to your site, and will ensure better compatibility with future versions of Microsoft Commerce Server.

Definition

Function RequestMoneyAsNumber(
bstrName As String,
vtDefault As Variant,
vtMin As Variant,
vtMax As Variant,
vtLocal As Variant
) As Variant

Parameters

bstrName

A String that contains the name of the URL-query string or form-post variable to retrieve.

vtDefault

A Variant that contains the value to return if the requested URL-query string or form-post variable is not present or contains no value. If this parameter is also not supplied, the method returns NULL. If the default value is a string value, it will be converted into the base monetary value; otherwise, it is assumed that the value is in base monetary units. This parameter is optional.

vtMin

A Variant that contains the monetary value that specifies the low end of the range against which to validate the converted value. If the variant is of type VT_NULL, the vtMin parameter value is not considered in the validation process. A value in base monetary units is expected for the vtMin parameter. If the converted value is less than vtMin, the method returns NULL. This parameter is optional.

vtMax

A Variant that specifies the high end of the range against which to validate the converted value. A value in base monetary units is expected for the vtMax parameter. If the converted value is greater than vtMax, the method returns NULL. This parameter is optional.

vtLocale

A Variant that contains the number that specifies the locale to use to convert the bstrName parameter. If this parameter is not used, the RequestMoneyAsNumber method uses the value of the Locale property of the DataFunctions object. This parameter is optional.

Return Values

If this method completes successfully, it returns a Variant that contains a number in the base monetary units of the specified or default locale.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

This method is used for backwards compatibility with Site Server 3.0 Commerce Edition sites, and relies on the Site Server 3.0 Commerce Edition monetary format.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oPage is a Commerce.Page object
' In the following example, the value of a field on the purchase
' form (filled out by the customer) is read into the
' variable list_price. The vtMax argument is the upper limit
' of a Variant variable. Using this value as the upper limit and
' zero (0) as the lower limit of the range check ensures that
' the value is not negative:
list_price = oPage .RequestMoneyAsNumber("list_price", 0, 0, _
    100, 1033)

See Also

Page Object

DataFunctions.Locale

DataFunctions.ConvertMoneyStringToNumber

DataFunctions.Money

Page.RequestFloat

Page.RequestNumber


Page.RequestNumber

Use this method to retrieve a value from a URL query string or form post variable and convert it to a number based on the specified or default locale.

Optionally, the RequestNumber method checks the converted number against the specified range and validates it based on the specified locale.

Important

  • This method is included for backwards compatibility with Site Server 3.0 Commerce Edition. See the AppFrameWork object, which provides similar functionality to that found in this method. Using the AppFrameWork methods is the preferred way of adding this type of functionality to your site, and will ensure better compatibility with future versions of Microsoft Commerce Server.

Definition

Function RequestNumber(
bstrName As String,
vtDefault As Variant,
vtMin As Variant,
vtMax As Variant,
vtLocal As Variant
) As Variant

Parameters

bstrName

A String that contains the name of the URL-query string or form-post variable to retrieve.

vtDefault

A Variant that contains the value to return if the requested URL-query string or form-post variable is not present or contains no value. If this parameter is not supplied, the method returns NULL. This parameter is optional.

vtMin

A Variant that contains the number value that specifies the low end of the range against which to validate the converted value. If the converted value is less than vtMin, then NULL is returned. This parameter is optional.

vtMax

A Variant that contains the number value that specifies the high end of the range against which to validate the converted value. If the converted value is greater than vtMax, then NULL is returned. If the converted value is greater than vtMax, the method returns NULL. This parameter is optional.

vtLocale

A Variant that contains the number that specifies the locale to use to convert the bstrName parameter. If this parameter is not used, the RequestNumber method uses the value of the Locale property of the DataFunctions object. This parameter is optional.

Return Values

If this method completes successfully, it returns a Variant that contains the converted number.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oPage is a Commerce.Page object
' In the following example, the value of a field on the purchase
' form (filled out by the customer) is read into the
' variable cc_expmonth. Because the Default parameter is specified
' as 7, RequestNumber will return 7 if the field is empty
' or missing.
cc_expmonth = oPage.RequestNumber("_cc_expmonth", 7, 1, 12)

See Also

Page Object

DataFunctions.Locale

Page.RequestFloat

DataFunctions.ConvertNumberString

DataFunctions.Number

DataFunctions.ValidateNumber


Page.RequestString

Use this method to retrieve a value from a URL query string or form post variable and perform string processing on it, based on the specified locale.

This processing may involve stripping out leading and trailing white spaces, stripping out carriage returns, checking the length of the string against a specified range, and validating the string based on the specified or default locale.

Important

  • This method is included for backwards compatibility with Site Server 3.0 Commerce Edition. See the AppFrameWork object, which provides similar functionality to that found in this method. Using the AppFrameWork methods is the preferred way of adding this type of functionality to your site, and will ensure better compatibility with future versions of Microsoft Commerce Server.

Definition

Function RequestString(
bstrName As String,
vtDefault As Variant,
vtMin As Variant,
vtMax As Variant,
vtStripWhite As Variant,
vtStripReturn As Variant,
vtCase As Variant,
vtLocal As Variant
) As Variant

Parameters

bstrName

A String that contains the name of the URL-query string or form-post variable to retrieve.

vtDefault

A Variant that contains the string to return if the specified URL-query string or form-post variable does not exist or contains no value. If this parameter is not supplied, the method returns NULL. This parameter is optional.

vtMin

A Variant that contains the number that indicates the minimum length against which the length of the bstrName parameter must be validated. If the variant is of type vtMissing, the vtMin parameter value is not considered in the validation process. This parameter is optional. If this value is invalid or length of the bstrName/vtDefault parameter is not in range, the method returns NULL.

vtMax

A Variant that contains the number that indicates the maximum length against which the length of the bstrName parameter must be validated. If the variant is of type vtMissing, the vtMax parameter value is not considered in the validation process. If this value is invalid or length of the bstrName/vtDefault parameter is not in range, the method returns NULL. This parameter is optional.

vtStripWhite

A Variant that contains a Boolean value that indicates whether leading and trailing white spaces should be stripped from the string. The default value is True. This parameter is optional.

vtStripReturn

A Variant that contains a Boolean value that indicates whether carriage returns should be stripped from the string. The default value is True. This parameter is optional.

vtCase

A Variant that contains the number that indicates the case to which the string should be converted. The default value is zero (0), which results in no modification to the case of the string. If the vtCase parameter is one (1), the string is converted to uppercase. If the vtCase parameter is two (2), the string is converted to lowercase. This parameter is optional.

vtLocal

A Variant that contains the number that specifies the locale to be used as the basis of the conversion. If this value is not specified, the RequestString method uses the value of the Locale property of the DataFunctions object. This parameter is optional.

Return Values

If this method completes successfully, it returns a Variant that contains the processed string.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oPage is a Commerce.Page object
' vString is a Variant
' This example assumes that the string value is entered using
' the following form:
<FORM METHOD ="POST" ACTION="PROCESS.ASP">
<INPUT TYPE="Text" NAME="String">
<INPUT TYPE="SUBMIT" NAME="ACTION" VALUE="Send Info">
</FORM>
' If the user enters the string into the form and clicks the
' Send Info button, the value of this form field can be
' retrieved by the RequestString method as follows:
vString = oPage.RequestString("String", "Default String", _
    1, 100, True, True, 0, 1033)
' In this example, the string is checked that it it contains
' between 1 and 100 characters; all leading and trailing white
' spaces are removed, all carriage returns are removed, , no
' modification is made to character case, and the string is
' converted according to the locale 1033 (USA). If no string is
' input, the string "Default String" will be loaded into the
' variable vString.

See Also

Page Object

DataFunctions.Locale


Page.RequestTime

Use this method to retrieve a value from a URL query string or form post variable and convert the string to a Date Variant, based on the specified or default locale.

Important

  • This method is included for backwards compatibility with Site Server 3.0 Commerce Edition. See the AppFrameWork object, which provides similar functionality to that found in this method. Using the AppFrameWork methods is the preferred way of adding this type of functionality to your site, and will ensure better compatibility with future versions of Microsoft Commerce Server.

Definition

Function RequestTime(
bstrName As String,
vtDefault As Variant,
vtMin As Variant,
vtMax As Variant,
vtLocal As Variant
) As Variant

Parameters

bstrName

A String that contains the name of the URL-query string or form post-variable to retrieve.

vtDefault

A Variant that contains the string to return if the specified URL-query string or form-post variable does not exist or contains no value. If this parameter is not supplied, the method returns NULL. The default cannot contain DateTime or Date values. This parameter is optional.

vtMin

A Variant that contains the time value that specifies the low end of the range against which to validate the bstrName parameter. If the converted value is less than vtMin, the method returns NULL. The default is no low-end validation. This parameter is optional.

vtMax

A Variant that contains the time value that specifies the high end of the range against which to validate the bstrName parameter. The default is no high-end validation. If the converted value is greater than vtMax, the method returns NULL. This parameter is optional.

vtLocale

A Variant that contains the number that specifies the locale to use to convert the DateTime value. If this value is not specified, the RequestTime method uses the value of the Locale property of the DataFunctions object. This parameter is optional.

Return Values

If this method completes successfully, it returns a Variant that contains the date.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oPage is a Commerce.Page object
' This example assumes that the -time value is entered using
' the following form:
<FORM METHOD ="POST" ACTION="PROCESS.ASP">
<INPUT TYPE="Text" NAME="Time">
<INPUT TYPE="SUBMIT" NAME="ACTION" VALUE="Send Info">
</FORM>
If the user enters the date into the form and clicks the Send Info button, the value of this form field can be retrieved by the RequestTime method as follows:
vTime = oPage.RequestTime("Time", "12:00:01 AM", "12:00:01 AM", _
 "11:59:59 PM", 1033)

See Also

Page Object

DataFunctions.Locale

DataFunctions_4_0::ConvertTimeString

Page.RequestDate


Page.SiteRoot

Use this method to return the physical directory that contains the Commerce Server site.

Important

  • This method is included for backwards compatibility with Site Server 3.0 Commerce Edition.

Definition

Function SiteRoot() As String

Parameters

None.

Return Values

If this method completes successfully, it returns a String that contains the physical directory path.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

See Also

Page Object

Page.VirtualDirectory


Page.SURL

Use this method to generate a properly formatted secure HTTP URL (SURL) based on the provided file name and an optional list of name/value arguments. The formatted URL includes the server name, the virtual directory in which the file is stored (taken from the context in which the Web site is running), and the name of the file itself.

Additionally, if the StandardSManager for the application is initialized in URL mode, the SURL method uses the value stored in the MSCSSIDUrlKey Application object variable as the name in a name/value pair, the value of which is the current customer's shopper ID.

Important

  • This method is included for backwards compatibility with Site Server 3.0 Commerce Edition. See the AuthManager object, which provides similar functionality to that found in the SURL method. Using the AuthManager methods is the preferred way of adding this type of functionality to your site, and will ensure better compatibility with future versions of Microsoft Commerce Server.

Definition

Function SURL(
bstrPath As String
) As String

Parameters

bstrPath

A String that contains the name of the file for the SURL to reference.

Return Values

If this method completes successfully, it returns String that contains a properly formatted secure HTTP URL.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

During application development, you can set the Site.DisableHTTPS property to one (1), which causes the SURL method to use the InsecureHostName value as the host name. The SURL method generates a secure URL only if Site.DisableHTTPS is set to zero (0).

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

The following example is from the MySite Purchase.asp file.

<FORM METHOD="POST"
    ACTION =<% = Page.SURL("xt_orderform_purchase.asp" %)
If the hostname is www.microsoft.com, the preceding example
' produces the following URL:
https://www.microsoft.com/MySite/xt_orderform_purchase.asp

See Also

Page Object

StandardSManager Object

AuthManager Object

Page.URL


Page.SURLPrefix

Use this method to return the secure root domain as determined by the MSCSSecureHostName value. The returned string can be used as the prefix of a complete URL.

Important

  • This method is included for backwards compatibility with Site Server 3.0 Commerce Edition. See the AuthManager object, which provides similar functionality to that found in the SURLPrefix method. Using the AuthManager methods is the preferred way of adding this type of functionality to your site, and will ensure better compatibility with future versions of Microsoft Commerce Server.

Definition

Function SURLPrefix() As String

Parameters

None.

Return Values

If this method completes successfully, it returns a String that contains the secure root domain string.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

During application development, you can set the DisableHTTPS property of the site dictionary to one (1), which causes the SURLPrefix method to use the InsecureHostName value as the host name. The SURLPrefix method generates a secure URL only if Site.DisableHTTPS is set to zero (0).

See Also

Page Object

StandardSManager Object

AuthManager Object

Page.URLPrefix

Page.SURL

Page.URLShopperArgs

Page.URLArgs

Page.VirtualDirectory


Page.URL

Use this method to generate a URL based on the specified file name and an optional list of name/value arguments. This URL includes the server name, the virtual directory in which the file is stored, and the name of the file itself.

Additionally, if the StandardSManager for the application is initialized in URL mode, the URL method uses the value stored in the Application object's MSCSSIDUrlKey variable as the name in a name/value pair, the value of which is the current shopper ID.

The method applies URL encoding to the values passed in.

Important

  • This method is included for backwards compatibility with Site Server 3.0 Commerce Edition. See the AuthManager object, which provides similar functionality to that found in the URL method. Using the AuthManager methods is the preferred way of adding this type of functionality to your site, and will ensure better compatibility with future versions of Microsoft Commerce Server.

Definition

Function URL(
bstrPath As String
) As String

Parameters

bstrPath

A String that contains the name of the file to reference in the URL.

Return Values

If this method completes successfully, it returns a String that contains the encoded value.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' The URL method spares the site builder the need to map a file
' to the HTTP path to that file. For example, assume the
following call to URL:
<%= oPage.URL("filename.asp") %>
' This call resolves to the correct HTTP path to
' filename.asp as follows:
http://host_name/virtual_directory/filename.asp
' The value for host_name is determined by the contents of the
' site dictionary's InsecureHostName value. The virtual_directory
' is determined automatically from the scripting context.

See Also

Page Object

AuthManager Object

Page.SURL


Page.URLArgs

Use this method to generate a series of query string arguments in an appropriate form for passing in a URL. The method applies URL encoding to the values passed in.

Important

  • This method is included for backwards compatibility with Site Server 3.0 Commerce Edition. See the AuthManager object, which provides similar functionality to that found in the URLArgs method. Using the AuthManager methods is the preferred way of adding this type of functionality to your site, and will ensure better compatibility with future versions of Microsoft Commerce Server.

Definition

Function URLArgs() As String

Parameters

None.

Return Values

If this method completes successfully, it returns a String that contains the series of query string arguments.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

See Also

Page Object

AuthManager Object

Page.VirtualDirectory

Page.SURL

Page.SURLPrefix

Page.URL

Page.URLShopperArgs


Page.URLEncode

Use this method to apply URL-encoding rules, including escape characters, to a specified string. An encoded URL string may be passed in a URL as a query string argument.

Important

  • This method is included for backwards compatibility with Site Server 3.0 Commerce Edition. See the AuthManager object, which provides similar functionality to that found in the URLEncode method. Using the AuthManager methods is the preferred way of adding this type of functionality to your site, and will ensure better compatibility with future versions of Microsoft Commerce Server.

Definition

Function URLEncode(
vtValue As Variant
) As String

Parameters

vtValue

A Variant that contains the string to be encoded.

Return Values

If this method completes successfully, it returns a URL-encoded String.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Strings that contain certain characters, such as spaces, slashes (/), or percentage symbols (%), cannot be passed as URL query arguments. URL encoding encodes these characters as escaped text so that they can be passed in a URL.

The Page.URLEncode method is equivalent to the Server.URLEncode method, except that the Page.URLEncode method handles NULL values by returning an empty string. (The Server.URLEncode method fails when the String parameter is NULL). This distinction is important because database queries can return NULL.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' Suppose that a variable called referringURL contains the URL _
' http://www.microsoft.com, which is to be passed as a query
' string argument in another URL.
' The following script:
<A HREF="Sample.asp?referringURL=<% =
    oPage.URLEncode(referringURL) %>">My link</A>
' generates the following HTML:
<A HREF="Sample.asp?referringURL= _
http%3A%2F%2Fwww%2Emicrosoft%2Ecom">My link</A>
' The receiving page (Sample.asp) can use the Request method to
' get the value of the variable. The method converts the string
' back to its original form and returns it to the script on the page.

See Also

Page Object

AuthManager Object

Page.HTMLEncode


Page.URLPrefix

Use this method to return the root domain as determined by the InsecureHostName value. The returned string can be used as the prefix to a complete URL.

Important

  • This method is included for backwards compatibility with Site Server 3.0 Commerce Edition. See the AuthManager object, which provides similar functionality to that found in the URLPrefix method. Using the AuthManager methods is the preferred way of adding this type of functionality to your site, and will ensure better compatibility with future versions of Microsoft Commerce Server.

Definition

Function URLPrefix() As String

Parameters

None.

Return Values

If this method completes successfully, it returns a String that contains the root domain string.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

To generate the domain for the secure host, use the Page.SURLPrefix method.

See Also

Page Object

AuthManager Object

Page.SURLPrefix

Page.VirtualDirectory

Page.SURL

Page.SURLPrefix

Page.URL

Page.URLShopperArgs

Page.URLArgs


Page.URLShopperArgs

Use this method to generate a series of query string arguments in an appropriate form for passing in a URL, and include in the arguments the shopper ID if the StandardSManager has been initialized to URL mode. The URLShopperArgs method URL-encodes the values passed in.

Important

  • This method is included for backwards compatibility with Site Server 3.0 Commerce Edition. See the AuthManager object, which provides similar functionality to that found in the URLShopperArgs method. Using the AuthManager methods is the preferred way of adding this type of functionality to your site, and will ensure better compatibility with future versions of Microsoft Commerce Server.

Definition

Function URLShopperArgs() As String

Parameters

None.

Return Values

If this method completes successfully, it returns a String that contains the series of query string arguments.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The URLShopperArgs method appends the current customer's shopper ID to the URL argument list. The name of the argument passed in the URL is stored in the Application object's MSCSSIDUrlKey variable.

See Also

Page Object

AuthManager Object


Page.VerifyWith

Use this method to output HTML tags in the form <INPUT TYPE="HIDDEN"> in an HTML form. These hidden fields contain specified values from the OrderForm object to be used to verify that an order has not been altered between presentation of the OrderForm and final purchase. When the order form is submitted, the ProcessVerifyWith method on the target page stores these fields in a Dictionary object in the OrderForm, which is then passed to the Order Processing pipeline (OPP). One of the objects in the pipeline compares the original values with the values from the hidden fields.

Important

  • This method is included for backwards compatibility with Site Server 3.0 Commerce Edition. See the AppFrameWork object, which provides similar functionality to that found in this method. Using the AppFrameWork methods is the preferred way of adding this type of functionality to your site, and will ensure better compatibility with future versions of Microsoft Commerce Server.

Definition

Function VerifyWith(
pdispOrder As Object

  pbstrArguments As String
) As String

Parameters

pdispOrder

An object reference to the OrderForm object that contains the fields to verify.

pbstrArguments

A String that contains a comma-separated list of field names in the supplied OrderForm object to verify. This parameter is optional.

Return Values

If this method completes successfully, it returns a String that contains the HTML tags.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oPage is a Commerce.Page object
' The following example generates hidden fields containing
' the values stored in the _total_total,and _tax_total fields
'  of the supplied OrderForm object:
<FORM METHOD="POST"
    ACTION="<% = oPage.SURL("xt_orderform_purchase.asp") %>">
    <% = mscsPage.VerifyWith(mscsOrderForm, "_total_total",
 "_tax_total") %>
' When the page containing this call is loaded in the client
' browser, the  document source for the page would contain the
'  following HTML script '(assuming a total of 138.95 and a tax
'  of 8.75):
<FORM METHOD="POST"
ACTION="http://example.microsoft.com/xt_orderform_purchase.asp">
<INPUT TYPE=HIDDEN NAME="_VERIFY_WITH" VALUE="_total_total=13895">
<INPUT TYPE=HIDDEN NAME="_VERIFY_WITH" VALUE="_tax_total=875">

See Also

Page Object

Page.ProcessVerifyWith

OrderForm Object


Page.VirtualDirectory

Use this method to return the name of the virtual directory for the site.

Important

  • This method is included for backwards compatibility with Site Server 3.0 Commerce Edition. See the AppFrameWork object, which provides similar functionality to that found in this method. Using the AppFrameWork methods is the preferred way of adding this type of functionality to your site, and will ensure better compatibility with future versions of Microsoft Commerce Server.

Definition

Function VirtualDirectory() As String

Parameters

None.

Return Values

If this method completes successfully, it returns a String that contains the site virtual directory.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

See Also

Page Object

Page.SiteRoot

Page.SURL

Page.URL

Page.SURLPrefix

Page.URLArgs

Page.URLPrefix

Page.URLShopperArgs

StandardSManager Object


PooledPipeline Object

Use this object to execute a Microsoft Commerce Server 2000 pipeline configuration file. The pipeline may be an Order Processing pipeline (OPP).

The PooledPipeline object uses COM+ object pooling to greatly increase the loading speed of pipelines, where the contained pipeline components support object pooling. For more information about pooled pipelines, see Pooled Pipelines.

ProgID: | Commerce.PooledPipeline (Externally creatable)
COM Class Name: | CPooledPipeline
Type Library Name: | Microsoft Commerce 2000 Order Pipeline Type Library
DLL Name: | pipeline.dll
Threading Model: | Both

The methods of the PooledPipeline object are shown in the following table.

Method | Description
Execute | Runs the components in the pipeline.
LoadPipe | Loads a pipeline configuration file (.pcf) into the pipeline.
SetLogFile | Identifies the file in which to log pipeline events.

Remarks

The PooledPipeline should be created on each Active Server Pages (ASP) page in which it is used rather thatn being held in Application or Sessions scope.

In general, use the PooledPipeline object only in production Web sites; use the MtsPipeline object when developing the site. If you use the PooledPipeline object during development, you will need to stop and restart Internet Information Services (IIS).

When you create custom poolable pipeline components, you must add the Component Object Model (COM) category, CATID_POOLABLE, to the component to make it poolable.

The PooledPipeline object is registered under COM+ as "transactions not supported." Use this pipeline where transactions are not needed. For more information about transactions and pipelines, see Pipeline Basics.


PooledPipeline.Execute

Use this method to run the stages in the pipeline configuration file, which was previously specified by the LoadPipe method.

Definition

Function Execute(
lMode As Long,
pdispOrder As Object,
pdispContext As Object,
lFlags As Long
) As Long

Parameters

lMode

A Long indicating the mode in which to run the pipeline. This parameter is provided only for backward compatibility with previous versions of Commerce Server. Specify 1 for this parameter.

pdispOrder

A reference to a business object (typically a dictionary object or an order form object).

pdispContext

A reference to a secondary business object (typically a context dictionary).

lFlags

An unused Long parameter. Must be set to zero (0).

Return Values

If this method completes successfully, it returns a Long indicating whether there were warnings or errors detected by components in the pipeline. See the Error Values section for more details.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

In addition, the method returns one of the following three values:

Value | Description
1 | The pipeline ran successfully.
2 | A pipeline component raised a warning. Generally, these are basket or user errors that would be reported to the user through the ASP page.
3 | A pipeline component failed to run.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' dOrder, dContext are Commerce.Dictionary objects
' pPooledPipeline is a Commerce.PooledPipeline object

errVal = pPooledPipeline.Execute(1, dOrder, dContext, 0)

See Also

PooledPipeline Object

PooledPipeline.LoadPipe

PooledPipeline.SetLogFile


PooledPipeline.LoadPipe

Use this method to load a pipeline configuration file (.pcf) into a pipeline.

Definition

Sub LoadPipe(
pszFileName As String
)

Parameters

pszFileName

A String containing the pipeline configuration file (.pcf) name.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The LoadPipe method must be called to initialize all pipelines.

The LoadPipe method fails if you attempt to load a pipeline configuration file that is designated to be used for transactions (for use in MtsTxPipeline or PooledTxPipeline).

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' pPooledPipeline is a Commerce.PooledPipeline object

errVal = pPooledPipeline.LoadPipe("CustomShip.pcf")

See Also

PooledPipeline Object

PooledPipeline.Execute

PooledPipeline.SetLogFile


PooledPipeline.SetLogFile

Use this method to identify the file in which to log the operations of the pipeline component.

Note

  • This method is for use by developers who want to analyze pipeline configuration file information. Logging should never be enabled in a production environment: it degrades performance and compromises the security of credit card numbers in non-set transactions. The file system must be configured to allow the process running the pipeline to have write access to the specified path.

Definition

Sub SetLogFile(
pszFileName As String
)

Parameters

pszFileName

A String containing the name of the file in which to log events.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

When logging is set, the pipeline logs the pipeline components that are called and the error values each component returns. The pipeline also logs all Dictionary and SimpleList object read and write operations.

Calling this method with an empty string turns off logging.

The SetLogFile method should be called immediately before executing a pipeline.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' pPooledPipeline is a Commerce.PooledPipeline object

errVal = pPooledPipeline.SetLogFile("CustomShipping.log")

See Also

PooledPipeline Object

PooledPipeline.Execute

PooledPipeline.LoadPipe


PooledTxPipeline Object

Use this object to execute a Microsoft Commerce Server 2000 pipeline. The pipeline may be an Order Processing pipeline (OPP). Use in place of the PooledPipeline object where you need transactions.

The PooledTxPipeline object uses COM+ object pooling to greatly increase the loading speed of pipelines. For more information about pooled pipelines, see Pooled Pipelines.

ProgID: | Commerce.PooledTxPipeline (Externally creatable)
COM Class Name: | CPooledTxPipeline
Type Library Name: | Microsoft Commerce 2000 Order Pipeline Type Library
DLL Name: | pipeline.dll
Threading Model: | Both

The methods of the PooledTxPipeline object are shown in the following table.

Method | Description
Execute | Runs the components in the pipeline as configured by the LoadPipe method.
LoadPipe | Loads a pipeline configuration file (.pcf) into the pipeline.
SetLogFile | Identifies the file in which to log pipeline events.

Remarks

The PooledTxPipeline object is registered under COM+ as "transactions required." Use this pipeline where transactions are needed. For more information about transactions and pipelines, see Pipeline Basics.

The Microsoft Distributed Transaction Coordinator (MSDTC) service must be running in order to use the PooledTxPipeline object.

To verify that the Distributed Transaction Coordinator service is running

  1. Click Start, point to Programs, point to Administrative Tools, and then click Services.

  2. Scroll to Distributed Transaction Coordinator and verify that the Status is Started.

In general, use the PooledTxPipeline object only in production Web sites; use the MtsPipeline object when developing the site. If you use the PooledTxPipeline object during development, you will need to stop and restart Internet Information Services (IIS) in order to force the .pcf files to be re-read when you change them.

The PooledPipeline object should be created on each ASP page in which it is used rather than being held in Application or Session scope.

When you create custom poolable pipeline components, you must add the Component Object Model (COM) category, CATID_POOLABLE, to the component to make it poolable.


PooledTxPipeline.Execute

Use this method to run the stages in the pipeline configuration file, which was previously specified by the LoadPipe method.

Definition

Function Execute(
lMode As Long,
pdispOrder As Object,
pdispContext As Object,
lFlags As Long
) As Long

Parameters

lMode

A Long indicating the mode in which to run the pipeline. This parameter is provided only for backward compatibility with previous versions of Commerce Server. Specify 1 (one) for this parameter.

pdispOrder

A reference to a business object (typically a dictionary object or an order form object). The Order dictionary that will be used by the pipeline, usually an OrderForm object.

pdispContext

A reference to a secondary business object (typically a context dictionary object).

lFlags

An unused Long parameter. Must be set to zero (0).

Return Values

If this method completes successfully, it returns a Long indicating whether components in the pipeline detected warnings or errors. See the Error Values section for more details.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

In addition, the method returns one of the following three values:

Value | Description
1 | The pipeline ran successfully.
2 | A pipeline component raised a warning. Generally, these are basket or user errors that would be reported to the user through the ASP page.
3 | A pipeline component failed to run.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' dOrder, dContext are Commerce.Dictionary objects
' pPooledTxPipeline is a Commerce.PooledTxPipeline object

errVal = pPooledTxPipeline.Execute(1, dOrder, dContext, 0)

See Also

PooledTxPipeline Object

PooledTxPipeline.LoadPipe

PooledTxPipeline.SetLogFile


PooledTxPipeline.LoadPipe

Use this method to load a pipeline configuration file (.pcf) into the pipeline.

Definition

Sub LoadPipe(
pszFileName As String
)

Parameters

pszFileName

A String containing the pipeline configuration file (.pcf) name.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The LoadPipe method must be called to initialize all pipelines.

The LoadPipe method fails if you attempt to load a pipeline configuration file that is not designated to be used for transactions (for use in MtsPipeline or PooledPipeline).

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' pPooledTxPipeline is a Commerce.PooledTxPipeline object

errVal = pPooledTxPipeline.LoadPipe("CustomShip.pcf")

See Also

PooledTxPipeline Object

PooledTxPipeline.Execute

PooledTxPipeline.SetLogFile


PooledTxPipeline.SetLogFile

Use this method to identify the file in which to log the operations of the pipeline component.

Note

  • This method is for use by developers who want to analyze pipeline configuration file information. Logging should never be enabled in a production environment: it degrades performance and could compromise the security of credit card numbers in non-set transactions. File systems must be configured to allow the process running the pipeline to have write access to the specified path.

Definition

Sub SetLogFile(
pszFileName As String
)

Parameters

pszFileName

A String containing the name of the file in which to log events.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

When logging is set, the pipeline logs the pipeline components that are called and the error values each component returns. The pipeline also logs all Dictionary and SimpleList object read and write operations.

The SetLogFile methodshould be called immediately before executing a pipeline.

Calling this method with an empty string turns off logging.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' pPooledTxPipeline is a Commerce.PooledTxPipeline object

errVal = pPooledTxPipeline.SetLogFile("CustomShipping.log")

See Also

PooledTxPipeline Object

PooledTxPipeline.Execute

PooledTxPipeline.LoadPipe


PredictorClient Object

Use this object to load an analysis model, set properties controlling the prediction context, and execute the prediction algorithm. Two types of models are supported, prediction models and segment models. Results of a prediction model are used to recommend products and supply missing profile data. Results of a segment model are used to categorize a user. Prediction models provide more accurate recommendations than segment models and the use of segment models for predictions is discouraged.

ProgID: | Commerce.PredictorClient (Externally creatable)
COM Class Name: | PredictorClient
Type Library Name: | Microsoft Commerce 2000 Predictor Client Type Library
DLL Name: | PredictorClient.dll
Threading Model: | Both

The properties of the PredictorClient object are shown in the following table.

Property | Type | Description
fpDataFitScore | Single | Stores the Data Fit Score. This property is read-only.
fpDefaultConfidence | Single | Stores the threshold for confidence in a prediction. This property is read/write.
bFailOnUnknownInputAttributes | Boolean | Controls the behavior of the Predict method when input attributes are unknown. This property is read/write.
fpPopularityPenalty | Single | Stores the penalty applied when selecting popular items to recommend. This property is read/write.
fpRecommendScore | Single | Stores the Recommend Score. This property is read-only.
sSiteName | String | Stores the site name in which the PredictorClient object is running. This property is read/write.

The methods of the PredictorClient object are shown in the following table.

Method | Description
Explain | Explains the prediction of a property in terms of the relevant property/value pairs used as input to the prediction model.
LoadModelFromDB | Loads a model from a database.
LoadModelFromFile | Loads a model from the specified file.
Predict | Predicts recommend products or missing profile data.
PredictAllSegments | Calculates the probabilities that the user belongs to each segment of a population of past users.
PredictMostLikelySegment | Calculates the segment to which the user most likely belongs.
SaveModelToFile | Saves a model to the specified file.

Remarks

Applications that need to anticipate user behavior use the PredictorClient object to load analysis models and generate predictions. The models use a specified set of partial cases as the basis for their predictions. A case is all that is known about a previous user and may contain demographic information and transactional history.

Use the PredModelBuilder object to generate new models. Use the PredictorServiceAdmin object to retrieve a list of models and model configurations. Use the PredictorServiceSiteAdmin object to delete or rename models and model configurations.

Measure the effectiveness of a prediction model using the fpDataFitScore and the fpRecommendScore properties. This allows fine-tuning of the input parameters, such as SampleSize, InputAttributeFraction, and OutputAttributeFraction, when building the model.

Load a model using the LoadModelFromDB or LoadModelFromFile methods prior to using other PredictorClient methods.

For optimum performance when using a prediction model, default values for the fpDefaultConfidence and fpPopularityPenalty properties should be set in the Application_OnStart method in the global.asa file, to avoid having to explicitly set the values for every Predict method call.

See Also

Prediction Objects

Predictor Schema

PredictorServiceAdmin Object

PredictorServiceSiteAdmin Object

PredModelBuilder Object

Running the Predictor Resource


PredictorClient.fpDataFitScore

The read-only fpDataFitScore property returns the Data Fit Score, measuring the effectiveness of a prediction model to fill in missing profile data.

Definition

Property fpDataFitScore As Single

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The Data Fit Score is automatically computed when a model is built, using a fraction of the data as test data. The amount of data to set aside for testing purposes is specified as the Measured Accuracy Sample Fraction. For more information, see Building a New Analysis Model and PredictorModels Table.

Use the Data Fit Score to test and fine-tune the input parameters for a prediction model. Known cases, taken from the input cases used to build the model, are tested against both the prediction model and a "stalking horse" model. The " stalking horse" model is a marginal model that assumes all properties are independent. An intermediate value is calculated by dividing the probability the prediction model assigns to a case in the test data by the probability the "stalking horse" model assigns to the same case. The score is the logarithm of the geometric average of these values for each output property. Thus, any score greater than zero means that the built model makes predictions that are more accurate than the "stalking horse" model.

Load the prediction model using the LoadModelFromDB or LoadModelFromFile methods prior to accessing this property.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

PredictorClient Object

PredictorClient.Predict


PredictorClient.fpDefaultConfidence

The read/write fpDefaultConfidence property determines the threshold below which predictions are not returned by the PredictorClient object.

Definition

Property fpDefaultConfidence As Single

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

The following standard COM error value has a particular meaning in the context of this property.

E_INVALIDARG

The value of the property is outside the valid range of 0 to 100.

Remarks

The fpDefaultConfidence property is a threshold that determines which attributes can be shown on the recommendation list. When a prediction is made, each attribute is assigned a probability of "not missing", which in most uses will correspond to the probability that the product will be purchased. If this probability (in percentage) falls below fpDefaultConfidence, then the attribute is not shown on the recommendation list even when this probability is large relative to probabilities of the other attributes being "not missing". The property should be within the range of 0 to 100, but a value of zero (0) is recommended unless the fpPopularityPenalty property is set to zero (0).

Set a default value for this property in the global.asa file to avoid setting the value for each Predict method call.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

PredictorClient Object

PredictorClient.Predict


PredictorClient.Explain

Use this method to return the properties and values from the current case that are relevant to a prediction of the specified unknown property. A score corresponding to each returned property/value pair explains the importance of each property/value pair to the prediction.

Definition

Sub Explain(
dCurrentCase As Object,
sPropToExplain As String,
pvsavRelevantProps As Variant,
pvsavRelevantValues As Variant,
pvsavRelevantScores As Variant,
Optional lMaxExplanations As Long
)

Parameters

dCurrentCase

A Dictionary object that contains the current case.

sPropToExplain

A String that contains the name of the property to explain.

pvsavRelevantProps

A Variant used to return a SafeArray containing the list of properties from the current case that are relevant to the prediction.

pvsavRelevantValues

A Variant used to return a SafeArray containing the list of values corresponding to the relevant properties.

pvsavRelevantScores

A Variant used to return a SafeArray containing the list of scores corresponding to the importance of each property towards the prediction.

lMaxExplanations

A Long that contains the maximum number of properties to return. The default value of -1 indicates to return all the properties.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

This method returns property/value/score triplets sorted in descending order by score. The higher the score, the greater the probability the unknown property is correctly predicted by the corresponding property/value pair.

Load the prediction model using the LoadModelFromDB or LoadModelFromFile methods prior to using this method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' dCase is a Dictionary object
' vsavRelevantProps, vsavRelevantValues, vsavRelevantScores
'  are Variant SafeArrays
oPredictorClient.Explain dCase, """Age""", vsavRelevantProps, _
 vsavRelevantValues, vsavRelevantScores, 10

See Also

PredictorClient Object


PredictorClient.bFailOnUnknownInputAttributes

The read/write bFailOnUnknownInputAttributes property controls whether the Predict method continues or fails when encountering unknown input attributes.

Definition

Property bFailOnUnknownInputAttributes As Boolean

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

This property is used as a debugging flag. By default, the Predict method ignores unknown input attributes. Setting this property to True causes the Predict method to fail when unknown input attributes are encountered.

When debugging, set a default value for this property in the global.asa file to avoid setting the value for each Predict method call.

Load the prediction model using the LoadModelFromDB or LoadModelFromFile methods prior to accessing this property.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

PredictorClient Object

PredictorClient.Predict


PredictorClient.LoadModelFromDB

Use this method to load a model stored in a database.

Definition

Sub LoadModelFromDB(
sModelName As String,
sDWConnStr As String
)

Parameters

sModelName

A String that contains the model name.

sDWConnStr

A String that contains the connection information for the Data Warehouse.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

A valid model must be loaded before calling the other methods of the PredictorClient object. This model, typically in the range of 100k to 10M, must be loaded onto the local Web server to ensure a timely response to a prediction request.

The information for the model is loaded from the PredictorModels table. For more information about this table, see Predictor Schema.

The sDWConnStr parameter must be a SQL OLE DB connection string.

Use the LoadModelFromFile method to load a model from a file.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

oPredictorClient.LoadModelFromDB "Purchase1", _
 "Provider=SQLOLEDB;Data Source=servername;Initial Catalog=Retail_dw;" _
 & "User ID=user;Password=******;"

See Also

PredictorClient Object

PredictorClient.Predict

PredictorClient.LoadModeFromFile


PredictorClient.LoadModelFromFile

Use this method to load a model stored in a file.

Definition

Sub LoadModelFromFile(
sFilePath As String
)

Parameters

sFilePath

A String that contains the file name, extension, and path.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

A valid model must be loaded before calling the other methods of the PredictorClient object. A model is originally stored in a database and must be loaded using the LoadModelFromDB method. Once loaded, the model may be saved to a file using the SaveModelToFile method.

The file path is relative to the current working directory of the calling process.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' PredictionModel2.mdl is stored in the working directory of the
'  calling process
oPredictorClient.LoadModelFromFile "PredictionModel2.mdl"

See Also

PredictorClient Object

PredictorClient.Predict

PredictorClient.LoadModelFromDB


PredictorClient.fpPopularityPenalty

The read/write fpPopularityPenalty property influences the likelihood that the Predict method recommends popular items.

Definition

Property fpPopularityPenalty As Single

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

The following standard COM error value has a particular meaning in the context of this property.

E_INVALIDARG

The parameter pbVal = 1. The valid range is 0 to less than 1.

Remarks

Popular items are frequently purchased items that are so well known that they do not need to be recommended to a user. A higher penalty value reduces the probability that a popular item is included as a recommended product in the prediction results. The value ranges from 0.0 to less than 1.0. To maximize sales of the most popular items, the default popularity penalty of zero (0) is recommended. For applications where most of the users are familiar with many of the popular products, a value of 0.9 is appropriate.

Set a default value for this property in the Application_OnStart method in the global.asa file to avoid setting the value for each Predict method call.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

PredictorClient Object

PredictorClient.Predict


PredictorClient.Predict

Use this method to generate predictions that are used to recommend relevant products to a user, the current case, or to fill in missing profile data associated with the user.

Definition

Sub Predict(
dCurrentCase As Object,
slPropsToPredict As Object,
pvsavPredictedProps As Variant
pvsavPredictedVals As Variant
Optional lMaxPredictions As Long
Optional pvsavDetails As Variant
)

Parameters

dCurrentCase

A Dictionary object that contains the current case.

slPropsToPredict

A SimpleList object that contains the names of the properties to predict.

pvsavPredictedProps

A Variant used to return a SafeArray containing the predicted property names.

pvsavPredictedVals

A Variant used to return a SafeArray containing the predicted property values.

lMaxPredictions

A Long that specifies the maximum number of predictions to return. The default value of -1 indicates to return all predictions.

pvsavDetails

Reserved for future use.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Predictions are made using the currently loaded prediction model based on user profile and selection information contained in the current case. The predicted property/value pairs are returned sorted in descending order of likelihood.

Set the fpDefaultConfidence and fpPopularityPenalty properties and load the prediction model using the LoadModelFromDB or LoadModelFromFile methods before using the Predict method.

Default values for the fpDefaultConfidence and fpPopularityPenalty properties may be set in the Application_OnStart method in the global.asa file to avoid having to explicitly set the values for every Predict method call.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' dCase is a Dictionary object, slPropsToPredict is a SimpleList
' vsavPredictedProps, vsavPredictedValues are Variant SafeArrays
oPredictorClient.Predict dCase, slPropsToPredict, vsavPredictedProps, _
 vsavPredictedVals, 10

See Also

PredictorClient Object

PredictorClient.LoadModelFromFile

PredictorClient.LoadModelFromDB

PredictorClient.fpDefaultConfidence


PredictorClient.PredictAllSegments

Use this method to predict the probabilities that a particular user, the current case, belongs to each segment of a population.

Definition

Sub PredictAllSegments(
dCurrentCase As Object,
pvsavSegmentNames As Variant,
pvsavProbabilities As Variant
)

Parameters

dCurrentCase

A Dictionary object that contains the current case.

pvsavSegmentNames

A Variant used to return a SafeArray containing the segment names.

pvsavProbabilities

A Variant used to return a SafeArray containing the membership probabilities associated with the segment names.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The Microsoft Research Cluster Engine Data Modeler groups similar users into segments. Similar segments are further grouped into higher order collections of segments, creating a hierarchy from which to analyze trends and discover hidden correlations. The returned probability associated with each segment name indicates the probability that the current user belongs to that segment.

Load the segment model using the LoadModelFromDB or LoadModelFromFile methods prior to using this method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' dCase is a Dictionary object
' vsavSegmentNames and vsavProbabilities are Variant SafeArrays
oPredictorClient.PredictAllSegments dCase, vsavSegmentNames, _
 vsavProbabilities

See Also

PredictorClient Object


PredictorClient.PredictMostLikelySegment

Use this method to predict the most likely segment of a population to which a user, the current case, belongs.

Definition

Function PredictMostLikelySegment(
dCurrentCase As Object,
Optional pvarProbability As Variant
) As String

Parameters

dCurrentCase

A Dictionary object that contains the current case.

pvarProbability

A Variant used to return the membership probability associated with the segment name.

Return Values

If successful, this method returns a String containing the segment name.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The Microsoft Research Cluster Engine Data Modeler groups similar users into segments. Similar segments are further grouped into higher order collections of segments, creating a hierarchy from which to analyze trends and discover hidden correlations.

This method returns the name of the segment most likely to contain the given case, and optionally, the probability that the user belongs to this segment.

Load the segment model using the LoadModelFromDB or LoadModelFromFile methods prior to using this method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' sSegment is a String, vProbabilty is a Variant
' dCase is a Commerce.Dictionary object
sSegment = oPredictorClient.PredictMostLikelySegment(dCase, vProbability)

See Also

PredictorClient Object


PredictorClient.fpRecommendScore

The read-only fpRecommendScore property returns the Recommendation Score, which measures the quality of a ranked list of recommendations returned from a prediction model.

Definition

Property fpRecommendScore As Single

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Use the Recommendation Score to test and adjust the input parameters for a prediction model. Known cases, taken from the input cases used to build the model, are tested against the prediction model with one of the transactions randomly removed. A list of recommendations is returned, and the prediction is deemed successful if the removed transaction is on the list. The score is the percentage of cases in which the model was successful.

The Recommendation Score is automatically computed when a model is built, using a fraction of the data as test data. The amount of data to set aside for testing purposes is specified as the Measured Accuracy Sample Fraction. For more information, see Building a New Analysis Model and PredictorModels Table.

Load the prediction model using the LoadModelFromDB or LoadModelFromFile methods prior to accessing this property.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

PredictorClient Object

PredictorClient.Predict


PredictorClient.SaveModelToFile

Use this method to save the currently loaded model to a file.

Definition

Sub SaveModelToFile(
sFilePath As String
)

Parameters

sFilePath

[in] A String that contains the file name, extension, and path relative to the working directory of the calling process.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The directory where the file is saved must exist prior to the call.

A model must be loaded using the LoadModelFromDB or LoadModelFromFile methods before using the SaveModelToFile method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

oPredictorClient.SaveModelToFile "PredictionModel2.mdl"

See Also

PredictorClient Object

PredictorClient.LoadModelFromFile

PredictorClient.LoadModelFromDB


PredictorClient.sSiteName

The read/write sSiteName property contains the name of the site in which the PredictorClient object is running.

Definition

Property sSiteName As String

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

This property should be set in the On_Start method of the global.asa file to allow logging of performance monitoring counters to be aggregated over the site. Performance counters are specific to a given computer. If multiple sites are running on the same Web server, the counters give a combined total for all sites. Specifying a site name allows the counts from one site to be distinguished from the counts of other sites.

The following counters are available:

  • Total number of predictions made since the site was initialized.

  • Average time per prediction.

  • Total number of model loads from files.

  • Total number of model loads from a database.

The counters can be accessed in Microsoft Windows 2000 by clicking Control Panel, double-clicking Administrative Tools, and then double-clicking Performance. The counters can also be accessed programmatically through the performance APIs described in the Windows 2000 Platform SDK.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

PredictorClient Object

PredictorClient.Predict


PredictorServiceAdmin Object

Use this object to retrieve a list of the available analysis models, a list of the available model configurations, and the date the Predictor resource was last started.

ProgID: | Commerce.PredictorServiceAdmin (Externally creatable)
COM Class Name: | PredictorServiceAdmin
Type Library Name: | Microsoft Commerce 2000 Predictor Service Type Library
EXE Name: | PredServ.exe
Threading Model: | Both

The properties of the PredictorServiceAdmin object are shown in the following table.

Property | Type | Description
dateLastStarted | Date | Retrieves the date the Predictor resource was last started. This property is read-only.
slModelConfigs | Object | Retrieves a list of currently available model configurations. This property is read-only.
slModels | Object | Retrieves a list of currently available models. This property is read-only.

Remarks

The PredictorServiceSiteAdmin object provides methods for maintaining the models and model configurations. The PredictorClient object loads the appropriate model and makes the actual predictions. Generate new models by using the PredModelBuilder object.

See Also

Prediction Objects

Predictor Schema

PredictorClient Object

PredictorServiceSiteAdmin Object

PredModelBuilder Object

Running the Predictor Resource


PredictorServiceAdmin.dateLastStarted

The dateLastStarted property is a read-only Date that indicates when the Predictor resource was last started.

Definition

Property dateLastStarted As Date

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

PredictorServiceAdmin Object

PredictorServiceSiteAdmin Object

PredModelBuilder Object


PredictorServiceAdmin.slModelConfigs

The slModelConfigs property is a read-only SimpleList object that contains information about the available model configurations.

Definition

Property slModelConfigs As Object

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The SimpleList object, slModelConfigs, contains a Dictionary object for each model configuration. A model configuration contains information used to build a model. The following table describes the keys of the Dictionary object which are the names of the model configuration properties.

Key Name | Type | Description
DWResourceName | String | Name of the Data Warehouse resource where the model configuration is defined.
ModelCfgName | String | Name of the model configuration.
SiteName | String | Reserved. May not appear in the dictionary.

Use the DeleteModelConfig method of the PredictorServiceSiteAdmin object to delete a model configuration.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

PredictorServiceAdmin Object

PredictorServiceSiteAdmin Object

PredModelBuilder Object


PredictorServiceAdmin.slModels

The slModels property is a read-only SimpleList object that contains information about the available models.

Definition

Property slModels As Object

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The SimpleList object, slModels, contains a Dictionary object for each available model. A model is available if a copy of it exists and is not currently being built. The keys of the Dictionary object are the names of the model properties as listed in the PredictorModels Table. The following table describes a few of these keys. For information about the remaining keys, see PredictorModels Table.

Key Name | Type | Description
DWResourceName | String | Name of the Data Warehouse resource where the model configuration is defined.
ModelCfgName | String | Name of the model configuration used to build the model.
ModelName | String | Model name.

Use the Start method of the PredModelBuilder object to create a new model.

Use the DeleteModel method of the PredictorServiceSiteAdmin object to delete a model.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

PredictorServiceAdmin Object

PredictorServiceSiteAdmin Object

PredModelBuilder Object


PredictorServiceSiteAdmin Object

Use this object to manage analysis models and model configurations.

ProgID: | Commerce.PredictorSiteAdmin (Externally creatable)
COM Class Name: | PredictorServiceSiteAdmin
Type Library Name: | Microsoft Commerce 2000 Predictor Service Type Library
EXE Name: | PredServ.exe
Threading Model: | Both

The properties of the PredictorServiceSiteAdmin object are shown in the following table.

Property | Type | Description
lCaseCount | Long | Retrieves the number of cases used by a model configuration. This property is read-only.
dModelInfo | Object | Retrieves information on the specified model. This property is read-only.
SegmentLabels | Variant | Stores the segment labels for a segment model. This property is read/write.

The methods of the PredictorServiceSiteAdmin object are shown in the following table.

Method | Description
DeleteModel | Deletes the specified predictor model.
DeleteModelConfig | Deletes the specified model configuration.
GenerateSegmentList | Generates a list of members of a segment.
Init | Initializes the server.
RenameModel | Renames a predictor model.
RenameModelConfig | Renames a model configuration.

Remarks

An analysis model summarizes dependency relationships among attributes found in data. A model configuration contains information used to build the analysis model.

Two types of analysis models are available. A prediction model is used to produce a ranked list of recommendations or to fill in a missing user profile attribute. A segment model is used to group similar users into segments of a population.

The PredictorServiceAdmin object contains lists of the available models and model configurations. The PredictorClient object loads the appropriate model and makes the actual predictions. The generation of new models is controlled by the PredModelBuilder object.

See Also

Prediction Objects

Predictor Schema

PredictorClient Object

PredictorServiceAdmin Object

PredModelBuilder Object

Running the Predictor Resource


PredictorServiceSiteAdmin.lCaseCount

The lCaseCount property is a read-only Long that contains a count of the number of cases used by a model configuration.

Definition

Property lCaseCount(
sConfigName As String
) As Long

Parameters

sConfigName

A String that contains the model configuration name.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

A case is the set of information known about a particular user. This information might include user profile data, purchase history, URL click history, or other user associated data. The number of cases used to build a model affects the accuracy of that model. In general, predictions will be more accurate when many cases are available for the model. However, the time necessary to build the model increases with the number of cases in the configuration and increases in accuracy are slight when the number of cases becomes very large (typically, greater than 50,000 cases).

Use the slModelConfigs property of the PredictorServiceAdmin object to retrieve a list of the available model configurations.

Connect to the Data Warehouse using the Init method before accessing this property.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

PredictorServiceAdmin Object

PredictorServiceSiteAdmin Object

PredModelBuilder Object


PredictorServiceSiteAdmin.DeleteModel

Use this method to delete the specified model.

Definition

Sub DeleteModel(
sModelName As String
)

Parameters

sModelName

A String that contains the name of the model to delete.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Use the slModels property of the PredictorServiceAdmin object to retrieve a list of the available models.

Deleting a model causes its entry in the PredictorModels table in the Data Warehouse to be removed.

Passing an empty string for the model name will result in an invalid argument error.

Connect to the Data Warehouse using the Init method before calling the DeleteModel method.

Use the Start method of the PredModelBuilder object to create a new model.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

PredictorServiceAdmin Object

PredictorServiceSiteAdmin Object

PredModelBuilder Object


PredictorServiceSiteAdmin.DeleteModelConfig

Use this method to delete the specified model configuration.

Definition

Sub DeleteModelConfig(
sModelConfigName As String
)

Parameters

sModelConfigName

A String that contains the name of the model configuration to delete.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Use the slModelConfigs property of the PredictorServiceAdmin object to retrieve a list of the available model configurations.

Passing an empty string for the model configuration name will result in an invalid argument error.

Deleting a model configuration causes its entries in the PredictorModelCfgs and PredictorDataTables tables in the Data Warehouse to be removed, as well as the Attributes table it references. No case data is deleted.

Caution

  • For this release of Microsoft Commerce Server 2000, the user must directly modify tables in the Data Warehouse to create a new model configuration. No API function is provided.

Connect to the Data Warehouse using the Init method before calling the DeleteModelConfig method.For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

PredictorServiceAdmin Object

PredictorServiceSiteAdmin Object

PredModelBuilder Object


PredictorServiceSiteAdmin.dModelInfo

The dModelInfo property is a read-only Dictionary object that contains information on the specified model.

Definition

Property dModelInfo(
sModelName As String
) As Object

Parameters

sModelName

A String that contains the model name.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The keys of the returned Dictionary object are the names of the model properties as listed in the PredictorModels Table. The following table describes a few of these keys. For information about the remaining keys, see PredictorModels Table.

Key Name | Type | Description
DWResourceName | String | Name of the Data Warehouse resource where the model configuration is defined.
ModelCfgName | String | Name of the model configuration used to build the model.
ModelName | String | Model name.

Connect to the Data Warehouse using the Init method before accessing this property.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

PredictorServiceAdmin Object

PredictorServiceSiteAdmin Object

PredModelBuilder Object


PredictorServiceSiteAdmin.GenerateSegmentList

Use this method to generate a list of the members of a segment.

Definition

Sub GenerateSegmentList(
sLMConn As String,
sTableName As String,
sModelName As String,
sSegmentName As String
fpMinProbability As Double

)

Parameters

sLMConn

A String that specifies the connection information for the ListManager object.

sTableName

A String that specifies the name of the table to store the list of segment members.

sModelName

A String that specifies the name of the segment model to use.

sSegmentName

A String that specifies the name of the segment to export.

fpMinProbability

A Double that specifies the minimum probability associated with a segment member for that member to be exported. The valid range is between 0 and 1.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

This method is provided for use by the ListManager object and should not be called independently. The CreateFromSegment method of the ListManager object calls this method and creates the list. For more information, see ListManager.CreateFromSegment.

Passing an empty string for the model name results in an empty list.

If the segment name, sSegmentName, does not exist or is the name of a segment group, an empty list is generated. No error is returned for this case.

Connect to the Data Warehouse using the Init method before calling the GenerateSegmentList method.

A segment model classifies groups of users into segments of users with similar user properties. Similar segments are further grouped into higher order collections of segments.

Each user is assigned a probability of membership to each segment. The sum of the probabilities for all segments equals one for the user. If the probability of membership in a particular segment for the user is greater than fpMinProbability, the user will be included in the export list.

All members (individual cases) of the specified segment level with an associated probability greater than the value specified in the fpMinProbability attribute are stored in the named table, and then exported into the List Manager.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

oPredictorServiceSiteAdmin.GenerateSegmentList _
 "Provider=SQLOLEDB;Data Source=servername;" & _
 "Initial Catalog=Retail_commerce;User ID=user;Password=*****;", _
 "TeenAgers", "Demog1", "TeenAgers", .5

See Also

PredictorServiceAdmin Object

PredictorServiceSiteAdmin Object

PredModelBuilder Object


PredictorServiceSiteAdmin.Init

Use this method to initialize the connection to the Data Warehouse.

Definition

Sub Init(
sSiteName As String,
sDWConnStr As String
)

Parameters

sSiteName

A String that is unused. Pass in an empty string.

sDWConnStr

A String that contains the Data Warehouse connection string.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The models and model configurations are stored in tables in the Data Warehouse.

Initialize the connection to the Data Warehouse before any other properties or methods of the PredictorServiceSiteAdmin object are called.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

oPredictorServiceSiteAdmin.Init "", _
 "Provider=SQLOLEDB;Data Source=servername;" & _
 "Initial Catalog=Retail_commerce;User ID=user;Password=*****;"

See Also

PredictorServiceAdmin Object

PredictorServiceSiteAdmin Object

PredModelBuilder Object

PredictorClient Object


PredictorServiceSiteAdmin.RenameModel

Use this method to rename a model.

Definition

Sub RenameModel(
sOldModelName As String,
sNewModelName As String
)

Parameters

sOldModelName

A String that contains the old model name.

sNewModelName

A String that contains the new model name.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

The following standard COM error value has a particular meaning in the context of this method.

E_FAIL

A model with the old name could not be found, or a model with the new name already exists.

Remarks

When renaming a model, update any sites that load the model using the LoadModelFromDB method of the PredictorClient object.

The name change is made to the model entry in the PredictorModels table in the Data Warehouse.

Use the slModels property of the PredictorServiceAdmin object to retrieve a list of available models. Use the RenameModelConfig method to rename a model configuration.

Passing an empty string for either model name will result in an invalid argument error.

Connect to the Data Warehouse using the Init method before calling the RenameModel method. For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

oPredictorServiceSiteAdmin.RenameModel "PredictorModel2", "PredictorModel3"

See Also

PredictorClient Object

PredictorServiceAdmin Object

PredictorServiceSiteAdmin Object

PredModelBuilder Object


PredictorServiceSiteAdmin.RenameModelConfig

Use this method to rename a model configuration.

Definition

Sub RenameModelConfig(
sOldModelConfigName As String,
sNewModelConfigName As String
)

Parameters

sOldModelConfigName

A String that contains the old model configuration name.

sNewModelConfigName

A String that contains the new model configuration name.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

The following standard COM error value has a particular meaning in the context of this method.

E_FAIL

A model configuration with the old name could not be found, or a model configuration with the new name already exists.

Remarks

The name change is made to the model configuration entry in the PredictorModelCfgs table in the Data Warehouse.

Use the slModelsConfigs property of the PredictorServiceAdmin object to retrieve a list of the model configurations. Use the RenameModel method to rename a model.

Passing an empty string for the model configuration name will result in an invalid argument error.

Connect to the Data Warehouse using the Init method before calling the RenameModelConfig method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

oPredictorServiceSiteAdmin.RenameModelConfig "ModelConf1", "ModelConf2"

See Also

PredictorServiceAdmin Object

PredictorServiceSiteAdmin Object

PredModelBuilder Object


PredictorServiceSiteAdmin.SegmentLabels

The SegmentLabels property is a read/write Variant that contains the labels for a given segment model.

Definition

Property SegmentLabels(
sModelName As String,
lDepth As Long
) As Variant

Parameters

sModelName

A String that contains the name of the segment model.

lDepth

A Long that specifies the depth in the segment hierarchy from which labels are assigned or retrieved.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

A segment model classifies groups of users into segments of users with similar user properties. Similar segments are grouped into higher order collections of segments, creating a hierarchy. When the segments are first generated they are generically labeled (for example, Segment4 or Group2). Rename the labels to better identify the different groups.

Valid values for the lDepth parameter are -1 (returns all segments) and 2 or greater.

Connect to the Data Warehouse using the Init method before accessing this property.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' saLabels is a SafeArray of Strings
' segment level 2 contains 3 members

saLabels(0) = "TeenAgers"
saLabels(1) = "TwentySomethings"
saLabels(2) = "Oldies"

oPredictorServiceSiteAdmin.SegmentLabels("Demog1", 2) = saLabels

See Also

PredictorServiceAdmin Object

PredictorServiceSiteAdmin Object

PredModelBuilder Object


PredModelBuilder Object

Use this object to control the creation of analysis models using multiple prioritized build threads.

ProgID: | Commerce.PredictorModelBuilder (Externally creatable)
COM Class Name: | PredModelBuilder
Type Library Name: | Microsoft Commerce 2000 Predictor Service Type Library
EXE Name: | PredServ.exe
Threading Model: | Both

The properties of the PredModelBuilder object are shown in the following table.

Property | Type | Description
dModelInfo | Object | Retrieves information on the specified running model. This property is read-only.
Priority | Enum | Stores the build thread priority. This property is read/write.
slRunningModels | Object | Retrieves a list of running models. This property is read-only.
Status | Enum | Indicates the build thread status. This property is read-only.

The methods of the PredModelBuilder object are shown in the following table.

Method | Description
Pause | Pauses a running build thread.
Resume | Resumes a paused build thread.
Start | Sets the thread identifier for a build and starts a new build thread.
Stop | Stops a running build thread.
StopAllBuilds | Stops all currently running build threads.

Remarks

Two types of analysis models are available in Microsoft Commerce Server 2000. A Prediction model is a collection of decision trees (called a dependency net) and is used either to produce a ranked list of recommendations, such as products to advertise, or to fill in missing user profile information, such as age. A Segment model is based on the process of clustering (segmentation) and is used to group similar users into segments of a population.

An analysis model is associated with a model configuration. More than one analysis model can be associated with the same model configuration. The model configuration contains attribute and case information used to build the analysis model. A case is all the information known about a user, such as profile data and transaction data. A typical model uses between 10,000 and 20,000 cases with a resulting size of between 100 kilobytes (KB) and 10 megabytes (MB).

The PredictorServiceAdmin object contains lists of the available analysis models and model configurations. The PredictorServiceSiteAdmin object provides methods for maintaining the analysis models and model configurations. The PredictorClient object loads the appropriate analysis model and makes the actual prediction.

The generation of an analysis model occurs in an individual build thread. A single instance of the PredModelBuilder object may control multiple simultaneous build threads. If a problem occurs in a build thread, that specific thread may be paused or terminated.

See Also

Prediction Objects

Predictor Schema

PredictorClient Object

PredictorServiceAdmin Object

PredictorServiceSiteAdmin Object

Running the Predictor Resource


PredModelBuilder.dModelInfo

The dModelInfo property is a read-only Dictionary object that contains information on the specified running model.

Definition

Property dModelInfo(
lBuildID As Long
) As Object

Parameters

lBuildID

[in] A Long that contains the build identifier used to select a specific build thread.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The keys of this dictionary are the build parameters of the running model. For information on the build parameters, see PredictorModels Table.

Initiate the build thread using the Start method before you access the thread using the dModelInfo property.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

PredModelBuilder Object

PredModelBuilder.Start

PredModelBuilder.Stop


PredModelBuilder.Pause

Use this method to suspend the model build thread.

Definition

Sub Pause(
lBuildID As Long
)

Parameters

lBuildID

[in] A Long that contains the build thread identifier.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The build thread identifier is returned by the Start method when a model build is initiated.

Use the Resume method to resume the paused build thread.

Use the Stop method to stop the execution of the build thread. A stopped thread may not be resumed. The thread must be restarted with the Start method.

Use the Status property to check the current status of a model build.

See Also

PredModelBuilder Object

PredModelBuilder.Start

PredModelBuilder.Resume

PredModelBuilder.Stop

PredModelBuilder.Status

PredModelBuilder.Priority


PredModelBuilder.Priority

The Priority property is a read/write ePredBuildPriority enumerated type. This property stores the priority of a build thread.

Definition

Property Priority(
lBuildID As Long
) As Enum

Parameters

lBuildID

[in] A Long that contains the build identifier.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Change this property to raise or lower the priority of the build thread depending on how quickly the build is needed.

The following table defines the possible values for the ePredBuildPriority enumerated priority levels. Absolute thread priority is not supported. These priority values are relative to the spawning thread.

Name | Value | Description
PriLowest | -2 | Lowest priority.
PriBelowNormal | -1 | Lower priority.
PriNormal | 0 | Normal priority.
PriAboveNormal | 1 | Higher priority.
PriHighest | 2 | Highest priority.

Initiate the build thread with the Start method before you access the Priority property.

Use the Pause method to temporarily suspend execution of equal or higher priority threads when a particular build thread is time-critical. Threads are executed round robin for each priority level. Threads with lower priorities are not executed until all the threads with a higher priority have executed.

See the Microsoft Developer Network (MSDN) documentation for the system SetThreadPriority method for more information about thread scheduling.

The Priority method does not support the THREAD_PRIORITY_REALTIME priority.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

PredModelBuilder Object

PredModelBuilder.Start

PredModelBuilder.Pause


PredModelBuilder.Resume

Use this method to resume the execution of a build thread suspended by the Pause method.

Definition

Sub Resume(
lBuildID As Long
)

Parameters

lBuildID

[in] A Long that contains the identifier of the paused build thread.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The build thread identifier is returned by the Start method when a model build is initiated.

Use the Status property to determine if a build thread is running or paused.

See Also

PredModelBuilder Object

PredModelBuilder.Start

PredModelBuilder.Pause

PredModelBuilder.Stop

PredModelBuilder.Status


PredModelBuilder.slRunningModels

The slRunningModels property is a read-only SimpleList object that contains information on the active (running and paused) model build threads.

Definition

Property slRunningModels() As Object

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The SimpleList object, slRunningModels, contains a Dictionary object for each running model. The keys of the Dictionary object are the names of the model properties as listed in the PredictorModels Table except for the properties dependent on a successful finished build. The properties that are unavailable are: DateCreated, DataFitScore, RecommendScore, and BuildTime. After a successful build, these properties are available through the slModels property of the PredictorServiceAdmin object or the dModelInfo property of the PredictorServiceSiteAdmin object. The following table describes a few of the keys contained in the Dictionary object. For information about the remaining keys, see PredictorModels Table.

Key Name | Type | Description
DWResourceName | String | Name of the Data Warehouse resource where the model configuration is defined.
ModelCfgName | String | Name of the model configuration used to build the model.
BuildID | Long | The ID of the build thread.
ModelName | String | Model name.

Use the Status property to check the status of a specific model build thread.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

PredictorServiceAdmin.slModels

PredictorServiceSiteAdmin.dModelInfo

PredModelBuilder Object

PredModelBuilder.Start

PredModelBuilder.Stop

PredModelBuilder.StopAllBuilds

PredModelBuilder.Status


PredModelBuilder.Start

Use this method to create a new model build thread.

Definition

Function Start(
sDWConnStr As String,
sSiteName As String,
sConfigName As String,
sModelName As String,
sXMLBuildParams As String
bOverWrite As Boolean
) As Long

Parameters

sDWConnStr

[in] A String that contains the connection information for the data warehouse.

sSiteName

[in] A String that is not used. Pass an empty string.

sConfigName

[in] A String that contains the model configuration name.

sModelName

[in] A String that contains the model name.

sXMLBuildParams

[in] A String that contains the run-time build parameters for the model in XML format.

bOverWrite

[in] A Boolean that indicates whether to overwrite the model if it already exists.

Return Values

If this method completes successfully, it returns a Long that contains the identifier for the new build thread.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

The following standard COM error value has a particular meaning in the context of this method.

E_FAIL

The overwrite flag is False, and the specified model already exists or the build thread failed.

Remarks

For information on the run-time build parameters contained in the sXMLBuildParams parameter, see PredictorModels Table. The sXMLBuildParams parameter must be passed in as the return value of the SaveXML method of the IPersistXML interface of a Dictionary object containing the build parameters. For an example of this technique, see Code to Build a New Model.

Connect to the data warehouse to access the model configuration.

Associating the site name with the PredModelBuilder object allows logging of performance monitoring counters to be aggregated over the site. See the PredictorClient object for more information.

Use the returned identifier for all subsequent access to the build thread.

If a model with the same name already exists and the overwrite parameter is False, the Start method fails.

The priority of a build thread may be set using the Priority property.

Use the Status property to check the status of a build thread.

Use the Stop method to stop a build thread that is currently running. A stopped thread may not be resumed. The thread must be restarted with the Start method.

Use the Pause method to temporarily suspend the execution of a build thread. Use the Resume method to resume execution of the suspended thread.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' lBuildID is a Long

lBuildID = oPredModelBuilder.Start _
("Provider=SQLOLEDB;Data Source=servername;" & _
 "Initial Catalog=Retail_dw;User ID=user;Password=*****;", _
 "", "PurchaseCfg1", "Demog1", sXMLBuildParams, False)

See Also

PredModelBuilder Object

PredModelBuilder.Pause

PredModelBuilder.Resume

PredModelBuilder.Stop

PredModelBuilder.Status

PredModelBuilder.Priority

PredictorClient Object


PredModelBuilder.Status

The Status property is a read-only ePredBuildStatus enumerated type. This property indicates the current status of a model build thread.

Definition

Property Status(
lBuildID As Long
) As Enum

Parameters

lBuildID

[in] A Long that contains the build identifier used to select a specific build thread.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The following table defines the possible values for the ePredBuildStatus enumerated build states.

Name | Value | Description
PredBldRunning | 0 | Is currently running.
PredBldPaused | 1 | Is paused.
PredBldShuttingDown | 2 | Is shutting down in response to the Stop method.

BuildIDs become invalid when a build is finished, either successfully or due to failure. For status information on finished builds, view the event log.

Initiate the build thread using the Start method before you access the thread using the Status property.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

PredModelBuilder Object

PredModelBuilder.Start

PredModelBuilder.Stop


PredModelBuilder.Stop

Use this method to stop execution of a specific model build thread.

Definition

Sub Stop(
lBuildID As Long
)

Parameters

lBuildID

[in] A Long that identifies the model build thread.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

The following standard COM error value has a particular meaning in the context of this method.

E_FAIL

The build ID was invalid or the status of the build thread was neither running nor paused.

Remarks

The build thread identifier is returned by the Start method when a model build is initiated.

The Stop method sets a flag that signals the data modeler for the specified build thread to stop when it is ready. The data modeler checks the flag each time it updates progress information. If the flag is set, the data modeler ends thread execution and performs necessary clean-up operations.

Use the Status property to access the current status of a build thread. If the data modeler has not completed the thread termination, the build thread status is PredBldShuttingDown.

After the thread terminates, the build identifier no longer indicates a valid build thread. A stopped thread may not be resumed. The thread must be restarted with the Start method.

Use the StopAllBuilds method to halt execution of all build threads associated with the PredModelBuilder object.

See Also

PredModelBuilder Object

PredModelBuilder.Start

PredModelBuilder.Status

PredModelBuilder.StopAllBuilds


PredModelBuilder.StopAllBuilds

Use this method to stop execution of all model build threads associated with the PredModelBuilder object.

Definition

Sub StopAllBuilds()

Parameters

None.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The StopAllBuilds method sets a flag that signals each build thread to stop when it is ready. If the flag is set for a build thread, the data modeler for that thread ends thread execution and performs necessary clean-up operations.

Use the Status property to access the current status of a build thread. If a data modeler has not completed thread termination, the thread status for the modeler is PredBldShuttingDown. After the thread terminates, the build identifier no longer indicates a valid build thread. A stopped thread may not be resumed. The thread must be restarted with the Start method.

Use the Stop method to stop a specific build thread.

See Also

PredModelBuilder Object

PredModelBuilder.Start

PredModelBuilder.Status

PredModelBuilder.Stop


Product Object

Use this object to work with products and variants in a catalog.

ProgID: | Dependent (See Remarks for more information)
COM Class Name: | Product
Type Library Name: | Microsoft Commerce 2000 Catalog Type Library
DLL Name: | Catalog.dll
Threading Model: | Both

The properties of the Product object are shown in the following table.

Property | Type | Description
AncestorCategories | Recordset | Contains a recordset of category names that exist anywhere above this product, and that directly or indirectly contain this product in the hierarchy. This property is read-only.
CatalogName | String | Contains the name of the catalog of which this Product object is a member. This property is read-only.
GetProductProperties | Recordset | Contains a recordset containing the property values for this product. This property is read-only.
ParentCategories | Recordset | Contains a recordset of categories that directly contain this product. This property is read-only.
PricingCategory | String | Contains the name of the pricing category for this product. This property is read/write.
ProductID | BSTR | Contains the unique identifier for this product This property is read-only.
RelatedCategories | Recordset | Contains a recordset that describes all of the categories that are related to this product. This property is read-only.
RelatedProducts | Recordset | Contains a recordset that describes all of the products that are related to this product. This property is read-only.
Variants | Recordset | Contains a recordset that describes all of the variants of this product, if any. This property is read-only.

The methods of the Product object are shown in the following table.

Method | Description
AddRelationshipToCategory | Adds a relationship to a specified category from this product.
AddRelationshipToProduct | Adds a relationship to another specified product from this product.
CreateVariant | Creates a new product variant.
DeleteVariant | Deletes a product variant.
GetVariantProperties | Returns the properties of a specified product variant.
RemoveRelationshipToCategory | Removes the specified relationship between this product and the specified category.
RemoveRelationshipToProduct | Removes the specified relationship between this product and the specified product.
SetProductProperties | Sets the properties for this product and all its variants.
SetVariantProperties | Sets the properties for variants of this product.

Remarks

The Product object is a dependent object. Obtain a reference to it by accessing the following properties:

  • ProductCatalog.CreateProduct

  • ProductCatalog.GetProduct


Product.AddRelationshipToCategory

Use this method to add a relationship to a specified category from this product.

Definition

Sub AddRelationshipToCategory(
strRelatedCategoryName As String,
strRelationshipName As String,
Optional strRelationshipDescription As Variant
)

Parameters

strRelatedCategoryName

A String that contains the name of the category to which a relationship is to be added.

strRelationshipName

A String that contains a name for the relationship.

strRelationshipDescription

A Variant that optionally contains a description for the relationship.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_CATEGORY_DOESNT_EXIST | &H8898001C | The specified category did not exist.
E_CAT_INVALID_RELATION | &H88980039 | The specified relationship was invalid. For example, a category or product cannot be related to itself.
E_CAT_INVALID_RELATION_DESC | &H88980055 | The relationship description exceeded 256 characters.
E_CAT_INVALID_RELATION_NAME | &H88980054 | The relationship name exceeded 128 characters.
E_CAT_RELATIONSHIP_EXISTS | &H88980033 | The specified relationship already existed.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The new relationship must have a name, which you specify in the strRelationshipName parameter. It may also optionally have a description, which you can specify in the strRelationshipDescription parameter.

More than one relationship may be created between the same product and category, however in this case each relationship created must be given a unique name.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

'vDesc is a Variant of subtype String containing the description.
myProduct.AddRelationshipToCategory "Apparel", "Accessory", vDesc

See Also

Product Object

Product.AddRelationshipToProduct

Product.RemoveRelationshipToCategory


Product.AddRelationshipToProduct

Use this method to add a relationship to a specified product from this product.

Definition

Sub AddRelationshipToProduct(
varRelatedProductID As Variant,
strRelationshipName As String,
Optional strRelationshipDescription As Variant
)

Parameters

varRelatedProductID

A Variant that contains the ID of the related product.

strRelationshipName

A String that contains the name of the relationship.

strRelationshipDescription

A Variant that optionally contains a description for the relationship.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_INVALID_RELATION | &H88980039 | The specified relationship was invalid. For example, a product cannot be related to itself.
E_CAT_INVALID_RELATION_DESC | &H88980055 | The relationship description exceeded 256 characters.
E_CAT_INVALID_RELATION_NAME | &H88980054 | The relationship name exceeded 128 characters.
E_CAT_PRODUCT_DOESNT_EXIST | &H8898001E | The specified product ID did not exist.
E_CAT_RELATIONSHIP_EXISTS | &H88980033 | The specified relationship already existed.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The new relationship must have a name, which you specify in the strRelationshipName parameter. It may also optionally have a description, which you can specify in the strRelationshipDescription parameter.

More than one relationship may be created between the same two products, however in this case each relationship created must be given a unique name.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

'vProdID is a Variant containing the product ID
'vDesc is a Variant of subtype String containing a description
'of the relationship
myProduct.AddRelationshipToProduct vProdID, "Accessory", vDesc

See Also

Product Object

Product.AddRelationshipToCategory

Product.RemoveRelationshipToProduct


Product.AncestorCategories

The AncestorCategories property is a read-only Recordset object that contains the names of categories that exist anywhere above this product in the hierarchy.

Definition

Property AncestorCategories As Recordset

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_CIRCULAR_REFERENCE | &H88980037 | Circular referencing is not supported. A circular reference would put a category in more than one place in the hierarchy.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The AncestorCategories property contains valid data only if it was accessed successfully.

The AncestorCategories property is a Recordset object with a single 128-character field, named Name.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Product Object

Product.ParentCategories


Product.CatalogName

The CatalogName property is a read-only String that contains the name of the catalog within which this product exists.

Definition

Property CatalogName As String

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Product Object


Product.CreateVariant

Use this method to create a new product variant of the current product. Only product specifc attributes will be set in the new variant.

Definition

Function CreateVariant(
varProductVariantID As Variant
) As Recordset

Parameters

varProductVariantID

A Variant that contains the unique ID of the product variant.

Return Values

If this method completes successfully, it returns a recordset that contains the properties for the variant.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_BLANK_VARIANT | &H8898004F | A blank value was specified for the VariantID.
E_CAT_CATALOG_DOESNT_SUPPORT_VARIANTS | &H88980032 | This catalog does not support product variants. This is determined when the catalog is created and cannot be changed.
E_CAT_INVALID_VARIANTID | &H8898005C | The VariantID exceeded 256 characters in length.
E_CAT_INVALIDVALUE_FOR_PROPERTY &H88980038 An invalid value was specified for one of the product properties.

This error can be due to:

  • One of the values in the recordset does not satisfy the requirements of the minimum value/maximum value attributes set for the properties.

  • An enumeration property has a value that is not defined in its list of legal values.

  • Strings exceed the maximum length defined for the property or are shorter than the minimum length.
E_CAT_INVALIDVALUE_FOR_VARIANTID &H8898004D An invalid value was specified for the VariantID.

This error can be due to the value of the VariantId being out of range.
E_CAT_NO_VARIANTS_UNDER_PRODUCT | &H88980051 | This product does not support variants. Variants cannot be created under a regular product.
E_CAT_PRODUCT_DOESNT_EXIST | &H8898001E | This product has been removed from the catalog.
E_CAT_VARIANT_EXISTS | &H88980026 | The specified variant already existed.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The value and type of the varProductVariantID parameter must be valid for the property specified as the unique ID for product variants. This property, strProductVariantID, is specified when a catalog is created.

If the catalog created does not support variants, that is strProductVariantID was not specified on catalog creation, an error is returned.

Upon successful completion, the method returns an ActiveX Data Object (ADO) recordset that contains fields for all the properties defined for the new product-variant and an integer field named oid. The oid field is for internal use and should not be updated. The returned recordset is updateable, but disconnected. In order to modify the variant properties, pass this recordset to the SetVariantProperties method.

The product-variants inherit the properties that are present in the product definition. Values for non variant-specific product properties are propagated from the Product object down to the variants, but values for variant-specific properties must be explicitly set for each variant.

The variant ID value should be unique within the product family. There can be two product variants with same variant IDs within the same catalog, as long as they are in different product families and the unique Product identifier and the unique Variant identifier are different.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

Set rsVariantProps = myProduct.CreateVariant("SKU4005XLA")

See Also

Product Object

Product.DeleteVariant

Product.SetVariantProperties


Product.DeleteVariant

Use this method to delete the specified product variant.

Definition

Sub DeleteVariant(
varVariantID As Variant
)

Parameters

varVariantID

A Variant that contains the unique ID of the variant.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_CATALOG_DOESNT_SUPPORT_VARIANTS | &H88980032 | This catalog does not support product variants. This is determined when the catalog is created and cannot be changed.
E_CAT_VARIANT_DOESNT_EXIST | &H8898001F | Variant did not exist.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

'vVarID is a Variant containing the unique ID
'for the product variant.
myProduct.DeleteVariant vVarID

See Also

Product Object

Product.CreateVariant


Product.GetProductProperties

The GetProductProperties property is a read-only recordset that contains the properties of this Product object.

Definition

Property GetProductProperties As Recordset

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_PRODUCT_DOESNT_EXIST | &H8898001E | This product has been deleted.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The GetProductProperties property contains valid data only if it was accessed successfully.

The returned single-row recordset contains all the fields defined for the product definition as well as all the common fields in the CatalogProduct Recordset.

The recordset returned is updateable, but disconnected. To modify the product properties, pass this recordset to the SetProductProperties method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Product Object

Product.SetProductProperties


Product.GetVariantProperties

Use this method to retrieve the properties for a specified product variant.

Definition

Function GetVariantProperties(
varProductVariantID As Variant
) As Recordset

Parameters

varProductVariantID

A Variant that contains the unique ID of the product variant.

Return Values

If this method completes successfully, it returns a Recordset object that contains the variant properties.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_CATALOG_DOESNT_SUPPORT_VARIANTS | &H88980032 | This catalog does not support product variants.
E_CAT_VARIANT_DOESNT_EXIST | &H8898001F | This product variant has been removed from the catalog.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The ppRSProductVariant property contains valid data only if it was accessed successfully.

This method returns the properties of the specified product variant. If the product variant specified in the varProductVariantID parameter does not exist in the product, the method will fail.

The single-row recordset returned contains fields for all of the properties defined for variants of this product followed by the following fields:

Field | Type | Description
TimeStamp | Timestamp | None
cy_list_price | Currency | List price
oid | Integer | None

The oid field is for internal use only and should not be updated.

The recordset returned is updateable, but disconnected. To modify the product properties, pass this recordset to the SetVariantProperties method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

'vVarID is a Variant containing the unique ID of the variant.
SET rsVariantProps = myProduct.GetVariantProperties(vVarID)

See Also

Product Object

Product.SetVariantProperties


Product.ParentCategories

The ParentCategories property is a read-only recordset that contains the names of categories that directly contain this product.

Definition

Property ParentCategories As Recordset

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

If the product is not contained in any categories, the returned recordset will be empty, and its EOF property will be set to VARIANT_TRUE.

The returned recordset will have a single 128-character String field called Name. Each row in the recordset will contain the name of a category containing this product.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Product Object

Product.AncestorCategories


Product.PricingCategory

The PricingCategory property is a read/write String that contains the name of the pricing category for this product.

Definition

Property PricingCategory As String

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_CATEGORY_DOESNT_EXIST | &H8898001C | The specified category did not exist.
E_CAT_PRICING_CAT_PRICELESS | &H8898002F | The specified category did not have a list price. Categories that do not have a list price cannot be used as a pricing category.
E_CAT_PRODUCT_DOESNT_EXIST | &H8898001E | This product has been deleted.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Using a category as a Pricing category allows you to set the prices of multiple products by making a single change, rather than having to change the price for each product. Setting the Pricing category for a product family will also set the Pricing category for all the variants of the product family.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Product Object


Product.ProductID

The ProductID property is a read-only String that contains the unique ID for this product.

Definition

Property ProductID As String

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The value of this property is a copy of the value of the IdentifyingProductProperty property of the catalog containing this product.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Product Object


Product.RelatedCategories

The RelatedCategories property is a read-only Recordset object that contains the names of categories that are related to this product.

Definition

Property RelatedCategories As _Recordset

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The RelatedCategories property contains valid data only if it was accessed successfully.

The returned recordset contains one row for each relationship present.

The returned recordset contains the following fields:

Field Data Type Description
CategoryName String
Maximum of 128 characters 		Name of the category.
RelationshipName String
Maximum of 128 characters 		Name of the relationship.
RelationshipDescription String
Maximum of 256 characters 		Description of the relationship.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Product Object

Product.RelatedProducts

Product.AddRelationshipToCategory


Product.RelatedProducts

The RelatedProducts property is a read-only Recordset object that contains the names of products that are related to this product.

Definition

Property RelatedProducts As Recordset

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The RelatedProducts property contains valid data only if it was accessed successfully.

The recordset returned contains one row for each relationship present.

The recordset returned contains the following fields:

Field | Data Type | Description
<defined ProductID field> | Varies | The field that uniquely defines a product in this catalog.
RelationshipName String
Maximum of 128 characters 		Name of the relationship.
RelationshipDescription String
Maximum of 128 characters 		Description of the relationship.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Product Object


Product.RemoveRelationshipToCategory

Use this method to remove the specified relationship between the specified category and this product.

Definition

Sub RemoveRelationshipToCategory(
strRelatedCategoryName As String,
strRelationshipName As String
)

Parameters

strRelatedCategoryName

A String that contains the name of the category that is to have its relationship to this product removed.

strRelationshipName

A String that contains the name of the relationship to be removed.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' Remove the "Accessory" relationship this product has to
' the "Apparel" category

myProduct.RemoveRelationshipToCategory "Apparel", "Accessory"

See Also

Product Object

Product.RelatedCategories

Product.AddRelationshipToCategory

Product.RemoveRelationshipToProduct


Product.RemoveRelationshipToProduct

Use this method to remove the specified relationship between the specified product and this product.

Definition

Sub RemoveRelationshipToProduct(
varRelatedProductID As Variant,
strRelationshipName As String
)

Parameters

varRelatedProductID

A Variant that contains the unique ID of the product that is to have its relationship to this product removed.

strRelationshipName

A String that contains the name of the relationship to be removed.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

''vProdID is a Variant containing the unique ID of the related product.
myProduct.RemoveRelationshipToProduct(vProdID, "Accessory")

See Also

Product Object

Product.RelatedProducts

Product.AddRelationshipToProduct

Product.RemoveRelationshipToCategory


Product.SetProductProperties

Use this method to set the properties for this product.

Definition

Sub SetProductProperties(
pRSProduct As Recordset,
Optional fForceUpdate As Variant
)

Parameters

pRSProduct

A Recordset object that contains the new product properties. This should be an updated recordset returned by the GetProductProperties method.

fForceUpdate

A Variant that determines whether to force an update of the product properties.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_INVALID_LISTPRICE | &H8898003C | The value specified for the list price was invalid.
E_CAT_INVALIDVALUE_FOR_PROPERTY &H88980038 An invalid value was specified for one of the product properties. This error was returned if:
  • One of the properties did not satisfy the Min/Max condition.

  • The properties of string or enumeration data type exceeded the maximum length.

  • The value of the enumeration property was not one of the legal values defined.
E_CAT_PRODUCT_CHANGED | &H88980027 | This product's properties were changed since they were last read. This error is returned only if the fForceUpdate parameter is set to False.
E_CAT_PRODUCT_DOESNT_EXIST | &H8898001E | The specified product ID did not exist.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Use the SetProductProperties method to modify the properties of a product. The pRSProduct parameter specifies a Recordset object that describes the new property values for this product. This method will not update the fields derived from the catalog such as ProductId and VariantID. If this method is called for a product family it will update the properties for all variants that belong to the Product family.

Use the Recordset object returned by the GetProductProperties property so that the timestamps can be compared to the records updated by this method for error detection.

If the fForceUpdate parameter is set to False, and the property values for this product have been changed since the pRSProduct record set was read, the method will fail.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

'This example changes the list price for a product
set rsProductProps = myProduct.GetProductProperties
rsProductProps.fields("cy_list_price").value = CCur(1.398)
myProduct.SetProductProperties rsProductProps, TRUE

See Also

Product Object

Product.GetProductProperties


Product.SetVariantProperties

Use this method to set the properties for a variant of this product.

Definition

Sub SetVariantProperties(
pRSNewState As _Recordset,
Optional fForceUpdate As Variant
)

Parameters

pRSNewState

A Recordset object that contains the new product variant properties. This should be a recordset returned by the GetVariantProperties property, or by the CreateVariant method.

fForceUpdate

A Variant that determines whether to force an update of the product variant properties.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_CATALOG_DOESNT_SUPPORT_VARIANTS | &H88980032 | Catalog does not support variants.
E_CAT_INVALIDVALUE_FOR_PROPERTY &H88980038 An invalid value was specified for one of the product properties. This error was returned if:
  • One of the properties did not satisfy the Min/Max condition.

  • The properties of string or enumeration data type exceeded the maximum length.

  • The value of the enumeration property was not one of the legal values defined.
E_CAT_PRODUCT_CHANGED | &H88980027 | This product's properties were changed since they were last read. This error is returned only if the fForceUpdate parameter is set to False.
E_CAT_VARIANT_DOESNT_EXIST | &H8898001F | This product variant has been removed from the catalog.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Use the SetVariantProperties method to modify the properties of a product variant. The pRSNewState parameter specifies a Recordset object that describes the new property values for this product variant. Use the recordset returned by the GetVariantProperties property, or by the CreateVariant method, so that timestamps can be compared for error detection.

If the fForceUpdate parameter is set to False, and the property values in the pRSNewState parameter have changed, the method will fail.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

myProduct.SetVariantProperties pRSNewState, fForceUpdate

See Also

Product Object

Product.GetVariantProperties


Product.Variants

The Variants property is a read-only recordset that describes all of the variants of this product.

Definition

Property Variants(
Optional strPropertyToSortOn As Variant
) As Recordset

Parameters

strPropertyToSortOn

A Variant that contains the property on which the returned Recordset object is to be sorted.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

If this product has no variants, the returned recordset will be empty, and its EOF property will be set to VARIANT_TRUE.

The recordset returned contains fields for all of the properties defined for variants of this product and the following fields:

Field | Type | Description
TimeStamp | Timestamp | None
cy_list_price | Currency | List price
<defined variant ID> | Varies | None

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

SET rsVariants = myProduct.Variants("Size")

See Also

Product Object


ProductCatalog Object

Use this object to alter catalogs and to modify catalog contents. The ProductCatalog object is the primary object for working with catalogs in the Product Catalog System.

ProgID: | Dependent (See Remarks for more information)
COM Class Name: | ProductCatalog
Type Library Name: | Microsoft Commerce 2000 Catalog Type Library
DLL Name: | Catalog.dll
Threading Model: | Both

The properties of the ProductCatalog object are shown in the following table.

Property | Type | Description
BaseCatalogName | BSTR | Contains the name of a base catalog for the custom catalog. This property is read-only.
CatalogName | BSTR | Contains the name of this catalog. This property is read-only.
IdentifyingProductProperty | String | Contains the name of the column used to uniquely identify products and product families. This property is read-only.
IdentifyingVariantProperty | String | Contains the name of the column used to uniquely identify product variants. This property is read-only.
RootCategories | _Recordset | Returns a recordset containing the names of categories that are the root categories for this catalog. This property is read-only.
RootProducts | _Recordset | Returns a recordset containing the products that are part of this catalog, but are not contained in any category. This property is read-only.
SearchableCategories | _Recordset | Returns a recordset with a single field that contains the names of the categories that are defined as searchable. This property is read-only.

The methods of the ProductCatalog object are shown in the following table.

Method | Description
AddSpecificationSearchClause | Adds a search constraint to the search context when performing a specification search of this catalog.
BeginSpecificationSearch | Initiates a specification search of this catalog.
CreateCategory | Creates a new category based on the specified category definition.
CreateCustomCatalog | Creates a new custom catalog template. The returned recordset is disconnected and updateable.
CreateProduct | Creates a new product based on the specified product definition.
DeleteCategory | Deletes a category from this catalog.
DeleteCustomCatalog | Deletes a custom catalog from this catalog.
DeleteProduct | Deletes a product from this catalog.
GenerateCustomCatalog | Populates the specified custom catalog template with data derived from this catalog.
GetCatalogAttributes | Returns the attributes of this catalog. The returned recordset is disconnected and updateable.
GetCategory | Returns the specified category.
GetCategoryCustomPrice | Returns the custom price of the specified category.
GetCustomCatalogAttributes | Returns the attributes of the specified custom catalog. The returned recordset is disconnected and updateable.
GetProduct | Returns the specified product.
GetProductVariant | Returns a recordset with a single row containing all of the properties for the specified product variant.
GetSpecificationSearchClauses | Returns a recordset with a single field containing all of the search clauses for a specification search.
GuaranteedSpecificationSearch | Performs a specification search in which search constraints are removed until a match is found.
PerformSpecificationSearch | Performs a specification search of this catalog using the specified search context.
RegenerateFreeTextSearchIndex | Updates the free text search index for this catalog.
RemoveSpecificationSearchClause | Removes the last search constraint from the specified search context.
SetCatalogAttributes | Sets attributes for this catalog.
SetCategoryCustomPrice | Defines a custom price for the specified category.
SetCustomCatalogAttributes | Sets attributes for the specified custom catalog.

Remarks

The ProductCatalog object is a dependent object. Obtain a reference to it by calling one of the following methods:

  • CatalogManager.GetCatalog

  • CatalogManager.CreateCatalog

Note

  • There is limit on the number of ProductCatalogs objects upon which you can search. Above 256 ProductCatalog objects, full-text search will break. This is a limitation of SQL Server 2000.


ProductCatalog.AddSpecificationSearchClause

Use this method to add constraints to a specification search of this catalog.

Definition

Sub AddSpecificationSearchClause(
strClause As String,
pstrSearchHandle As Variant
)

Parameters

strClause

A String that contains the clause to be added to the specified specification search.

pstrSearchHandle

A Variant that contains the state of the specification search to which the clause will be added. This variant is also used to return the updated state of the specification search.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The specification clause contained in the strClause parameter will be appended to the existing clauses and sent to SQL Server without any changes when the specification search is performed.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

myProductCatalog.AddSpecificationSearchClause strClause, pstrSearchHandle

See Also

ProductCatalog Object

ProductCatalog.BeginSpecificationSearch

ProductCatalog.GetSpecificationSearchClauses

ProductCatalog.PerformSpecificationSearch


ProductCatalog.BaseCatalogName

The BaseCatalogName property is a read-only string that contains the name of the base catalog for this catalog. If this is not a custom catalog, it does not have a base catalog, and the BaseCatalogName property contains the name of the catalog in hand.

Definition

Property BaseCatalogName() As String

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ProductCatalog Object


ProductCatalog.BeginSpecificationSearch

Use this method to initialize a specification search of a catalog.

Definition

Function BeginSpecificationSearch(
strCategoryName As String,
Optional pRSInitialPropValuesList As Variant,
Optional plTotalRecordsAvailable As Variant
) As String

Parameters

strCategoryName

A String that contains the name of the category in which to search.

pRSInitialPropValuesList

A Variant used to return the recordset of initial property values.

plTotalRecordsAvailable

A Variant used to return the total records available.

Return Values

If this method completes successfully, it returns a String that contains the state of this specification search.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_CATEGORY_DOESNT_EXIST | &H88980041 | The category you specified did not exist in the catalog.
E_CAT_CATEGORY_NOT_SEARCHABLE | &H88980034 | The specified category was not specification searchable.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The optional parameter pRSInitialPropValuesList is a single row recordset. The returned recordset contains one field for each searchable property for the products under the specified category. Each field contains a SAFEARRAY. Each SAFEARRAY contains a set of all the distinct values found in all the products under that category. Only the properties that are marked as searchable are returned in the recordset.

If all the searchable categories contain NULL values then pRSInitialPropValuesList parameter will be set to NULL and the plTotalRecordsAvailable parameter will be 0.

A category can be marked as searchable by setting the IsSearchable property to True.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

'
strSearchHandle = myProductCatalog.BeginSpecificationSearch(strCategoryName, pRSInitialPropValuesList)

See Also

ProductCatalog Object

ProductCatalog.AddSpecificationSearchClause

ProductCatalog.GetSpecificationSearchClauses

ProductCatalog.PerformSpecificationSearch


ProductCatalog.CatalogName

The CatalogName property is a read-only string that contains the name of this catalog.

Definition

Property CatalogName() As String

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ProductCatalog Object


ProductCatalog.CreateCategory

Use this method to create a new category.

Definition

Function CreateCategory(
strDefinitioName As String,
strCategoryName As String,
Optional strParentCategoryName As Variant,
Optional fIsSpecificationSearchable As Variant
) As Category

Parameters

strDefinitioName

A String that contains the name of the category definition on which the category is based.

strCategoryName

A String that contains the name of the category to be created.

strParentCategoryName

A Variant that contains the name of the category that will be a parent to this new category, if any.

fIsSpecificationSearchable

A Variant that determines whether or not this category is to be specification searchable.

Return Values

If this method completes successfully, it returns the newly created Category object.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_CATEGORY_DOESNT_EXIST | &H8898001C | The specified parent category did not exist.
E_CAT_CATEGORY_EXISTS | &H8898001D | The specified name for the new category was already in use. Category names must be globally unique across the entire system.
E_CAT_DEFINITION_DOESNT_EXIST | &H8898000B | The specified definition did not exist.
E_CAT_INVALID_CATEG_LENGTH | &H88980047 | The category name exceeded 128 characters.
E_CAT_PRODUCT_DEFN_FOR_CATEGORY | &H8898004B | The definition specified was not a category definition but a product definition.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

SET oMyCategory = myProductCatalog.CreateCategory("BasicCategoryDefinition", "T-Shirts", "Apparel", TRUE)

See Also

ProductCatalog Object

ProductCatalog.GetCategory

ProductCatalog.DeleteCategory


ProductCatalog.CreateCustomCatalog

Use this method to create a new template for a custom catalog.

Definition

Function CreateCustomCatalog(
strCCName As String
) As _Recordset

Parameters

strCCName

A String that contains the name of the custom catalog to be created.

Return Values

If this method completes successfully, it returns a recordset that contains the properties of the newly created custom catalog.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_CATALOG_EXISTS | &H88980001 | There was already a base catalog with the specified name. Catalog names and custom catalog names must be unique throughout the Product Catalog System.
E_CAT_CUSTOMCAT_EXISTS | &H88980022 | There was already a custom catalog with the specified name.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The following table shows the fields that the returned single-row recordset contains.

Field | Data Type | Description
CustomCatalogName | String 256 characters | The name of the custom catalog.
CatalogName | String 256 characters | The name of the base catalog.
CustomCatalogID | Integer | The field name that uniquely identifies custom catalogs.
TimeStamp | Timestamp | None.

The returned recordset is disconnected and updateable.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

SET rsMyCustomCat = myProductCatalog.CreateCustomCatalog("SeniorDiscountCatalog")

See Also

ProductCatalog Object

ProductCatalog.DeleteCustomCatalog

ProductCatalog.GenerateCustomCatalog

ProductCatalog.SetCategoryCustomPrice


ProductCatalog.CreateProduct

Use this method to create a new product within the catalog according to specified parameters.

Definition

Function CreateProduct(
strDefinitionName As String,
varProductID As Variant,
cyListPrice As Currency,
Optional strParentCategoryName As Variant
) As Product

Parameters

strDefinitionName

A String that contains the name of the product definition for the product.

varProductID

A Variant that contains the unique product ID for the product to be created. The data type must match the property used to uniquely identify products in this catalog.

cyListPrice

A Currency object that contains the list price of the product to be created.

strParentCategoryName

A Variant that contains the name of the category to be designated as the parent category of the product to be created.

Return Values

If this method completes successfully, it returns the Product object that was created.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_CATEGORY_DEFN_FOR_PRODUCT | &H8898004A | The specified definition was a category definition not a product definition
E_CAT_CATEGORY_DOESNT_EXIST | &H8898001C | The specified category did not exist.
E_CAT_DEFINITION_DOESNT_EXIST | &H8898000B | The specified definition did not exist.
E_CAT_PRODUCT_EXISTS | &H8898001B | The specified product ID was already in use. The product ID must be unique throughout the catalog.
E_CAT_INVALID_PRODUCTID | &H8898005B | The length of the ProductID exceeded 256 characters.
E_CAT_INVALIDVALUE_FOR_PRODUCTID | &H8898004E | An invalid value was specified for the ProductID

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

A product family is a product that has variants.

The properties of the definition on which a new product is based will determine whether the product being created is a single product or a product family. If the definition used to create the product has variant properties, the newly created product will be a product family.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

SET oMyNewProduct = myProductCatalog.CreateProduct("BasicProduct", "SKU3004", cyListPrice, "Apparel")

See Also

ProductCatalog Object

ProductCatalog.DeleteProduct

ProductCatalog.GetProduct


ProductCatalog.DeleteCategory

Use this method to delete a category from the Product Catalog System.

Definition

Sub DeleteCategory(
strCategoryName As String
)

Parameters

strCategoryName

A String that contains the name of the category to be deleted.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM error that this method can return.

Constant | Value | Description
E_CAT_CATEGORY_DOESNT_EXIST | &H8898001C | The specified category did not exist.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Any products or categories that existed in the deleted category, but not in another category, will be orphaned. Categories will become root categories and products will become root products. For example: CategoryA and CategoryB are child categories of CategoryX. CategoryA is also a child of CategoryY. When CategoryX is deleted, CategoryB will become a root category, but CategoryA will not.

If this category has been specified as a Pricing category for a custom catalog, it will be removed as the Pricing category. All the products using this category as a Pricing category will revert to their original price and the category will be removed as the Pricing category

Example

myProductCatalog.DeleteCategory "Apparel"

See Also

ProductCatalog Object

ProductCatalog.RootCategories

ProductCatalog.CreateCategory

ProductCatalog.GetCategory


ProductCatalog.DeleteCustomCatalog

Use this method to delete a custom catalog from the Product Catalog System.

Definition

Sub DeleteCustomCatalog(
strCCName As String
)

Parameters

strCCName

A String that contains the name of the custom catalog to be deleted.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

All data relating to the custom catalog will be deleted. If the custom catalog was generated, then the generated catalog will also be deleted.

Example

myProductCatalog.DeleteCustomCatalog "SeniorDiscountCatalog"

See Also

ProductCatalog Object

ProductCatalog.CreateCustomCatalog

ProductCatalog.GenerateCustomCatalog


ProductCatalog.DeleteProduct

Use this method to delete a product from the Product Catalog System.

Definition

Sub DeleteProduct(
varProductID As Variant
)

Parameters

varProductID

A Variant that contains the unique identifier of the product to be deleted.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM error that this method can return.

Constant | Value | Description
E_CAT_CATALOG_DOESNT_EXIST | &H88980002 | The catalog did not exist.
E_CAT_PRODUCT_DOESNT_EXIST | &H88980010 | The specified product did not exist.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

This method removes the product from the SQL Server database. The Product object caches information for improved performance. Because of this cache, the CatalogName and ProductID methods of the Product object will continue to return the old values after the DeleteProduct method has been called. The Variants, ParentCategories, AncestorCategories, RelatedCategories, and RelatedProducts properties will return an empty recordset and no error message.

Caution

  • Deleting a product with variants also deletes all of the variants.

Example

myProductCatalog.DeleteProduct 654321

See Also

ProductCatalog Object

ProductCatalog.CreateProduct

ProductCatalog.GetProduct


ProductCatalog.GenerateCustomCatalog

Use this method to populate a custom catalog with data or to update a custom catalog to reflect the latest version of the base catalog. A copy of the base catalog is made and custom prices and rules are applied to generate the custom catalog.

Definition

Sub GenerateCustomCatalog(
strCustomCatalogName As String
)

Parameters

strCustomCatalogName

A String that contains the custom catalog name.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM error that this method can return.

Constant | Value | Description
E_CAT_CUSTOMCAT_DOESNT_EXIST | &H88980024 | The specified custom catalog did not exist.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Use this method to populate a custom catalog template with data. If the custom catalog already exists then the existing data will be deleted. The generated custom catalog is a copy of the base catalog at the moment when it is populated by this method. The prices of the products in the custom catalog are determined by applying the custom pricing rule that has been set with the SetCategoryCustomPrice method. After the custom catalog has been generated by this method, the custom catalog can be treated as any other catalog.

Because custom catalogs are only copies of an existing base catalog, and are not dynamically linked to the base catalog, any changes made to the base catalog will not be automatically reflected in any custom catalogs derived from it. Similarly, any changes made to a custom catalog will not automatically propagate back to the base catalog. Use this method to update the custom catalog to reflect the latest version of the base catalog.

Note

  • This method cannot be called in a transacted object. This method involves the creation, deletion, or updating of free text indexes. SQL Server does not allow these operations in a transaction.

Example

myProductCatalog.GenerateCustomCatalog "SeniorDiscountCatalog"

See Also

ProductCatalog Object

ProductCatalog.CreateCustomCatalog

ProductCatalog.DeleteCustomCatalog

ProductCatalog.SetCategoryCustomPrice


ProductCatalog.GetCatalogAttributes

Use this method to retrieve the attributes of this catalog. The returned recordset is disconnected and updateable.

Definition

Function GetCatalogAttributes() As _Recordset

Parameters

None.

Return Values

If this method completes successfully, it returns a recordset that contains the attributes of this catalog.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The returned recordset is disconnected and updateable. The following table shows the fields that the returned recordset contains.

Field | Data Type | Description
CatalogName | String 128 characters | The name of the catalog.
Locale | Integer | None.
StartDate | Datetime | None.
End Date | Datetime | None.
VariantID | String 128 characters | The field name that uniquely identifies variants.
ProductID | String 128 characters | The field name that uniquely identifies products.
Currency | String 128 characters | None.
WeightMeasure | String 128 characters | None.
TimeStamp | Timestamp | None.
CatalogID | Integer | None.
CustomCatalog | Boolean | A flag indicating whether this is a custom catalog. True indicates a custom catalog.
FreeTextIndexCreated | Datetime | None.
ProductTableUpdated | Datetime | None.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

SET rsMyCatAttribs = myProductCatalog.GetCatalogAttributes

See Also

ProductCatalog Object

ProductCatalog.GetCustomCatalogAttributes

ProductCatalog.SetCatalogAttributes


ProductCatalog.GetCategory

Use this method to retrieve the specified category from a catalog.

Definition

Function GetCategory(
strCategoryName As String
) As Category

Parameters

strCategoryName

A String that contains the name of the category to be returned.

Return Values

If this method completes successfully, it returns the Category object specified.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following standard COM error value has a particular meaning in the context of this method:

S_FALSE

The catalog specified did not exist.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

SET oMyCategory = myProductCatalog.GetCategory "Apparel"

See Also

ProductCatalog Object

ProductCatalog.CreateCategory

ProductCatalog.DeleteCategory


ProductCatalog.GetCategoryCustomPrice

Use this method to retrieve the custom price and custom price type for a specified custom catalog and category.

Definition

Sub GetCategoryCustomPrice(
strCCName As String,
strCategoryName As String,
peCustomPrice As Variant,
pfpCustomPriceAmount As Variant
)

Parameters

strCCName

A String that contains the name of the custom catalog.

strCategoryName

A String that contains the category name for which the custom price will be returned.

peCustomPrice

A Variant used to return the type of the custom price. Valid values are from the CatalogCustomPriceEnum enumeration, and are described in the Remarks section below.

pfpCustomPriceAmount

A Variant used to return the custom price adjustment.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_CATEGORY_DOESNT_EXIST | &H8898001C | The specified category did not exist.
E_CAT_CUSTOMCAT_DOESNT_EXIST | &H88980024 | The specified custom catalog did not exist.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The following table shows the values of the CatalogCustomPriceEnum enumeration, their associated names, and describes their use.

Name | Value | Description
cscNoCustomPrice | 0 | The custom price is the same as the base price.
cscPercentageMultiplier | 1 | The custom price is the base price multiplied by the percentage value in the pfpCustomPriceAmount parameter.
cscAddFixedAmount | 2 | The custom price is the pfpCustomPriceAmount added to the base price.
cscReplacePrice | 3 | The custom price is the pfpCustomPriceAmount.
cscInvalidCustomPrice | -1 | Reserved for future use.

If the Category has not been specified as a Custom Category then the peCustomPrice parameter and the pfpCustomPriceAmount parameter will be set to 0.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

myProductCatalog.GetCategoryCustomPrice "SeniorDiscout", "Shoes", cscPercentageMultiplier, 90

See Also

ProductCatalog Object

ProductCatalog.SetCategoryCustomPrice


ProductCatalog.GetCustomCatalogAttributes

Use this method to retrieve the attributes for a specified custom catalog.

Definition

Function GetCustomCatalogAttributes(
strCCName As String
) As _Recordset

Parameters

strCCName

A String that contains the name of the custom catalog.

Return Values

If this method completes successfully, it returns a recordset that contains the custom catalog attributes.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The following table shows the fields that the returned single-row recordset contains.

Field | Data Type | Description
CustomCatalogName | String Maximum of 128 unicode characters | The name of the custom catalog.
CatalogName | String Maximum of128 unicode characters | The name of the base catalog.
CustomCatalogID | Integer | The field name that uniquely identifies custom catalogs.
TimeStamp | Timestamp | None.

The returned recordset is disconnected and updateable. The CustomCatalogName parameter is the only field that can be modified.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

SET rsMyCustomCatAttribs = myProductCatalog.GetCustomCatalogAttributes("SeniorDiscountCatalog")

See Also

ProductCatalog Object

ProductCatalog.CreateCustomCatalog

ProductCatalog.SetCustomCatalogAttributes


ProductCatalog.GetProduct

Use this method to retrieve the specified product from a catalog.

Definition

Function GetProduct(
varProductID As Variant
) As Product

Parameters

varProductID

A Variant that contains the unique identifier of the product.

Return Values

If this method completes successfully, it returns the product specified.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following standard COM error value has a particular meaning in the context of this method:

S_FALSE

The catalog specified did not exist.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

SET oMyProduct = myProductCatalog.GetProduct("SKU4005")

See Also

ProductCatalog Object

ProductCatalog.CreateProduct

ProductCatalog.DeleteProduct


ProductCatalog.GetProductVariant

Use this method to retrieve the properties of a specified product variant.

Definition

Function GetProductVariant(
varProductID As Variant,
varVariantID As Variant
) As _Recordset

Parameters

varProductID

A Variant that contains the unique identifier of the product family.

varVariantID

A Variant that contains the unique identifier of the product variant.

Return Values

If this method completes successfully, it returns a recordset that contains the properties of the specified variant.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_CATALOG_DOESNT_SUPPORT_VARIANTS | &H88980032 | This catalog does not support variants. This is determined when the catalog is created and cannot be changed.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

A single row recordset with all the properties of the variant is returned. The fields of the returned recordset are determined by the properties associated with the definition on which it is based. Both the product properties and the variant properties are returned.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

SET rsVariantProps = myProductCatalog.GetProductVariant("SKU4007", "Blue")

See Also

ProductCatalog Object

ProductCatalog.IdentifyingVariantProperty


ProductCatalog.GetSpecificationSearchClauses

Use this method to retrieve the specified specification search constraints.

Definition

Function GetSpecificationSearchClauses(
strSearchHandle As String
) As _Recordset

Parameters

strSearchHandle

A String that contains the specification search handle.

Return Values

If this method completes successfully, it returns a recordset that contains the specification search clauses.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The returned recordset contains a single variable-length String field, called Clause, and one row for each constraint present.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

'strSearchHandle contains a search handle returned
'from AddSpecificationSearchClause or BeginSpecificationSearch
SET rsMySearchClauses = myProductCatalog.GetSpecificationSearchClauses(strSearchHandle)

See Also

ProductCatalog Object

ProductCatalog.AddSpecificationSearchClause

ProductCatalog.RemoveSpecificationSearchClause


ProductCatalog.GuaranteedSpecificationSearch

Use this method to guarantee results when performing a specification search of a catalog.

Definition

Function GuaranteedSpecificationSearch(
pstrSearchHandle As Variant,
Optional eClassTypeRequired As Variant,
Optional lDesiredRecords As Variant,
Optional plTotalRecordsAvailable As Variant,
Optional pRSNewPropValuesList As Variant,
Optional vrPropertiesRequired As Variant
) As _Recordset

Parameters

pstrSearchHandle

A Variant that contains the specification search handle.

eClassTypeRequired

A Variant that contains the catalog class desired. Valid values are from the CatalogClassTypeEnum enumeration, and are described in the Remarks section below.

lDesiredRecords

A Variant that contains the number of records desired.

plTotalRecordsAvailable

A Variant used to return the total records available.

pRSNewPropValuesList

A Recordset used to return the new property values list.

vrPropertiesRequired

A Variant that contains the properties required in a comma-delimited String.

Return Values

If this method completes successfully, it returns a recordset that contains the search results.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors, and the standard COM errors with special meanings, that this method can return.

Constant | Value | Description
S_FALSE &H00000001 This value is returned when the pRSNewPropValuesList parameter is specified and:
  • There are no properties in the catalog that are marked for specification search.

  • There are no products under the category selected for specification search.
E_CAT_CATEGORY_NOT_EXISTS_NOT_SEARCHABLE | &H88980049 | The category you specified did not exist or was not specification searchable.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

This method is similar to the PerformSpecificationSearch method. The optional output parameter, pRSNewPropValuesList, is a single row recordset. This recordset contains one field for each searchable property for the products under the category specified in the BeginSpecificationSearch method. Each field contains a SAFEARRAY. The SAFEARRAY contains a set of distinct values for that property. The set is all the values in all the products that match the search clauses in the search handle. Only the properties that are marked as searchable are returned in the recordset. A property can be marked as searchable by setting the IncludeInSpecSearch attribute of that property to True.

This method guarantees that results will be returned from a specification search of the catalog by removing search constraints in the reverse order that they were added until a match is found. Therefore, remember to add constraints to a specification search in order of decreasing importance.

The Recordset object returned by this method will contain a field for each property name in the vrPropertiesRequired parameter. If the parameter is omitted, the Recordset object will contain all of the corresponding fields. For more information about these fields, see CatalogProduct Recordset.

Note

  • When field names begin with a number or contain spaces they must be enclosed in brackets. Data errors will occur if the field names are not formatted correctly. For example, "[123_Prop1],[123_ Prop2]". If the vrPropertiesRequired property is omitted then the data in all fields will be returned correctly.

The following table shows the values of the CatalogClassTypeEnum enumeration, their associated names, and describes their use.

Name | Value | Description
cscCategoryClass | 1 | Requests category data.
cscProductVariantClass | 2 | Requests product variant data.
cscProductClass | 4 | Requests product data.
cscProductFamilyClass | 8 | Requests product family data.
cscProductFamilyForVariantsClass | 16 | Requests family for variant data, which means the product family of a product variant is being requested.
cscProductVariantsForFamily | 32 | Requests variants for family data, which means that all of the product variants for a product family are being requested.

CatalogClassTypeEnum values can be combined in the eClassTypeRequired parameter with logical ORs , so that specifying cscProductClass OR cscProductVariantClass will return both product and product variant data.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

'strSearchHandle contains a search handle returned
'from AddSpecificationSearchClause or BeginSpecificationSearch
'The following parameters should be examined after the call returns.
'plTotalRecordsAvailable is a Long
'pRSNewPropValuesList is an empty recordset
SET rsMySearchResults = myProductCatalog.GuaranteedSpecificationSearch('strSearchHandle , 20, plTotalRecordsAvailable, pRSNewPropValuesList)

See Also

ProductCatalog Object

ProductCatalog.AddSpecificationSearchClause

ProductCatalog.PerformSpecificationSearch

ProductCatalog.RemoveSpecificationSearchClause


ProductCatalog.IdentifyingProductProperty

The IdentifyingProductProperty property is a read-only String that contains the name of the unique identifier field for the products in this catalog.

Definition

Property IdentifyingProductProperty() As String

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The product id is cached in the ProductCatalog object. Because of the cache, this method will continue to return the old value after the catalog has been deleted.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ProductCatalog Object

ProductCatalog.IdentifyingVariantProperty


ProductCatalog.IdentifyingVariantProperty

The IdentifyingProductVariantProperty property is a read-only String that contains the name of the unique identifier field for product variants in this catalog.

Definition

Property IdentifyingVariantProperty() As String

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The variant id is cached in the ProductCatalog object. Because of the cache, this method will continue to return the old value after the catalog has been deleted.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ProductCatalog Object

ProductCatalog.IdentifyingProductProperty


ProductCatalog.PerformSpecificationSearch

Use this method to perform a specification search of a catalog.

Definition

Function PerformSpecificationSearch(
strSearchHandle As String,
Optional eClassTypeRequired As Variant,
Optional lDesiredRecords As Variant,
Optional plTotalRecordsAvailable As Variant,
Optional pRSNewPropValuesList As Variant,
Optional vrPropertiesRequired As Variant
) As _Recordset

Parameters

strSearchHandle

A String that contains the name of the search to perform.

eClassTypeRequired

A Variant that contains the catalog class desired. Valid values are from the CatalogClassTypeEnum enumeration, and are described in the Remarks section below.

lDesiredRecords

A Variant that contains the records desired.

plTotalRecordsAvailable

A Variant used to return the total number of records available.

pRSNewPropValuesList

A Variant used to return the Recordset of the new property values list.

vrPropertiesRequired

A Variant that contains the properties required in a comma-delimited String.

Return Values

If this method completes successfully, it returns a recordset that contains the search results.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
S_FALSE &H00000001 This value is returned when the pRSNewPropValuesList parameter is supplied and:
  • There are no properties in the catalog that are marked for specification search.

  • There are no products under the category selected for specification search.
E_CAT_CATEGORY_NOT_EXISTS_NOT_SEARCHABLE | &H88980049 | The category you specified did not exist or was not specification searchable.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The PerformSpecificationSearch method executes a query using all of the constraints that have been added to the specified specification search handle.

The optional output parameter, pRSNewPropValuesList, is a single row recordset. This recordset contains one field for each searchable property for the products under the category specified in the BeginSpecificationSearch method. Each field contains a SAFEARRAY. The SAFEARRAY contains a set of distinct values for that property. The set is all the values in all the products that match the search clauses in the search handle. Only the properties that are marked as searchable are returned in the recordset. A property can be marked as searchable by setting the IncludeInSpecSearch attribute of that property to True.

The Recordset object returned by this method will contain a field for each property name in the vrPropertiesRequired parameter. It will always contain a CatalogName field. If the parameter is omitted, the Recordset object will contain all of the corresponding fields. For more information about these fields, see CatalogProduct Recordset.

Note

  • When field names begin with a number or contain spaces they must be enclosed in brackets. Data errors will occur if the field names are not formatted correctly. For example, "[123_Prop1],[123_ Prop2]". If the vrPropertiesRequired property is omitted then the data in all fields will be returned correctly.

The following table shows the values of the CatalogClassTypeEnum enumeration, their associated names, and describes their use.

Name | Value | Description
cscCategoryClass | 1 | Requests category data.
cscProductVariantClass | 2 | Requests product variant data.
cscProductClass | 4 | Requests product data.
cscProductFamilyClass | 8 | Requests product family data.
cscProductFamilyForVariantsClass | 16 | Requests family for variant data, which means the product family of a product variant is being requested.
cscProductVariantsForFamily | 32 | Requests variants for family data, which means that all of the product variants for a product family are being requested.

CatalogClassTypeEnum values can be combined in the eClassTypeRequired parameter with logical OR operators, so that specifying cscProductClass OR cscProductVariantClass will return both product and product variant data.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

'strSearchHandle contains a search handle returned
'from AddSpecificationSearchClause or BeginSpecificationSearch
'The following parameters should be examined after the call returns.
'plTotalRecordsAvailable is a Long
'pRSNewPropValuesList is an empty recordset
SET rsSearchResults = myProductCatalog.PerformSpecificationSearch(strSearchHandle, 20, plTotalRecordsAvailable, pRSNewPropValuesList)

See Also

ProductCatalog Object

ProductCatalog.AddSpecificationSearchClause

ProductCatalog.BeginSpecificationSearch

ProductCatalog.GuaranteedSpecificationSearch

ProductCatalog.RemoveSpecificationSearchClause


ProductCatalog.RegenerateFreeTextSearchIndex

Use this method to regenerate the free text search index of a catalog.

Definition

Sub RegenerateFreeTextSearchIndex(
fGenerateIncremental As Boolean
)

Parameters

fGenerateIncremental

A Boolean that determines whether an incremental or a full rebuild of the free text search index is to be performed. A value of True indicates an incremental rebuild. A value of False indicates a full rebuild. See the Remarks section for more information. The default value is False.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_CANNOT_REFRESH | &H8898004C | A catalog import operation is currently in progress. The refresh operation cannot be performed now.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

This method should be called after new products or categories are added to a catalog. Otherwise, those new products and categories will not be returned in any free text search results.

The fGenerateIncremental parameter determines what type of free text index rebuild to perform. The default is to completely rebuild the free text index. Though this option ensures completeness, it is slower than an incremental rebuild, which appends only recently added products and categories to the index.

If the database in which Commerce Server keeps its catalog data does not have the SQL Server 2000 full-text engine installed, this method will return with no action.

Note

  • This method cannot be called in a transacted object. This method involves the creating, deleting, or updating of free text indexes. SQL Server does not allow these operations in a transaction.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

myProductCatalog.RegenerateFreeTextSearchIndex TRUE

See Also

ProductCatalog Object


ProductCatalog.RemoveSpecificationSearchClause

Use this method to remove the last constraint from a specified specification search.

Definition

Function RemoveSpecificationSearchClause(
pstrSearchHandle As Variant
) As String

Parameters

pstrSearchHandle

A Variant that contains the specification search handle from which a constraint is to be removed.

Return Values

If this method completes successfully, it returns a String that contains the removed clause.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

This method always removes the last constraint that was added to the search using the AddSpecificationSearchClause method. The returned string will be in the same form as the original constraint.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

'strSearchHandle contains a search handle returned
'from AddSpecificationSearchClause or BeginSpecificationSearch
'strRemovedClause will contain the removed clause after the call returns.
Set strRemovedClause = myProductCatalog.RemoveSpecificationSearchClause(strSearchHandle)

See Also

ProductCatalog Object


ProductCatalog.RootCategories

The RootCategories property is a read-only recordset that contains the names of the categories that exist at the root level of this catalog.

Definition

Property RootCategories(
Optional vrPropertiesRequired As Variant
) As _Recordset

Parameters

vrPropertiesRequired

A VARIANT, subtype String, that contains a comma-separated list of the required property names.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Any category without parents is considered to be a root category.

The Recordset object returned by this method will contain one row for each root category, and a field for each property name in the vrPropertiesRequired parameter. If the parameter is omitted, the Recordset object will contain all of the corresponding fields. For more information about these fields, see CatalogProduct Recordset.

Note

  • Leading numbers in the property names in the vrPropertiesRequired parameter will be trimmed from the corresponding field names in the returned recordset. The data will be correct; only the field names will be incorrect. If the property is omitted, then the field names will be correct. Enclose field names that begin with a number in brackets to avoid this problem. For example, oProductCatalog.RootCategories("[123_Prop1],[123_ Prop2]").

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ProductCatalog Object

ProductCatalog.RootProducts


ProductCatalog.RootProducts

The RootProducts property is a read-only recordset that contains the products that exist at the root level of a catalog.

Definition

Property RootProducts() As _Recordset

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Any product that is not contained within a category is considered to be a root product.

The Recordset object returned by this method will contain all of the corresponding fields. For more information about these fields, see CatalogProduct Recordset.

Products added by importing a comma-separated value (CSV) file will be root products.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

SET rsRootProducts = myProductCatalog.RootProducts

See Also

ProductCatalog Object

ProductCatalog.RootCategories


ProductCatalog.SearchableCategories

The SearchableCategories property is a read-only recordset that contains the names of all searchable categories.

Definition

Property SearchableCategories() As _Recordset

Parameters

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The SearchableCategories property returns the names of all the categories in this catalog that can be queried using a specification search. Whether or not a particular category is specification searchable is determined by the value of the IsSearchable attribute. This property can be set at the time the category is created, or can be changed at any time using the SetCategoryProperties methods of the category object.

The Recordset object returned by this property will contain a single 128-character field called Name. Each row will contain the name of a searchable category.

If there are no searchable categories, a recordset with its EOF property set to VARIANT_TRUE will be returned.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ProductCatalog Object

ProductCatalog.CreateCategory

ProductCatalog.GetCategory


ProductCatalog.SetCatalogAttributes

Use this method to set the attributes of a catalog.

Definition

Sub SetCatalogAttributes(
pRSCatalogAttributes As _Recordset,
Optional fForceUpdate As Variant
)

Parameters

pRSCatalogAttributes

A Recordset containing the new attributes.

fForceUpdate

A Variant that causes a forced update of the catalog attributes.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_CATALOG_DOESNT_EXIST | &H88980002 | The catalog did not exist.
E_CAT_CATALOG_CHANGED | &H88980012 | The catalog has been updated since it was last read.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Use the GetCatalogAttributes method to get a recordset of the current attributes. After the recordset has been modified, use it as the pRSCatalogAttributes parameter to the SetCatalogAttributes method to write the changes back to the catalog. The timestamps in the recordset will be compared to the timestamps of the attributes being updated for error detection.

The catalog Name, ProductID, CatalogID, and VariantID attributes cannot be changed with this method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

myProductCatalog.SetCatalogAttributes(rsCatalogAttribs, TRUE)

See Also

ProductCatalog Object

ProductCatalog.GetCatalogAttributes


ProductCatalog.SetCategoryCustomPrice

Use this method to set a custom price rule for a category.

Definition

Sub SetCategoryCustomPrice(
strCCName As String,
strCategoryName As String,
eCustomPrice As CatalogCustomPriceEnum,
fpCustomPriceAmount As Double
)

Parameters

strCCName

A String that contains the name of the custom catalog template for which this rule will apply.

strCategoryName

A String that contains the name of the category for which a custom price will be set.

eCustomPrice

The type of price adjustment. Valid values are from the CatalogCustomPriceEnum enumeration, and are described in the Remarks section below.

fpCustomPriceAmount

A Double that contains the custom price adjustment amount.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM error that this method can return.

Constant | Value | Description
E_CAT_CATEGORY_DOESNT_EXIST | &H8898001C | The category did not exist.
E_CAT_CUSTOMCAT_DOESNT_EXIST | &H88980024 | The specified custom catalog did not exist.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The SetCategoryCustomPrice method defines a custom pricing rule for a category, and all the immediate child products of that category, in the specified custom catalog. The SetCategoryCustomPrice method does not affect child categories.

If a product exists within multiple categories, each having different custom prices, the custom price will not be applied to that product for either category.

The following table shows the values of the CatalogCustomPriceEnum enumeration, their associated names, and describes their use.

Name | Value | Description
cscNoCustomPrice | 0 | The custom price is the same as the base price.
cscPercentageMultiplier | 1 | The custom price is the base price multiplied by the percentage value in the pfpCustomPriceAmount parameter.
cscAddFixedAmount | 2 | The custom price is the pfpCustomPriceAmount added to the base price.
cscReplacePrice | 3 | The custom price is the pfpCustomPriceAmount.
cscInvalidCustomPrice | -1 | Reserved for future use.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

myProductCatalog.SetCategoryCustomPrice "SeniorDiscountCatalog", "Apparel", cscPercentageMultiplier, 90

See Also

ProductCatalog Object

ProductCatalog.GetCategoryCustomPrice


ProductCatalog.SetCustomCatalogAttributes

Use this method to set the attributes of a custom catalog.

Definition

Sub SetCustomCatalogAttributes(
pRSNewState As _Recordset,
Optional fForceUpdate As Variant
)

Parameters

pRSNewState

A Recordset object containing the new attributes.

fForceUpdate

A Variant that causes a forced update of the custom catalog attributes.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM error that this method can return.

Constant | Value | Description
E_CAT_CANNOT_ALTER_CC | &H88980060 | The specified changes could not be made.
E_CAT_CUSTOMCATALOG_CHANGED | &H88980035 | The custom catalog has been altered since it was last read.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Use the SetCustomCatalogAttributes method to modify the CustomCatalogName attribute of a custom catalog. No other attributes can be modified. The pRSNewState parameter specifies a Recordset object that describes the new attribute values for this custom catalog. The method will fail if the custom catalog has already been published.

Use the Recordset object returned by the GetCustomCatalogAttributes method so that its timestamp can be compared for quality assurance.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

myProductCatalog.SetCustomCatalogAttributes rsNewAttribs, TRUE

See Also

ProductCatalog Object

ProductCatalog.GetCustomCatalogAttributes


CatalogProduct Recordset

The fields in this Recordset object will vary, depending on the product definitions in the catalog. The following table contains a list of common fields that will always be part of this Recordset object.

Field name | Data type
CategoryName | String Maximum of 128 characters
Oid | Integer
DefinitionName | String Maximum of 128 characters
IsSearchable | Small integer
cy_list_price | Money
PricingCategoryOID | Integer
TimeStamp | TimeStamp
OriginalPrice | Money
i_ClassType | Integer
ParentOID | Integer
ProductID | String Maximum of 256 characters
VariantID | String Maximum of 256 characters

Note

  • The Oid field is for internal use and should not be updated.

See Also

ProductCatalog.GuaranteedSpecificationSearch

ProductCatalog.PerformSpecificationSearch

ProductCatalog.RootCategories

ProductCatalog.RootProducts


ProfileObject Object

Use this object to retrieve the data in specific profile object instances and modify the property values for that profile object. In addition, use the ProfileObject object to examine and navigate the property attributes of a profile object.

ProgID: | Commerce.ProfileObject (Externally creatable)
COM Class Name: | ProfileObject
Type Library Name: | Microsoft Commerce 2000 Profile Service Type Library
DLL Name: | mscsups.dll
Threading Model: | Both

The properties of the ProfileObject object are shown in the following table.

Property | Type | Description
Fields | Object | Stores the profile property collection. This property is read-only.

The methods of the ProfileObject object are shown in the following table.

Method | Description
GetProfileXML | Retrieves an XML fragment representing the data structure of the profile object.
Update | Saves the profile data to the underlying data store.

Remarks

The ProfileObject object maintains backward compatibility with the AUO 1.0 object (released in Microsoft Site Server 3.0 Commerce Edition) by inheriting from the IADs interface. Refer to the MSDN ADSI documentation for descriptions of the methods of the IADs interface.

The ProfileObject object supports extended dot notation. For example, using extended dot notation, the following:

oProfileObject.Fields("Address.Zipcode")

is equivalent to:

oProfileObject.Fields("Address").Value("Zipcode")

The first technique retrieves the Zipcode value in a single call to Fields.Value, while the second technique requires two calls to retrieve the same value.

The ProfileObject object also provides smart navigation into profiles. For example, using smart navigation, the following:

oProfileObject.Address.ZipCode

is equivalent to:

oProfileObject.Fields("Address.Zipcode")

In general, the CreateProfile method of the ProfileService object is used to instantiate this object.

See Also

Profile Objects

Profile Schema

Profile XML Structures

ProfileService Object


ProfileObject.Fields

The Fields property is a read-only Fields collection that contains the profile property data for the ProfileObject object. Read-only refers to the inability to add or delete members (profile properties) of the Fields collection. This property is the default property of the ProfileObject object. Use this property to set and retrieve profile property values and to navigate the attribute list of the properties.

Definition

Property Fields As Object

Parameters

None.

Error Values

The Errors property of the ProfileService object stores the collection of errors encountered in the last Profiles resource operation. For more information, see ProfileService.Errors.

Remarks

The Fields collection is similar to an ADO Fields collection object. The following ADO Fields methods and properties are supported:

  • Count

  • Item

  • _NewEnum

A member of the Fields collection is a Field object that represents a single property or property group of a ProfileObject object. The Field object is similar to an ADO Field object. The following ADO Field methods and properties are supported:

  • Properties - Returns the read-only Attributes collection.

  • DefinedSize - Retrieves the defined size of the data type.

  • Name

  • Type

  • Value

The Attributes collection is represented as an ADO Properties object. The following ADO Properties methods and properties are supported:

  • Count

  • Item

  • _NewEnum

Use the Update method of the ProfileObject object to save any changed profile data in the underlying data store.

The Fields property of the ProfileObject object supports extended dot notation for increased performance. For example, using extended dot notation, the following:

oProfileObject.Fields("Address.Zipcode")

is equivalent to:

oProfileObject.Fields("Address").Value("Zipcode")

For information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ProfileObject Object

ProfileService Object


ProfileObject.GetProfileXML

Use this method to retrieve the XML schema and data of the profile object.

Definition

Function GetProfileXML (
eRetrieveEnum As XMLRetrieveEnum,
bAttributeCentric As Boolean
) As String

Parameters

eRetrieveEnum

[in] An Enum that indicates whether to retrieve the XML schema, data, or both.

bAttributeCentric

[in] A Boolean that indicates if the XML output format. Set this parameter to True (1) to retrieve the XML in an attribute-centric format, and to False (0) to retrieve the XML in an element-centric format.

Return Values

This method returns a String containing the XML representation of the profile object.

Error Values

The Errors property of the ProfileService object stores the collection of errors encountered in the last Profiles resource operation. For more information, see ProfileService.Errors.

Remarks

The following table defines the possible values for XMLRetrieveEnum.

Name | Value | Description
psRetrieveInvalidValue | 0 | Invalid option
psRetrieveSchemaAndData | 1 | Both the schema and data are retrieved.
psRetrieveDataOnly | 2 | Only the data is retrieved.
psRetrieveSchemaOnly | 3 | Only the schema is retrieved.

For information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' sXMLProfile is a String, oProfileObject is a UserObject profile

sXMLProfile = oProfileObject.GetProfileXML(psRetrieveDataOnly, True)

' The attribute-centric sXMLProfile string now contains:
   <?xml version="1.0"?>
   <ProfileDocument>
   <UserObject>
      <AccountInfo  org_id="{590858E1-08A7-11D3-B8C4-00104B95AE0E}"
         account_status="1" date_registered="2000- 6- 5T 0: 0: 0">
      </AccountInfo>
      <GeneralInfo  user_id="{590858DB-08A7-11D3-B8C4-00104B95FFFF}"
         logon_name="jilluser@microsoft.com"
         user_security_password="password" user_title="" last_name="User"
         first_name="Jill" user_id_changed_by="admin">
      </GeneralInfo>
   </UserObject>
   </ProfileDocument>

sXMLProfile = oProfileObject.GetProfileXML(psRetrieveDataOnly, False)

' The element-centric sXMLProfile string now contains:
   <?xml version="1.0"?>
   <ProfileDocument>
   <UserObject>
      <AccountInfo>
         <org_id>{590858E1-08A7-11D3-B8C4-00104B95AE0E}</org_id>
         <account_status>1</account_status>
         <date_registered>2000- 6- 5T 0: 0: 0</date_registered>
      </AccountInfo>
      <GeneralInfo
         <user_id>{590858DB-08A7-11D3-B8C4-00104B95FFFF}</user_id>
         <logon_name>jilluser@microsoft.com</logon_name>
         <user_security_password>password</user_security_password>
         <user_title></user_title>
         <last_name>User</last_name>
         <first_name>Jill</first_name>
         <user_id_changed_by>admin</user_id_changed_by>
      </GeneralInfo>
   </UserObject>
   </ProfileDocument>

See Also

ProfileObject Object

ProfileObject.Fields

Profile XML Structures


ProfileObject.Update

Use this method to save ProfileObject object data to the underlying data store.

Definition

Sub Update()

Parameters

None.

Return Values

None.

Error Values

The Errors property of the ProfileService object stores the collection of errors encountered in the last Profiles resource operation. For more information, see ProfileService.Errors.

Remarks

The Update method commits the object to the data store.

Any changes made using the IADs interface routines are committed to the database.

Use the Fields property to access the ProfileObject object data.

See Also

ProfileObject Object

ProfileObject.Fields


ProfileService Object

Use this object to create, delete, and retrieve ProfileObject objects.

ProgID: | Commerce.ProfileService (Externally creatable)
COM Class Name: | ProfileService
Type Library Name: | Microsoft Commerce 2000 Profile Service Type Library
DLL Name: | mscsups.dll
Threading Model: | Both

The properties of the ProfileService object are shown in the following table.

Property | Type | Description
Errors | Object | Stores the collection of errors encountered in the last Profiles resource operation. This property is read-only.

The methods of the ProfileService object are shown in the following table.

Method | Description
BindAs | Sets the user credentials for accessing the underlying Profiles store.
CreateProfile | Creates the specified ProfileObject object.
DeleteProfile | Deletes a ProfileObject object specified by a primary key value from the Profiling System.
DeleteProfileByKey | Deletes a ProfileObject object specified by a key member/value pair from the Profiling System.
GetProfile | Retrieves a ProfileObject object specified by a primary key value from the Profiling System.
GetProfileByKey | Retrieves a ProfileObject object specified by a key member/value pair from the Profiling System.
GetProfileDefXML | Retrieves the XML description of the specified profile definition.
Initialize | Establishes connection to the specified Profiles store and populates the schema cache.
UnBind | Clears the user credentials for accessing the underlying Profiles store.

Remarks

The ProfileService object implements read/write run-time access for ProfileObject objects and read-only access for profile definitions.

The ProfileService object provides run-time access to a profile object, which is a specific instantiation of a profile schema. The Profile Designer module in Commerce Server Business Desk and the Profiles resource in Commerce Server Manager provide design-time access for modifying the profile schema.

In a Web-based application context, the ProfileService object is intended to be created and initialized in the Global.asa file for the application. The ProfileObject objects are intended to be created within page scope.

Call the Initialize method before you use any other ProfileService method or property.

See Also

Profile Objects

Profile Schema

Profile XML Structures

ProfileObject Object


ProfileService.BindAs

Use this method to set the credentials used to access ProfileObject objects in the underlying Profiles store.

Definition

Sub BindAs (
sUserName As String,
sPassword As String
)

Parameters

sUserName

[in] A String that contains the user name for accessing ProfileObject objects.

sPassword

[in] A String that contains the password for accessing ProfileObject objects.

Return Values

None.

Error Values

The Errors property stores the collection of errors encountered in the last Profiles resource operation. For more information, see ProfileService.Errors.

Remarks

This method sets the credentials used to access and modify ProfileObject objects in the underlying directory store. Any new ProfileObject objects or modifications will be bound to these credentials. The specified credentials define the security context under which all subsequent ProfileObject object operations will be performed, until the UnBind method is invoked. The credentials specified here will be used as is to bind to the underlying directory stores. It is the responsibility of the client to pass in these credentials in the appropriate format. For example, to bind to Active Directory one could pass in either the

  • Full User Principal Name (UPN) (for example, joeuser@domain.com), or

  • SAM Account Name (for example, Domain\SAMAccountName), or

  • Fully specified distinguished name of the security principal (for example, CN=joeuser, CN=Users, DC=Domain, DC=com).

For Membership Directory, you must specify the fully specified distinguished name of the security principal.

Use the UnBind method to clear the credentials.

Call the Initialize method before you use this ProfileService method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oProfileService is a Commerce ProfileService object

oProfileService.BindAs "JoeUser@microsoft.com", "MyPassword123"
oProfileService.BindAs "DomainName\JoeUser", "MyPassword123"

See Also

ProfileService Object

ProfileService.UnBind


ProfileService.CreateProfile

Use this method to create a ProfileObject object.

Definition

Function CreateProfile(
sValue As Variant,
bstrType As String
) As Object

Parameters

sValue

[in] A Variant that contains the primary key value for the new ProfileObject object. The variable types permitted for this variant are String or Long.

bstrType

[in] A String that contains the schema type for the new ProfileObject object.

Return Values

If this method completes successfully, it returns the newly created ProfileObject object. The object is set to Nothing if a ProfileObject object of the specified primary key and schema type already exists in the Profiles store.

Error Values

The Errors property stores the collection of errors encountered in the last Profiles resource operation. For more information, see ProfileService.Errors.

Remarks

If the CreateProfile method fails on an aggregated profile (one that has multiple data sources), the DeleteProfile method must be called to clean up any entries in the data stores. In this case, the DeleteProfile method will produce an error that should be ignored.

The CreateProfile method verifies that a ProfileObject object with the specified attributes does not already exist in the database.

The Fields property of the returned ProfileObject object provides access to the profile properties.

Use the GetProfile or GetProfileByKey method to retrieve existing ProfileObject instances from the Profiles store.

Call the Initialize method before you use this ProfileService method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oProfileService is a Commerce ProfileService object
' oProfileObject1 and oProfileObject2 are Commerce ProfileObject objects

oProfileObject1 = oProfileService.CreateProfile _
 ("{73A4C9C1-D68D-11D0-98BF-00A0C90DC8DF}", "Address")

oProfileObject2 = oProfileService.CreateProfile _
 ("Joeuser@microsoft.com", "UserObject")

See Also

ProfileService Object

ProfileService.DeleteProfile

ProfileService.GetProfile

ProfileService.GetProfileByKey

ProfileService.Initialize

ProfileObject Object

ProfileObject.Fields


ProfileService.DeleteProfile

Use this method to delete the ProfileObject object specified by a primary key value and schema type. All properties associated with the profile are purged from the system.

Definition

Sub DeleteProfile(
sValue As Variant,
strType As String
)

Parameters

sValue

[in] A Variant that contains the primary key value.

strType

[in] A String that contains the profile schema type.

Return Values

None.

Error Values

The Errors property stores the collection of errors encountered in the last Profiles resource operation. For more information, see ProfileService.Errors.

Remarks

If the DeleteProfile method is called because of an error in creating a new ProfileObject object, any error message produced should be ignored.

Use the DeleteProfileByKey method to delete a profile specified by a key member/value pair and schema type.

Call the Initialize method before you use this ProfileService method.

Caution

  • Care must be taken when deleting ProfileObject objects due to possible expression dependencies. See the ExpressionStore and ExpressionEval objects for details on expressions.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oProfileService is a Commerce ProfileService object

oProfileService.DeleteProfile("Joeuser@microsoft.com", "UserObject")

See Also

ProfileService Object

ProfileService.CreateProfile

ProfileService.DeleteProfileByKey

ExpressionEval Object

ExpressionStore Object


ProfileService.DeleteProfileByKey

Use this method to delete the ProfileObject object specified by a key member name/value pair and schema type. All properties associated with the profile are purged from the system.

Definition

Sub DeleteProfileByKey(
strKeyMemberName As String,
sValue As Variant,
strType As String
)

Parameters

strKeyMemberName

[in] A String that contains the key member name.

sValue

[in] A Variant that contains the key value.

strType

[in] A String that contains the profile schema type.

Return Values

None.

Error Values

The Errors property stores the collection of errors encountered in the last Profiles resource operation. For more information, see ProfileService.Errors.

Remarks

Use the DeleteProfile method to delete a profile by specifying a primary key value and schema type.

Call the Initialize method before you use this ProfileService method.

Caution

  • Care must be taken when deleting ProfileObject objects due to possible expression dependencies. See the ExpressionStore and ExpressionEval objects for details on expressions.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oProfileService is a Commerce ProfileService object

oProfileService.DeleteProfileByKey("user_id",_
 "{74A38551-D6D8-FFD0-12BF-0A20C90DC8D1}" "UserObject")

See Also

ProfileService Object

ProfileService.CreateProfile

ProfileService.DeleteProfile

ExpressionEval Object

ExpressionStore Object


ProfileService.Errors

The Errors property is a read-only ADO Errors object that stores the collection of errors encountered in the last Profiles resource operation.

Definition

Property Errors As Object

Parameters

None.

Remarks

The Errors property collects all errors generated by a ProfileService object operation, including those that emerge from the underlying technology.

If the error is coming from the underlying data store providers (such as OLE DB Provider for SQL Server and OLE DB Provider for Microsoft Directory Services) it is passed, for example, in some cases only the Number and Source properties of the Error object are set.

For information about standard COM errors, see Standard COM Errors.

The following ADO Errors methods and properties are supported:

  • Clear

  • Count

  • Item

  • _NewEnum

The following ADO Error methods and properties are supported:

  • Description

  • HelpFile

  • Number

  • Source

Call the Initialize method before you access the Errors property.

See Also

ProfileObject Object

ProfileService Object


ProfileService.GetProfile

Use this method to retrieve the ProfileObject object corresponding to the specified primary key value and schema type.

Definition

Function GetProfile(
sValue as Variant,
bstrType As String
Optional bReturnError As Boolean
) As Object

Parameters

sValue

[in] A Variant that contains the primary key value.

bstrType

[in] A String that contains the profile schema type.

bReturnError

[in] An optional Boolean. The default value is True (-1).

Return Values

If this method completes successfully, it returns a ProfileObject object corresponding to the specified primary key value and schema name.

Error Values

The Errors property stores the collection of errors encountered in the last Profiles resource operation. For more information, see ProfileService.Errors.

Remarks

If the optional bReturnError parameter is set to True (-1) and the specified ProfileObject object is not found, an error message, E_PS_PROFILE_NOTEXISTS, is returned instead of a ProfileObject object.

If the bReturnError parameter is set to False (0) and the specified ProfileObject object is not found, an empty ProfileObject object is returned without an error message.

Properties with the IsCached attribute set to False are not loaded by this method.

The Fields property of the returned ProfileObject object provides access to the profile properties.

Use the GetProfileByKey method to retrieve a profile by specifying a key member name/value pair and schema type.

Call the Initialize method before you use this ProfileService method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oProfileService is a Commerce ProfileService object
' oProfileObject is a Commerce ProfileObject object

oProfileObject = oProfileService.GetProfile("Joeuser@microsoft.com", _
 "UserObject")

See Also

ProfileService Object

ProfileService.GetProfileByKey

ProfileService.Initialize

ProfileObject Object

ProfileObject.Fields


ProfileService.GetProfileByKey

Use this method to retrieve a ProfileObject object that corresponds to a specified key member name/value pair and schema type.

Definition

Function GetProfileByKey(
bstrKeyMemberName As String,
sValue As Variant,
bstrType As String
Optional bReturnError As Boolean
) As Object

Parameters

bstrKeyMemberName

[in] A String that contains the key member name.

sValue

[in] A Variant that contains the key value.

bstrType

[in] A String that contains the schema type.

bReturnError

[in] An optional Boolean. The default value is True (-1).

Return Values

If this method completes successfully, it returns a ProfileObject object corresponding to the specified key member/value pair and schema name.

Error Values

The Errors property stores the collection of errors encountered in the last Profiles resource operation. For more information, see ProfileService.Errors.

Remarks

If the optional bReturnError parameter is set to True (-1) and the specified ProfileObject object is not found, an error message, E_PS_PROFILE_NOTEXISTS, is returned instead of a ProfileObject object.

If the bReturnError parameter is set to False (0) and the specified ProfileObject object is not found, an empty ProfileObject object is returned without an error message.

Properties with the IsCached attribute set to False are not loaded by this method.

The Fields property of the returned ProfileObject object provides access to the profile properties.

Use the GetProfile method to retrieve a profile by specifying a primary key value and schema type.

Call the Initialize method before you use this ProfileService method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oProfileService is a Commerce ProfileService object
' oProfileObject is a Commerce ProfileObject object

oProfileObject = oProfileService.GetProfileByKey("user_id", _
 "{74A38551-D6D8-FFD0-12BF-0A20C90DC8D1}", "UserObject")

See Also

ProfileService Object

ProfileService.GetProfile

ProfileService.Initialize

ProfileObject Object

ProfileObject.Fields


ProfileService.GetProfileDefXML

Use this method to retrieve the XML definition of the named profile schema type.

Definition

Function GetProfileDefXML(
bstrProfileName As String
bNamesOnly As Boolean,
) As String

Parameters

bstrProfileName

[in] A String that contains the name of the profile schema type.

bNamesOnly

[in] A Boolean that determines whether the method returns the profile schema name or the profile schema definition. A value of FALSE indicates to return the profile definition. A value of TRUE indicates to return only the name of the profile schema.

Return Values

If this method completes successfully, it returns a String that contains the XML description.

Error Values

The Errors property stores the collection of errors encountered in the last Profiles resource operation. For more information, see ProfileService.Errors.

Remarks

If the bstrProfileName parameter is empty and the bNamesOnly parameter is False (0), the XML descriptions of all the schema types in the catalog are returned.

If the bstrProfileName parameter is empty and the bNamesOnly parameter is True (-1), the names of all the schema types in the catalog are returned.

For information about the XML definitions, see the Profile XML Structures topic.

Call the Initialize method before you use this ProfileService method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' sXML is a String
' oProfileService is a Commerce ProfileService object

sXML = oProfileService.GetProfileDefXML("UserObject", False)

See Also

ProfileService Object

Profile XML Structures


ProfileService.Initialize

Use this method to establish a connection to the Commerce Server Profiles store and populate the schema cache with all the schemas from the specified catalog.

Definition

Sub Initialize(
sConfigStore As String,
Optional sCatalog As String
)

Parameters

sConfigStore

[in] A String that contains the connection string to the Profiles store.

sCatalog

[in, optional] A String that identifies the catalog. If this is specified it must be "Profile Definitions".

Return Values

None.

Error Values

The Errors property stores the collection of errors encountered in the last Profiles resource operation. For more information, see ProfileService.Errors.

Remarks

The Initialize method creates the necessary internal parameters and schema cache for profile management. A ProfileService object must connect to only one Profiles store. Multiple instances of the ProfileService object must be created to access multiple stores.

The connection string for the Profiles store may be obtained through the SiteConfigReadOnly object, or through the Commerce Server Manager console from the s_ProfileServiceConnectionString property under the key "Commerce Server Manager\Global Resources\Profiles(ComputerName SiteName)".

The connection string is comprised of the following mandatory tokens:

  • Data Source and/or Database [mandatory]. This attribute allows applications to specify the name of the underlying SQL Server containing the Profiles database. At least one of these attributes must be specified. If both of these attributes are specified, the value of the Data Source attribute takes precedence.

  • Initial Catalog and/or Server [mandatory]. This attribute allows applications to specify the name of the Profiles database containing profile definitions. At least one of these attributes must be specified. If both of these attributes are specified, the value of the Initial Catalog attribute takes precedence.

  • User ID and/or UID [mandatory]. This attribute allows applications to specify the login name to connect to the Profiles database. At least one of these attributes must be specified. If both of these attributes are specified, the value of the User ID attribute takes precedence.

The following is a sample connection string containing these attributes:

   Data Source=servername;Initial Catalog=dbname;User ID=user

Spaces are not allowed around the delimiting semi-colon, and a semi-colon is not allowed in the names of any of the tokens.

Additionally, the following optional tokens are also supported by the Profiles resource:

  • Provider [optional]. Allows applications to specify the OLE DB provider to which the Profiles resource connects. This parameter exists for consistency with standard ADO connection strings. The default value and only acceptable value for this attribute is CSOLEDB.

  • Password [optional]. Allows applications to specify the password for the user specified by the User ID or UID attribute. The default value for this attribute is NULL.

  • PsObjectCacheSize [optional]. Allows applications to specify the size of the Profiles resource object cache. This cache stores ProfileObject objects instantiated by the CreateProfile and GetProfile methods. The default value for this attribute is 32768.

  • PsSchemaCacheSize [optional]. Allows applications to specify the size of the Profiles resource definition (schema) cache. Once loaded, entries cannot be purged from the cache. The default value for this attribute is 64.

  • PsBackgroundThread [optional]. Allows applications to control the creation of a background thread to periodically clean up entries from the Profiles resource object cache. The acceptable values for this parameter are zero (0) or one (1). Zero turns off the background thread, one turns it on. By default, the background thread is on.

  • PsObjectAgeoutPeriod [optional]. Allows applications to specify the age-out period for the Profiles resource cache entries. The age-out period is the amount of time an unreferenced object can remain in the cache without being discarded. The default value for this attribute is five minutes.

Notes

  • The Initial Catalog in the connection string is the database containing the Profiles store.

  • The sCatalog parameter in the Initialize method is the catalog containing the profile schema definitions, which is "Profile Definitions".

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' Connect using an explicit connection string.
' oProfileService is a Commerce ProfileService object

oProfileService.Initialize "Provider=CSOLEDB;Data Source=MyServer;" _
 & "Initial Catalog=Retail_commerce;User ID=user;Password=*****;" _
 & "PsSchemaCacheSize=128;PsObjectAgeoutPeriod=8", "Profile Definitions"

' Connect through the SiteConfigReadOnly object.
' sConn is a String
' oSCRO is an initialized SiteConfigReadOnly object

sConn = oSCRO.Fields("Profiles(ComputerName SiteName").Value _
 .Fields("s_ProfileServiceConnectionString").Value & "SCHCACHE=128"
oProfileService.Initialize sConn, "Profile Definitions"

See Also

ProfileService Object


ProfileService.Unbind

Use this method to clear the credentials that are used to access ProfileObject objects in the underlying Profiles store.

Definition

Sub Unbind (
)

Parameters

None.

Return Values

None.

Error Values

The Errors property stores the collection of errors encountered in the last Profiles resource operation. For more information, see ProfileService.Errors.

Remarks

This method clears the credentials used to access ProfileObject objects in the underlying store. Any new profiles or modifications will not be bound to a specific user. Use this method to gain access to existing ProfileObject objects that are not bound to a specific user.

Use the Bind method to set the credentials to access ProfileObject objects that are bound to a specific user.

Call the Initialize method before you use this ProfileService method.

See Also

ProfileService Object

ProfileService.BindAs


ReportRenderer Object

Use this object to render (display) or export a static report synchronously.

ProgID: | Commerce.ReportRenderer (Externally creatable)
COM Class Name: | ReportRenderer
Type Library Name: | Microsoft Commerce 2000 Report Renderer Type Library
DLL Name: | ReportRenderer.dll
Threading Model: | Both

The methods of the ReportRenderer object are shown in the following table.

Method | Description
Init | Initializes the object.

Remarks

The ReportRender object must be passed the ReportStatusID parameter of the report to be rendered in its initialization string. This parameter is set when the report is run or exported from the Reports module.

Exporting a static report writes a result table to a target database. The ListManager object imports from this table using the CreateFromDWCalc method of the ListManager object.

The ReportRender object runs synchronously. Use the AsyncRpt object to run static reports asynchronously.

See Also

Analysis/Reporting Schema

Analysis/Reporting XML Structures

Creating Custom Reports

AsyncRpt Object

ListManager Object

Running Reports


ReportRenderer.Init

Use this method to initialize the ReportRenderer object and to render or export a static report synchronously.

Definition

Function Init(
sParamString As String
) As Boolean

Parameters

sParamString

A String used to supply parameters to the ReportRenderer object.

Return Values

If this method completes successfully, it returns a Boolean that indicates whether the initialization was successful. True (1) indicates success.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The sParamString parameter consists of a string containing six parameters delineated by the '|' symbol. The string is of the form:

   "ReportStatusID|Data warehouse connection string|
    OLAP connection string|Destination connection string|
    Destination table name|Report execution time"

The possible parameters consist of the following:

  • ReportStatusID - used to identify the report to be displayed or exported. This parameter is stored in the ReportStatus table which is created when a report is run or exported.

  • Data warehouse connection string - where the underlying data is stored. A valid connection string is of the type "DRIVER={SQL Server};SERVER=Server Name;DATABASE=Database Name;UID=username;PWD=password;".

  • OLAP connection string - where the underlying OLAP data is stored. A valid connection string is of the type "DATA SOURCE=Server Name;INITIAL CATALOG=Database Name;".

  • Destination connection string - where the table that will contain the exported report data is located. A valid connection string is of the type "SERVER=Server Name;DATABASE=Database Name;UID=username;PWD=password;".

  • Destination table name - the table that will contain the exported report data.

  • Report execution time - the time when the report was executed. If not supplied, this defaults to the current time in the format of the client computer.

The actual parameters used depend on the type of report (SQL or MDX) and whether the report is being displayed or exported. The ReportStatusID and the Data warehouse connection string parameters are required in all cases. The remaining parameters are required, as shown in the following table. Parameters not used are left blank.

Action- Report Type | Report StatusID | Data Warehouse connection string | OLAP connection string | Destination connection string | Destination table name | Report execution time
Display-SQL | X | X |  |  |  | X
Display-MDX | X | X | X |  |  | X
Export-SQL | X | X |  | X | X |
Export-MDX | X | X | X | X | X |

The ReportRenderer object constrains displayed reports with the following limitations:

  • Maximum of 1000 rows.

  • Maximum of 50 columns.

  • Maximum of 5 dimension levels for each row or column dimension.

The number of rows and columns is determined by the report query, report parameters, and report definitions. The number of dimensions is set in the ReportDimension table (for SQL queries) when the report is created. Trying to display a report outside these limitations results in the report being truncated at the above limits. There are no limits when exporting a report. For information on the report tables, see Analysis/Reporting Schema.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oReportRenderer is a Commerce ReportRenderer object

' Display a static SQL report

   oReportRenderer.Init("7|DRIVER={SQL Server};" _
    & "SERVER=MyServer;DATABASE=Retail_dw;UID=admin;" _
    & "PWD=*****;||||10/01/2000 3:45:56 pm" )

' Export a static SQL report

   oReportRenderer.Init("7|DRIVER={SQL Server};SERVER=MyServer;" _
    & "DATABASE=Retail_dw;UID=sysadmin;PWD=123;||Provider=SQLOLEDB;" _
    & "Persist Security Info=False;User ID=sa;Password=*****;" _
    & "Initial Catalog=Retail_commerce;Data Source=MyServer;|" _
    & "OutPutTableName|10/01/2000 3:45:56 pm")

' Display a static MDX report

   oReportRenderer.Init("19|DRIVER={SQL Server};SERVER=MyServer;" _
    & "DATABASE=Retail_dw;UID=admin;PWD=*****;|data source=MyServer;" _
    & "Initial Catalog=Retail_dw;|||10/01/2000 3:45:56 pm")

' Export a static MDX report

   oReportRenderer.Init("19|DRIVER={SQL Server};SERVER=MyServer;" _
    & "DATABASE=Retail_dw;UID=sysadmin;PWD=123;|data source=MyServer;" _
    & Initial Catalog=Retail_dw;|Provider=SQLOLEDB;" _
    & "Persist Security Info=False;User ID=sa;Password=*****;" _
    & "Initial Catalog=Retail_commerce;Data Source=MyServer;|" _
    & "OutPutTableName|10/01/2000 3:45:56 pm")

See Also

ReportRenderer Object

Analysis/Reporting Schema

Creating Custom Reports


RowCollection Object

Use this object to access data contained in a ContentList object and its corresponding ContentListFactory object. Some RowCollection objects allow access to all of the rows in these objects. Other RowCollection objects allow access to a calculated subset of the rows in these objects.

ProgID: | Dependent (See the Remarks section for more information)
COM Class Name: | RowCollection
Type Library Name: | Microsoft Commerce 2000 Cache Manager Type Library
DLL Name: | mscscache.dll
Threading Model: | Both

The properties of the RowCollection object are shown in the following table.

Property | Type | Description
_NewEnum | IUnknown | Allows iteration through the rows in the RowCollection object using the Microsoft Visual Basic "for each Row in Collection" syntax. This property is read-only.
Count | long | Stores the number of rows in the RowCollection object. This property is read-only.
EOF | VARIANT_BOOL | Tracks whether the current row is beyond the actual number of rows in the RowCollection object. This property is read-only.
Fields | Fields | Contains the Fields collection object for the current row. This property is read-only.
RowNum | long | Stores the position of the current row, starting from zero (0). This property is read-only.

The methods of the RowCollection object are shown in the following table.

Method | Description
MoveFirst | Sets the first row in the RowCollection object to be the current row.
MoveNext | Sets the row after the current row in the RowCollection object to be the new current row.

Remarks

The RowCollection object is a dependent object. Obtain a reference to it using the following properties and methods:

  • ContentList.ActiveRows

  • ContentList.AllRows

  • ContentList.Search

  • ContentListFactory.AllRows

  • ContentListFactory.Search


RowCollection._NewEnum

The read-only _NewEnum property provides a mechanism for enumerating through the rows in a RowCollection object using the Microsoft Visual Basic "for each Row in Collection" syntax. Each row in the collection is a Fields collection object that can be used to access the individual fields in the row.

Definition

Property _NewEnum() As IUnknown

Parameters

None.

Error Values

This property sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

This property exists so that the "for each Row in Collection" syntax in Microsoft Visual Basic can be used to iterate through the rows in a RowCollection object. This property is not accessed directly.

See Also

RowCollection Object


RowCollection.Count

The Count property is a read-only Long that contains the number of rows in the collection.

Definition

Property Count As Long

Parameters

None.

Error Values

This property sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

See Also

RowCollection Object


RowCollection.EOF

The EOF property is a read-only Boolean that returns True when the end of the collection has been reached.

Definition

Property EOF() As Boolean

Parameters

None.

Error Values

This property sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

See Also

RowCollection Object


RowCollection.Fields

The Fields property is a read-only Fields collection object that contains the Field objects for the current row.

Definition

Property Fields() As Fields

Parameters

None.

Error Values

This property sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The Fields object associated with this property corresponds to the current row in the RowCollection object. When the EOF property is True, indicating that the current row is set beyond the actual rows in the collection, accessing this property will result in an error.

See Also

RowCollection Object


RowCollection.MoveFirst

Use this method to set the current row to be the first row in a RowCollection object.

Definition

Sub MoveFirst()

Parameters

None.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Example

'myRowCollection is a RowCollection object.
myRowCollection.MoveFirst

See Also

RowCollection Object


RowCollection.MoveNext

Use this method to set the current row to be the row that is one row beyond the current row. In other words, the next row in the collection.

Definition

Sub MoveNext()

Parameters

None.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Example

'myRowCollection is a RowCollection object.
myRowCollection.MoveNext

See Also

RowCollection Object


RowCollection.RowNum

The RowNum property is a read-only number that contains the position of the current row within the RowCollection object. Row positions begin at zero (0), not one (1).

Definition

Property RowNum() As Long

Parameters

None.

Error Values

This property sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The value of this property corresponds to the current row in the RowCollection object. When the EOF property is True, indicating that the current row is set beyond the actual rows in the collection, accessing this property will result in an error.

See Also

RowCollection Object


Shipping Object

Use this object to create shipping cost preview information.

ProgID: | Commerce.Shipping (Externally creatable)
COM Class Name: | Shipping
Type Library Name: | Microsoft Commerce 2000 Shipping Components Type Library
DLL Name: | shipmgr.dll
Threading Model: | Apartment

The single method of the Shipping object is shown in the following table.

Method | Description
PreviewShipments | Divides an order into shipments and produces shipping cost previews for each shipment using each method.


Shipping.PreviewShipments

Use this method to create shipment preview information.

Definition

Function PreviewShipments(
orderform As Variant,
context As Variant,
ShipmentDistinguishers As Variant
) As Variant

Parameters

orderform

The OrderForm object for which to calculate shipping cost previews.

context

The Context dictionary to use to run the shipping components.

ShipmentDistinguishers

An array of strings containing the line item attributes (keys) to use to split the order into shipments.

Return Values

If this method completes successfully, it returns a Simplelist of dictionaries, one for each shipment, which in turn contains a Simplelist of dictionaries containing the shipping cost previews, one for each shipping method.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The PreviewShipments method creates the shipping cost previews by splitting the order into individual shipments. The mechanism used is the same as the Splitter pipeline component. For more information about how shipment distinguishers are used to split shipments, see Splitter.

The PreviewShipments method returns a SimpleList of dictionaries, one for each shipment. Each shipment dictionary in turn contains a SimpleList of dictionaries each of which contains the shipping cost for using a particular shipping method.

For example code showing how to loop through the preview shipments, see Previewing Shipping Costs.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oShip is a Commerce.Shipping object
' dOrder and dContext are Commerce.Dictionary objects
' ADistinguishers is an Array of strings naming line items
' slShipments is a SimpleList of dictionary or orderform objects

slShipments = oShip.PreviewShipments(dOrder, dContext, _
Distinguishers)

See Also

Previewing Shipping Costs

Shipping Object

ShippingDiscountAdjust

ShippingManagerCache

ShippingMethodManager Object

ShippingMethodRouter

StepwiseShipping


ShippingMethodManager Object

Use this object to manage shipping methods that will be available on the site. The ShippingMethodManager object lets you add and remove methods, and set their description, availability, and configuration.

ProgID: | Commerce.ShippingMethodManager (Externally creatable)
COM Class Name: | ShippingMethodManager
Type Library Name: | Microsoft Commerce 2000 Shipping Components Type Library
DLL Name: | shipmgr.dll
Threading Model: | Apartment

The methods of the ShippingMethodManager object are shown in the following table.

Method | Description
CreateMethodInstance | Creates an empty instance of a shipping method.
DeleteMethodInstance | Deletes the current shipping method instance.
GetComponentConfig | Retrieves the Configuration dictionary for the shipping component, which implements the current shipping method.
GetInstalledMethodList | Returns a recordset containing the current shipping methods.
GetMethodInfo | Returns a recordset containing information about the loaded shipping method.
Initialize | Initializes the ShippingMethodManager object and connects it to a database.
LoadMethodInstance | Loads a given shipping method to be manipulated by other methods.
SaveMethodConfig | Saves information about the current method.
SetCachableComponentConfig | Saves configuration and other component information for a component.
SetMethodConfig | Sets pairs of names and values for the current method.

Remarks

The shipping architecture in Commerce Server 2000 is designed so that shipping methods can be changed through the Shipping Methods module in Commerce Server Business Desk without programming or editing pipelines. To do this, Commerce Server maintains a database table, ShippingConfig, of shipping methods and the information required to configure shipping components to implement those methods.

The ShippingMethodManager object is used by Business Desk to manage the ShippingConfig database table.

For more information about shipping objects, see the Multiple Shipment Architecture Overview.


ShippingMethodManager.CreateMethodInstance

Use this method to create a new shipping method.

Definition

Function CreateMethodInstance(
bOnDisk As Variant
) As Variant

Parameters

bOnDisk

A Variant containing a Boolean indicating whether or not to create the shipping method on disk. This parameter is usually set to True.

Return Values

If this method completes successfully, it returns a Variant containing a string that is the method ID of the new shipping method. The method returns an empty string when the bOnDisk parameter is False.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

If the shipping method is created to be saved on disk (the bOnSaved parameter is True), the function adds a new record to the current recordset with the enabled column value set to zero (0) and the shipping_method_id column set to the new shipping method ID.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' Initialize the ShippingMethodManager object
' oSMM is a Commerce.ShippingMethodManager object
' MSCSTransactionConfigConnStr is sConnectionString, a string containing
' the connection string

Call oSMM.Initialize(MSCSTransactionConfigConnStr)

' Create a new shipping method
' bOnDisk is set to True
' sShippingMethodID is sMethodID
sShippingMethodID = oSMM.CreateMethodInstance(True)

' Set the configuration data for the pipeline component
' sProgID, sAction, and sActionFrientlyName are strings
' dConfigDict is a Commerce.Dictionary object

Call oSMM.SetCachableComponentConfig(sProgID, dConfigDict, _
                 sAction, sActionFriendlyName)

' Set properties for the shipping method

Call oSMM.SetMethodConfig(Array("shipping_method_name", "My Shipping Method", "description", "Cheapest but slowest shipping method", "enabled", 1))

' Save the configured shipping method
oSMM.SaveMethodConfig

See Also

Splitter

Shipping Object

ShippingDiscountAdjust

ShippingManagerCache

ShippingMethodManager Object

ShippingMethodRouter

StepwiseShipping


ShippingMethodManager.DeleteMethodInstance

Use this method to delete the current shipping method instance.

Definition

Sub DeleteMethodInstance()

Parameters

None.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

This method acts on the loaded shipping method. You must call LoadMethodInstance or CreateMethodInstance to load a shipping method into the ShippingMethodManager object before calling this method.

Example

' oSMM is an initialized Commerce.ShippingMethodManager object
' sMethodId is set to sShippingMethodId,
' the method ID of the new method

Call oSMM.LoadMethodInstance(sShippingMethodId)
oSMM.DeleteMethodInstance

See Also

Splitter

Shipping Object

ShippingDiscountAdjust

ShippingManagerCache

ShippingMethodManager Object

ShippingMethodRouter

StepwiseShipping


ShippingMethodManager.GetComponentConfig

Use this method to retrieve the Configuration dictionary for the shipping component to implement the current shipping method. The shipping method must be loaded using LoadMethodInstance before calling GetComponentConfig.

Definition

Function GetComponentConfig() As Variant

Parameters

None.

Return Values

If this method completes successfully, it returns a Variant that contains the Configuration dictionary for the current shipping method.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

This method acts on the loaded shipping method. You must call LoadMethodInstance or CreateMethodInstance to load a shipping method into the ShippingMethodManager object before calling this method.

Example

' oSMM is an initialized, loaded Commerce.ShippingMethodManager object

Set dConfig = oSMM.GetComponentConfig

See Also

Splitter

Shipping Object

ShippingDiscountAdjust

ShippingManagerCache

ShippingMethodManager Object

ShippingMethodRouter

StepwiseShipping


ShippingMethodManager.GetInstalledMethodList

Use this method to get a list of the current shipping methods. The GetInstalledMethodList method allows you to filter the list, select the columns to return, and to sort the list into a particular order.

Definition

Function GetInstalledMethodList(
Filter As Variant,
OrderBy As Variant,
columns As Variant
) As Variant

Parameters

Filter

A String that becomes the WHERE clause of the query. Pass Null if no filtering is wanted. An example filter is "enabled = 1", this will cause GetInstalledMethodList to only return enabled shipping methods.

OrderBy

A String that becomes the ORDER BY clause of the query. Pass a Null if no ordering is wanted. An example OrderBy arguement is "shipping_method_name", which will cause the results to be sorted by shipping method name.

columns

An Array of column names of the values to retrieve. If an empty array is passed, all columns from the ShippingConfig table are returned.

Return Values

If this method completes successfully, it returns an ADO Recordset object that contains the results of the query.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The GetInstalledMethodList method constructs a SQL query from its three parameters, runs it against the current ShippingConfig table, and returns the result in an ADO Recordset object.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oSMM is an initialized Commerce.ShippingMethodManager object
' sFilter is set to filter
' sOrderBy is set to null, so there will be no ordering
' AColumns is an array of column names of the values to retrieve
' rsMethodList is a recordset

"'""'"Set rsMethodList = oSMM.GetInstalledMethodList( _
                             "enabled = 1", _
                             Null, _
                             Array("shipping_method_name") _
                             )

See Also

Splitter

Shipping Object

ShippingDiscountAdjust

ShippingManagerCache

ShippingMethodManager Object

ShippingMethodRouter

StepwiseShipping


ShippingMethodManager.GetMethodInfo

Use this method to retrieve information about the database attributes of one or more columns in the ShippingConfig table.

Definition

Function GetMethodInfo(
columns As Variant
) As Variant

Parameters

columns

An Array of strings containing names of the columns. Specify an empty array to return all columns.

Return Values

If this method completes successfully, it returns an ADO Recordset object that contains the information about the wanted columns.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

This method acts on the loaded shipping method. You must call LoadMethodInstance or CreateMethodInstance to load a shipping method into the ShippingMethodManager object before calling this method.

This method returns an ADO Recordset object containing the data type, defined size, and attributes of the requested columns in the ShippingConfig table.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oSMM is an initialized, loaded Commerce.ShippingMethodManager object
' rsResult is an ADO recordset

Set rsResult = oSMM.GetMethodInfo(Array("shipping_method_name", "description", "enabled"))

See Also

Splitter

Shipping Object

ShippingDiscountAdjust

ShippingManagerCache

ShippingMethodManager Object

ShippingMethodRouter

StepwiseShipping


ShippingMethodManager.Initialize

Use this method to initialize a ShippingMethodManager object and connect it to a database.

Definition

Sub Initialize(
connection_string As Variant
)

Parameters

connection_string

A String containing the connection string.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oSMM is a Commerce.ShippingMethodManager object
' sConnectionString is a string containing the connection
' string

oSMM.Initialize(sConnectionString)

See Also

Splitter

Shipping Object

ShippingDiscountAdjust

ShippingManagerCache

ShippingMethodManager Object

ShippingMethodRouter

StepwiseShipping


ShippingMethodManager.LoadMethodInstance

Use this method to load an instance of a given shipping method.

Definition

Sub LoadMethodInstance(
methodid As Variant
)

Parameters

methodid

A String containing the method ID of the shipping method.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

This method loads an instance of the requested shipping method as a single record in the current recordset.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oSMM is an initialized Commerce.ShippingMethodManager object
' sMethodId is a string containing the method id

oSMM.LoadMethodInstance(sMethodId)

See Also

Splitter

Shipping Object

ShippingDiscountAdjust

ShippingManagerCache

ShippingMethodManager Object

ShippingMethodRouter

StepwiseShipping


ShippingMethodManager.SaveMethodConfig

Use this method to save the current shipping method information set with the SetMethodConfig method.

Definition

Sub SaveMethodConfig()

Parameters

None.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The SaveMethodConfig method saves the current shipping method configuration data.

This method acts on the loaded shipping method. You must call LoadMethodInstance or CreateMethodInstance to load a shipping method into the ShippingMethodManager object before calling this method.

Example

' oSMM is a Commerce.ShippingMethodManager object

oSMM.SaveMethodConfig

See Also

Splitter

Shipping Object

ShippingDiscountAdjust

ShippingManagerCache

ShippingMethodManager Object

ShippingMethodRouter

StepwiseShipping


ShippingMethodManager.SetCachableComponentConfig

Use this method to set the configuration data for the pipeline component, and other component information.

Definition

Sub SetCachableComponentConfig(
progid As Variant,
configdict As Variant,
action As Variant,
actionfriendlyname As Variant
)

Parameters

progid

A String containing the ProgID of the pipeline component.

configdict

A Dictionary object holding the configuration information for the component.

action

A String containing the name of the ASP edit page for the shipping component.

actionfriendlyname

A String containing a friendly name for the ASP edit page for the shipping component.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

This method acts on the loaded shipping method. You must call LoadMethodInstance or CreateMethodInstance to load a shipping method into the ShippingMethodManager object before calling this method.

This method takes the Configuration dictionary for the component and prepares it to be saved along with the current configuration. In addition, the method stores the ProgID, the edit page, and the page friendly names. The settings are not saved until the SaveMethodConfig method is called.

The configdict parameter is typically obtained using IPipelineComponentAdmin::GetConfigDictionary.

This method utilizes the IPipelineComponentAdmin interface; therefore all shipping components configurable by the ShippingMethodManager object must support the IPipelineComponentAdmin interface.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oSMM is a Commerce.ShippingMethodManager object
' sProgID, sAction, and sActionFrientlyName are strings
' dConfigDict is a Commerce.Dictionary object

Call oSMM.SetCachableComponentConfig(sProgID, dConfigDict, _
                 sAction, sActionFriendlyName)

See Also

Splitter

Shipping Object

ShippingDiscountAdjust

ShippingManagerCache

ShippingMethodManager Object

ShippingMethodRouter

StepwiseShipping


ShippingMethodManager.SetMethodConfig

Use this method to set properties such as name or description, on the current shipping method.

Definition

Sub SetMethodConfig(
ParametersAndValues As Variant
)

Parameters

ParametersAndValues

An Array containing name and value pairs in successive elements.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

This method acts on the loaded shipping method. You must call LoadMethodInstance or CreateMethodInstance to load a shipping method into the ShippingMethodManager object before calling this method.

The array parameter contains names and values in alternating elements. Odd subscripts contain the names of items, even subscripts contain the values.

Use the SaveMethodConfig method to save the configuration information entered with this method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oSMM is a Commerce.ShippingMethodManager object

Call oSMM.SetMethodConfig(Array("shipping_method_name", "My Shipping Method", "description", "Cheapest but slowest shipping method", "enabled", 1))

See Also

Splitter

Shipping Object

ShippingDiscountAdjust

ShippingManagerCache

ShippingMethodManager Object

ShippingMethodRouter

StepwiseShipping


SimpleFindResultInfo Object

Use this object to specify search criteria when using the SimpleFind and SimpleDelete methods of the OrderGroupManager object.

ProgID: | Commerce.SimpleFindResultInfo (Externally creatable)
COM Class Name: | SimpleFindResultInfo
Type Library Name: | Microsoft Commerce 2000 OrderGroup Type Library
DLL Name: | requisition.dll
Threading Model: | Apartment

The properties of the SimpleFindResultInfo object are shown in the following table.

Property | Type | Description
Columns | Variant | Specifies a custom set of columns to be returned by the OrderGroupManager SimpleFind method.
JoinLineItemInfo | Boolean | Specifies whether to join the OrderFormLineItems table with the results.
JoinOrderFormInfo | Boolean | Specifies whether the OrderFormHeader table is joined in the results.
OrderGroupSortColumn | Variant | Specifies the column name to sort on.
PageNumber | Long | Specifies the page number of the resultset to show if the resultset exceeds the PageSize.
PageSize | Long | Specifies the page size.
SortDirection | Variant | Specifies the sort direction.

Remarks

The following table shows the data returned by the OrderGroupManager SimpleFind method when it has been passed to the SimpleFindResultInfo object with the JoinOrderFormInfo and JoinLineItemInfo properties set to the indicated values.

JoinOrderFormInfo | JoinLineItemInfo | SimpleFind Method Data Returned
False | False | One record for each OrderGroup that meets the search criteria. Returns OrderGroup data only. The default setting is False.
True | False | One record for each OrderForm that meets the search criteria. Returns OrderGroup and OrderForm data.
True | True | One record for each line item that meets the search criteria. Returns OrderGroup, OrderForm, and line item data.
False | True | One record for each line item that meets the search criteria. Returns OrderGroup, OrderForm, and line item data.

See Also

Business Process Objects

SimpleFindSearchInfo Object

OrderGroupManager Object

OrderGroup Object

OrderForm Object


SimpleFindResultInfo.Columns

The Columns property is a read/write Variant that specifies a custom set of columns to be returned by the SimpleFind method. The columns property, if specified, should be a string of comma-separated column names. If the property is left Null, SimpleFind will return a standard set of columns.

Definition

Property Columns As Variant

Parameters

None.

Error Values

This property sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Requirements for using this property are listed in SimpleFindResultInfo Object.

See Also

SimpleFindResultInfo Object


SimpleFindResultInfo.JoinLineItemInfo

The JoinLineItemInfo property is a read/write Boolean that indicates whether to join the OrderFormLineItems table with the results.

Definition

Property JoinLineItemInfo As Boolean

Parameters

None.

Error Values

This property sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Requirements for using this property are listed in SimpleFindResultInfo Object.

See Also

SimpleFindResultInfo Object


SimpleFindResultInfo.JoinOrderFormInfo

The JoinOrderFormInfo property is a read/write Boolean that indicates whether the OrderFormHeader table is joined in the results.

Definition

Property JoinOrderFormInfo As Boolean

Parameters

None.

Error Values

This property sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Requirements for using this property are listed in SimpleFindResultInfo Object.

See Also

SimpleFindResultInfo Object


SimpleFindResultInfo.OrderGroupSortColumn

The OrderGroupSortColumn property is a read/write Variant that contains the column name on which to sort.

Definition

Property OrderGroupSortColumn As Variant

Parameters

None.

Error Values

This property sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Requirements for using this property are listed in SimpleFindResultInfo Object.

See Also

SimpleFindResultInfo Object


SimpleFindResultInfo.PageNumber

The PageNumber property is a read/write Long that contains the page number to jump to. This property setting must be coordinated with the PageSize property.

Definition

Property PageNumber As Long

Parameters

None.

Error Values

This property sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Use this property to implement a paging mechanism that allows you to page through your orders. (These orders could be viewed in a List Sheet, for example.)

This property is initialized to 1.

Requirements for using this property are listed in SimpleFindResultInfo Object.

See Also

SimpleFindResultInfo Object


SimpleFindResultInfo.PageSize

The PageSize property is a read/write Long that contains the page size. This property setting must be coordinated with the PageNumber property.

Definition

Property PageSize As Long

Parameters

None.

Error Values

This property sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Use this property to implement a paging mechanism that allows you to page through your orders. (These orders could be viewed in a List Sheet, for example.)

This property defaults to 20.

Requirements for using this property are listed in SimpleFindResultInfo Object.

See Also

SimpleFindResultInfo Object


SimpleFindResultInfo.SortDirection

The SortDirection property is a read/write Variant that contains the sort direction. The value of this field can be "asc" for ascending or "desc" for descending.

Definition

Property SortDirection As Variant

Parameters

None.

Error Values

This property sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

Requirements for using this property are listed in SimpleFindResultInfo Object.

See Also

SimpleFindResultInfo Object


SimpleFindSearchInfo Object

Use this object to specify search criteria when conducting searching and deleting operations using the SimpleFind and SimpleDelete methods of the OrderGroupManager object.

ProgID: | Commerce.SimpleFindSearchInfo (Externally creatable)
COM Class Name: | SimpleFindSearchInfo
Type Library Name: | Microsoft Commerce 2000 OrderGroup Type Library
DLL Name: | requisition.dll
Threading Model: | Apartment

The properties of the SimpleFindSearchInfo object are shown in the following table.

Property | Type | Description
description | Variant | Specifies the product description to search for; if left null, the product description does not become part of the search criteria. This property is read/write.
order_number | Variant | Specifies the order number to search for; if left null, the order number does not become part of the search criteria. This property is read/write.
ordergroup_id | Variant | Specifies the OrderGroup ID to search for; if left null, the OrderGroup ID does not become part of the search criteria. This property is read/write.
po_number | Variant | Specifies the OrderForm ID to search for; if left null, the OrderForm ID does not become part of the search criteria. This property is read/write.
product_id | Variant | Specifies the product ID to search for; if left null, the product ID does not become part of the search criteria. This property is read/write.
SearchDateTimeColumn | Variant | Specifies the DateTime column name to search for; if left null, the DateTime column name does not become part of the search criteria. This property is read/write.
SearchDateTimeEnd | Variant | Specifies the DateTime end value to search for; if left null, the DateTime end value does not become part of the search criteria. This property is read/write.
SearchDateTimeStart | Variant | Specifies the DateTime start value to search for; if left null, the DateTime start value does not become part of the search criteria. This property is read/write.
StatusFilter | Long | Specifies the OrderGroup status. This property allows the user to filter the status (ie basket, template or new order). This property is read/write.
user_firstname | Variant | Specifies the first name of the user to search for; if left null, the first name of the user does not become part of the search criteria. This property is read/write.
user_id | Variant | Specifies the user ID to search for; if left null, the user ID does not become part of the search criteria. This property is read/write.
user_lastname | Variant | Specifies the last name of the user to search for; if left null, the last name of the user does not become part of the search criteria. This property is read/write.
user_org_id | Variant | Specifies the user organization ID to search for; if left null, the user organization ID does not become part of the search criteria. This property is read/write.
user_org_name | Variant | Specifies the user organization to search for; if left null, the user organization does not become part of the search criteria. This property is read/write.

See Also

Business Process Objects

SimpleFindResultInfo Object

OrderGroupManager Object

OrderGroup Object

OrderForm Object


SimpleFindSearchInfo.description

The description property is a read/write Variant that specifies the product description to search for; if left null, the product description does not become part of the search criteria.

Definition

Property description As Variant

Parameters

None.

Error Values

This property sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

See Also

SimpleFindSearchInfo Object

OrderGroupManager.SimpleDelete

OrderGroupManager.SimpleFind


SimpleFindSearchInfo.order_number

The order_number property is a read/write Variant that specifies the order number to search for; if left null, the order number does not become part of the search criteria.

Definition

Property order_number As Variant

Parameters

None.

Error Values

This property sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

See Also

SimpleFindSearchInfo Object

OrderGroupManager.SimpleDelete

OrderGroupManager.SimpleFind


SimpleFindSearchInfo.ordergroup_id

The ordergroup_id property is a read/write Variant that contains the OrderGroup ID to search for; if left null, the OrderGroup ID does not become part of the search criteria.

Definition

Property ordergroup_id As Variant

Parameters

None.

Error Values

This property sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

See Also

SimpleFindSearchInfo Object

OrderGroupManager.SimpleDelete

OrderGroupManager.SimpleFind


SimpleFindSearchInfo.po_number

The po_number property is a read/write Variant that contains the OrderForm ID to search for; if left null, the OrderForm ID does not become part of the search criteria.

Definition

Property po_number As Variant

Parameters

None.

Error Values

This property sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

See Also

SimpleFindSearchInfo Object

OrderGroupManager.SimpleDelete

OrderGroupManager.SimpleFind


SimpleFindSearchInfo.product_id

The product_id property is a read/write Variant that contains the product ID to search for; if left null, the product ID does not become part of the search criteria.

Definition

Property product_id As Variant

Parameters

None.

Error Values

This property sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

See Also

SimpleFindSearchInfo Object

OrderGroupManager.SimpleDelete

OrderGroupManager.SimpleFind


SimpleFindSearchInfo.SearchDateTimeColumn

The SearchDateTimeColumn property is a read/write Variant that contains the name of the DateTime column to use in the search. If left null, the DateTime column name does not become part of the search criteria.

Definition

Property SearchDateTimeColumn As Variant

Parameters

None.

Error Values

This property sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

See Also

SimpleFindSearchInfo Object

OrderGroupManager.SimpleDelete

OrderGroupManager.SimpleFind


SimpleFindSearchInfo.SearchDateTimeEnd

The SearchDateTimeEnd property is a read/write Variant that contains the DateTime end value to search for; if left null, the DateTime end value does not become part of the search criteria. Use this property in conjunction with the SearchDateTimeColumn property.

Definition

Property SearchDateTimeEnd As Variant

Parameters

None.

Error Values

This property sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

See Also

SimpleFindSearchInfo Object

OrderGroupManager.SimpleDelete

OrderGroupManager.SimpleFind


SimpleFindSearchInfo.SearchDateTimeStart

The SearchDateTimeStart property is a read/write Variant that contains the DateTime start value to search for; if left null, the DateTime start value does not become part of the search criteria. Use this property in conjunction with the SearchDateTimeColumn property.

Definition

Property SearchDateTimeStart As Variant

Parameters

None.

Error Values

This property sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

See Also

SimpleFindSearchInfo Object

OrderGroupManager.SimpleDelete

OrderGroupManager.SimpleFind


SimpleFindSearchInfo.StatusFilter

The StatusFilter property is a read/write Variant that contains the OrderGroup status.

Definition

Property StatusFilter As Long

Parameters

None.

Error Values

This property sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

See Also

SimpleFindSearchInfo Object

OrderGroupManager.SimpleDelete

OrderGroupManager.SimpleFind


SimpleFindSearchInfo.user_firstname

The user_firstname property is a read/write Variant that contains the first name of the user to search for; if left null, the first name of the user does not become part of the search criteria.

Definition

Property user_firstname As Variant

Parameters

None.

Error Values

This property sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

See Also

SimpleFindSearchInfo Object

OrderGroupManager.SimpleDelete

OrderGroupManager.SimpleFind


SimpleFindSearchInfo.user_id

The user_id property is a read/write Variant that contains the user ID to search for; if left null, the user ID does not become part of the search criteria.

Definition

Property user_id As Variant

Parameters

None.

Error Values

This property sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

See Also

SimpleFindSearchInfo Object

OrderGroupManager.SimpleDelete

OrderGroupManager.SimpleFind


SimpleFindSearchInfo.user_lastname

The user_lastname property is a read/write Variant that contains the last name of the user to search for; if left null, the last name of the user does not become part of the search criteria.

Definition

Property user_lastname As Variant

Parameters

None.

Error Values

This property sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

See Also

SimpleFindSearchInfo Object

OrderGroupManager.SimpleDelete

OrderGroupManager.SimpleFind


SimpleFindSearchInfo.user_org_id

The user_org_id property is a read/write Variant that contains the user organization ID to search for; if left null, the user organization ID does not become part of the search criteria.

Definition

Property user_org_id As Variant

Parameters

None.

Error Values

This property sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

See Also

SimpleFindSearchInfo Object

OrderGroupManager.SimpleDelete

OrderGroupManager.SimpleFind


SimpleFindSearchInfo.user_org_name

The user_org_name property is a read/write Variant that contains the user organization name to search for; if left null, the user organization name does not become part of the search criteria.

Definition

Property user_org_name As Variant

Parameters

None.

Error Values

This property sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

See Also

SimpleFindSearchInfo Object

OrderGroupManager.SimpleDelete

OrderGroupManager.SimpleFind


SimpleList Object

Use this object to create an array of variants that supports enumeration.

ProgID: | Commerce.SimpleList (Externally creatable)
COM Class Name: | CSimpleList
Type Library Name: | Microsoft Commerce 2000 Core Components Type Library
DLL Name: | MscsCore.dll
Threading Model: | Both

The properties of the SimpleList object are shown in the following table.

Property | Type | Description
Count | Long | Stores the number of elements in the SimpleList object. This property is read-only.
Item | Variant | Stores an element of the SimpleList object. This property is read/write.

The methods of the SimpleList object are shown in the following table.

Method | Description
Add | Adds the specified item to a SimpleList object.
Delete | Deletes a specified item from the SimpleList object.

See Also

General Purpose Objects

Dictionary Object


SimpleList.Add

Use this method to add the specified item to this SimpleList object.

Definition

Sub Add(
pVar As Variant
)

Parameters

pVar

A Variant to add to the SimpleList.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' The following example adds the string "Hello World" to the oSimpleList
' object instance
' oSimpleList is a Commerce SimpleList object
oSimpleList.Add("Hello World")

See Also

SimpleList Object

SimpleList.Delete


SimpleList.Count

Use this property to return the number of elements in the SimpleList object.

Definition

Property Count As Long

Parameters

None.

Error Values

This property sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The Count parameter points to valid data only if the method completes successfully.

The caller should always call this method before calling a SimpleList method that requires an array index in-value as a parameter (such as the Delete method).

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

SimpleList Object


SimpleList.Delete

Use this method to delete the specified item from the SimpleList object.

Definition

Sub Delete(
Index As Long
)

Parameters

Index

A Long that contains the index value of the item to delete.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Description
DISP_E_BADINDEX | The Index parameter references an out-of-range value. This means that Index contains a value either larger than the SimpleList or less than zero.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' The following example deletes the SimpleList item at index 1008
' oSimpleList is a Commerce SimpleList object
oSimpleList.Delete(1008)

See Also

SimpleList Object

SimpleList.Add

SimpleList.Count


SimpleList.Item

The Item property is a read/write Variant that contains an element of the SimpleList object. An initialized Variant is stored at a specified array index. If an item is already stored at the specified index, that item is overwritten by the put procedure.

Definition

Property Item(
Index As Long
) As Variant

Parameters

Index

A Long that contains the index of the item.

Error Values

This property sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to either standard or custom COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Description
DISP_E_BADINDEX | The Index parameter references an out-of-range value. This means that Index contains a value either larger than the SimpleList or less than zero.

Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

When putting a value, use the putref_Item method if you are setting an object reference; use the put_Item method if you are setting a scalar value.

See Also

SimpleList Object


SiteConfig Object

Use this object to accomplish the following:

  • Create or delete site configuration information

  • Save any updated site configuration information to the Administration database

  • Load site configuration information from the Administration database

  • Import resource configuration data to a site and export resource configuration data from a site
ProgID: | Commerce.SiteConfig (Externally creatable)
COM Class Name: | SiteConfig
Type Library Name: | Microsoft Commerce 2000 Configuration Type Library
DLL Name: | MSCSCfg.dll
Threading Model: | Apartment

The single property of the SiteConfig object is shown in the following table.

Property | Type | Description
Fields | Fields | Returns configuration fields, some of which hold configuration settings of resources. This property is read-write.

The methods of the SiteConfig object are shown in the following table.

Method | Description
AddRefToGroupComponent | Adds a reference to a global resource so that a site can access that resource.
CreateComponentConfig | Creates and writes configuration information for the specified resource to the Administration database.
DeleteComponentConfig | Deletes configuration information for the specified resource.
DeleteSQLScript | Deletes the specified SQL script file from the Administration database.
ExportResource | Writes the specified resource, resource properties, and attributes to the specified file.
GetAppsInSite | Gets a list of Commerce Server 2000 applications for the specified site.
GetIfCollection | Use this method to convert values read from the Fields property, if appropriate, into either a SimpleList object or a Variant Array.
GetResourcePropAttrib | Gets a dictionary of key/value pairs that denote the attributes of the specified property of the specified resource.
GetSQLScript | Gets the specified SQL script file from the Administration database.
ImportResource | Reads the specified resource, resource properties, and attributes from the specified file, and writes them to the Commerce Server 2000 database.
Initialize | Loads the site configuration data from the Administration database.
MakeArrayFromSimpleList | Converts the specified SimpleList object into an Array.
MakeArrayFromString | Converts values read from the Fields property into an Array.
MakeSimpleListFromArray | Converts an Array into a SimpleList object.
MakeStringFromArray | Converts an Array into an encoded string that can be written to the Fields property.
MakeStringFromSimpleList | Converts a SimpleList object into an encoded string that can be written to the Fields property.
PutSQLScript | Puts the specified SQL script file into the Administration database.
SaveConfig | Saves the site configuration settings to the Administration database.

Remarks

Depending on how you add your own custom resource, you should be able to use this object to access configuration settings from the Administration database.

See Also

Configuration Objects

Integrating Cutom Resources

GlobalConfigObject

SiteConfigReadOnly Object


SiteConfig.AddRefToGroupComponent

Use this method to add a reference to a global resource so that a site can access that resource. If you use this method to create a global resource, in order to read the correct property values, use the SiteConfigReadOnly object methods. To set the correct property values, use the GlobalConfig object on the global resource that is referenced by this site level resource.

Definition

Sub AddRefToGroupComponent(
bstrSiteResourceName As String,
bstrGroupResourceName As String
)

Parameters

bstrSiteResourceName

A String that contains the name of the resource configuration object to be added to the site.

bstrGroupResourceName

A String that contains the name of the global resource configuration object to which a reference is being added.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The Initialize method must be called before this method can be used.

If you use this method to create a global resource, use the SiteConfigReadOnly object methods to read the correct property values. Use the GlobalConfig object on the global resource that is referenced by this site level resource to set the correct property values.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' sSiteResName and sGlob are strings
' oSiteConfig is a Commerce SiteConfig object
oSiteConfig.AddRefToGroupComponent(sSiteResName,sGlob)

See Also

SiteConfig Object


SiteConfig.CreateComponentConfig

Use this method to create an instance of a configuration schema class, and load it into the site recordset.

Definition

Sub CreateComponentConfig(
bstrConfigComponentName As String,
bstrConfigSchemaClass As String
)

Parameters

bstrConfigComponentName

A String that contains the new name for the resource configuration object instance.

bstrConfigSchemaClass

A String that contains the resource configuration schema class name.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The Initialize method must be called before this method can be used.

This method creates an instance of the class specified in the bstrConfigSchemaClass parameter, and sets the Name property of the instance to the name specified in the bstrConfigComponentName parameter. It loads the instance into the site recordset.

This method calls the SaveConfig method.

The following table contains a list of schema classes for this method.

Admininstration Database Class Name | Resource Name
MSCS_Catalog | Product Catalog
MSCS_AppConfigDefault | App Default Config
MSCS_TransactionConfig | Transaction Config
MSCS_Transactions | Transactions
MSCS_Content | (No longer used)
MSCS_Campaigns | Campaigns
MSCS_AuthManager | Site CS Authentication
MSCS_DirectMailer | Direct Mailer
MSCS_Predictor | Predictor
MSCS_Predictor_Site | (No longer used)
MSCS_Datawarehouse_Group | Global Data Warehouse
MSCS_Datawarehouse_Site | Site Data Warehouse
MSCS_BizDataStore | Profiles Resource
MSCS_Address | IIS Applications (such as Retail, RetailBizDesk)
MSCS_UPMDtsTask | Profiling System DTS Task Information

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' sMyCatalog is a string
' oSiteConfig is a Commerce SiteConfig object
oSiteConfig.CreateComponentConfig(sMyCatalog, MSCS_Catalog)

See Also

SiteConfig Object

SiteConfig.DeleteComponentConfig


SiteConfig.DeleteComponentConfig

Use this method to delete the Administration database information for the specified resource.

Sub DeleteComponentConfig(
bstrConfigComponentName As String
)

Parameters

bstrConfigComponentName

A String that contains the name of the resource configuration object to be deleted.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The Initialize method must be called before this method can be used.

This delete does not remove any resource-specific data other than the configuration information. For instance, deleting the Product Catalog resource will not remove the Product Catalog tables from the database, just the configuration information.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' sMyResource is the name of an existing resource
' oSiteConfig is a Commerce SiteConfig object
oSiteConfig.DeleteComponentConfig (sMyResource)

See Also

SiteConfig Object

SiteConfig.CreateComponentConfig


SiteConfig.DeleteSQLScript

Use this method to delete the specified SQL script file from the Administration database.

Definition

Sub DeleteSQLScript(
sResource As String,
sScriptName As String
)

Parameters

sResource

A String that contains the name of the resource that is associated with the SQL script file that is to be deleted.

sScriptName

A String that contains the name of the SQL script file to delete.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The Initialize method must be called before this method can be used.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

SiteConfig Object


SiteConfig.ExportResource

Use this method to write the specified resource, resource properties, and attributes to the specified file.

Definition

Sub ExportResource(
bstrResourceName As String,
bstrFileName As String
)

Parameters

bstrResourceName

A String that contains the resource name.

bstrFileName

A String that contains the destination file name for the resource export.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The Initialize method must be called before this method can be used.

This method and the ImportResource method are complements of each other. This method creates the file that ImportResource consumes.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' sMyResource and sMyFileName.txt are strings
' oSiteConfig is a Commerce SiteConfig object
oSiteConfig.ExportResource(sMyResource, sMyFileName.txt)

See Also

SiteConfig Object


SiteConfig.Fields

The Fields property is a read/write Fields object. The Fields object contents include recordsets that hold the configuration settings of resources. A Fields object is an ADO disconnected recordset.

Definition

Property Fields As Object

Parameters

None.

Error Values

This property sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

You update the data in the Fields object to change your configuration information. You then call SaveConfig to commit those changes back to the database.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

SiteConfig Object


SiteConfig.GetAppsInSite

Use this method to get a list of Commerce Server 2000 applications for the specified site.

Definition

Function GetAppsInSite(
strSiteName As String
) As Variant

Parameters

strSiteName

A String that contains the name of the site for which you want the list of running Commerce Server 2000 applications.

Return Values

If this method completes successfully, it returns a Variant that contains the list of Commerce Server 2000 applications.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The Initialize method must be called before this method can be used.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' sMySiteName is a string
' vVariant is a Variant
' oSiteConfig is a Commerce SiteConfig object
vVariant = oSiteConfig.GetAppsInSite(sMySiteName)

See Also

SiteConfig Object


SiteConfig.GetIfCollection

Use this method to convert values read from the Fields property into the appropriate object such as a SimpleList object or Variant Array.

Definition

Function GetIfCollection(
strList As Variant
) As Variant

Parameters

strList

A Variant that contains the encoded string to be converted.

Return Values

If this method completes successfully, it returns a Variant containing the converted data in the appropriate data type.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

If the encoding in the string contained in the Fields property indicates a SimpleList object, then a SimpleList object is returned. If the encoding indicates a Variant Array, then a Variant Array is returned. If no collection object is indicated, then the method returns the original encoded input string.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' vVariant is a Variant; vEncodedString is a Variant
' oSiteConfig is a Commerce SiteConfig object
vVariant = oSiteConfig.GetIfCollection(vEncodedString)

See Also

SiteConfig Object


SiteConfig.GetResourcePropAttrib

Use this method to get a Dictionary object of key/value pairs that denote the attributes of the specified property of the specified resource.

Definition

Function GetResourcePropAttrib(
strResourceName As String,
strPropName As String
) As Object

Parameters

strResourceName

A String that contains the resource name.

strPropName

A String that contains the resource property name.

Return Values

If this method completes successfully, it returns an object reference to a Dictionary object containing the key/value pairs that denote the attributes of the specified property of the specified resource.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The Initialize method must be called before this method can be used.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' dDict is a Dictionary object
' sMyCatalog is an existing resource
' connstr_desc_Catalog is a valid Catalog resource property
' oSiteConfig is a Commerce SiteConfig object
dDict = _
oSiteConfig.GetResourcePropAttrib(sMyCatalog, connstr_desc_Catalog)

See Also

SiteConfig Object


SiteConfig.GetSQLScript

Use this method to get the specified SQL script file from the Administration database.

Definition

Function GetSQLScript(
sResource As String,
sScriptName As String
) As String

Parameters

sResource

A String that contains the resource associated with the required SQL script file.

sScriptName

A String that contains the file name of the required SQL script file.

Return Values

If this method completes successfully, it returns a String that contains the SQL script file contents.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The Initialize method must be called before this method can be used.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' sMyCatalog is an existing resource
' sMySQLFileName.sql and sContents are strings
' oSiteConfig is a Commerce SiteConfig object
sContents = oSiteConfig.GetSQLScript(sMyCatalog, sMySQLFileName.sql)

See Also

SiteConfig Object


SiteConfig.ImportResource

Use this method to read the specified resource, resource properties, and attributes from the specified file, and write them to the Commerce Server 2000 database.

Definition

Sub ImportResource(
bstrFileName As String
)

Parameters

bstrFileName

A String that contains the file name.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The Initialize method must be called before this method can be used.

This method is the complement of the ExportResource method. It consumes the file that ExportResource creates.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' sMyFileName is a string
sMyFileName = "C:\ExportedFile.txt"
' oSiteConfig is a Commerce SiteConfig object
oSiteConfig.ImportResource(sMyFileName)

See Also

SiteConfig Object


SiteConfig.Initialize

Use this method to load the site configuration from the Administration database.

Definition

Sub Initialize(
bstrSiteName As String
)

Parameters

bstrSiteName

A String that contains the site name.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' sMySiteName is a string
' oSiteConfig is a Commerce SiteConfig object
oSiteConfig.Initialize(sMySiteName)

See Also

SiteConfig Object


SiteConfig.MakeArrayFromSimpleList

Use this method to convert the specified SimpleList object into an Array.

Definition

Function MakeArrayFromSimpleList(
list As Object
) As Variant

Parameters

list

An object reference to the SimpleList object that you want to convert into an Array.

Return Values

If this method completes successfully, it returns a Variant containing the converted Array.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

Important

  • A special group of methods is used with multivalued arrays. These methods are the only approved and recommended way of storing and retrieving multivalued arrays in the Administration database. You must use the following methods with any property that has the structure of a multivalued array:
    • MakeArrayFromSimpleList

    • MakeSimpleListFromArray

    • MakeArrayFromString

    • MakeStringFromArray

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' vMyVariant is a Variant
' varMySimpleList is a SimpleList object
' oSiteConfig is a Commerce SiteConfig object
vMyVariant = oSiteConfig.MakeArrayFromSimpleList(varMySimpleList)

See Also

SiteConfig Object


SiteConfig.MakeArrayFromString

Use this method to convert an encoded string read from the Fields property into an Array. If the encoded string does not indicate Array properties, then the method returns the original string that was passed into it.

Definition

Function MakeArrayFromString(
strList As Variant
) As Variant

Parameters

strList

A Variant that contains the encoded string.

Return Values

If this method completes successfully, it returns a Variant that contains the converted Array or unconverted String.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

Important

  • A special group of methods is used with multivalued arrays. These methods are the only approved and recommended way of storing and retrieving multivalued arrays in the Administration database. You must use the following methods with any property that has the structure of a multivalued array:
    • MakeArrayFromSimpleList

    • MakeSimpleListFromArray

    • MakeArrayFromString

    • MakeStringFromArray

Note

  • This method can only be used on values exposed by the Fields object. The client-side disconnected ADO recordset has no support for Variants, Arrays, or objects as Fields columns. Therefore, the SiteConfig object resorts to storing data in an encoded string format.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' vEncoded is a Variant containing an encoded string
read from the Fields property
' vArray is a Variant
' oSiteConfig is a Commerce SiteConfig object
vArray = oSiteConfig.MakeArrayFromString(vEncoded)

See Also

SiteConfig Object


SiteConfig.MakeSimpleListFromArray

Use this method to convert an Array into a SimpleList object.

Definition

Function MakeSimpleListFromArray(
varArray As Variant
) As Object

Parameters

varArray

A Variant that contains the SimpleList object to convert.

Return Values

If this method completes successfully, it returns an object reference to the converted SimpleList object.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

Important

  • A special group of methods is used with multivalued arrays. These methods are the only approved and recommended way of storing and retrieving multivalued arrays in the Administration database. You must use the following methods with any property that has the structure of a multivalued array:
    • MakeArrayFromSimpleList

    • MakeSimpleListFromArray

    • MakeArrayFromString

    • MakeStringFromArray

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' vMyArray is a Variant
' varMySimpleList is a SimpleList object
' oSiteConfig is a Commerce SiteConfig object
varMySimpleList = oSiteConfig.MakeSimpleListFromArray(vMyArray)

See Also

SiteConfig Object


SiteConfig.MakeStringFromArray

Use this method to convert an Array object into an encoded string that can be written to the Fields property.

Definition

Function MakeStringFromArray(
varArray As Variant
) As Variant

Parameters

varArray

A Variant that contains the Array to encode.

Return Values

If this method completes successfully, it returns Variant that contains the encoded string.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

Important

  • A special group of methods is used with multivalued arrays. These methods are the only approved and recommended way of storing and retrieving multivalued arrays in the Administration database. You must use the following methods with any property that has the structure of a multivalued array:
    • MakeArrayFromSimpleList

    • MakeSimpleListFromArray

    • MakeArrayFromString

    • MakeStringFromArray

Note

  • This method can only be used when updating values exposed by the Fields object. The client-side disconnected ADO recordset has no support for Variants, Arrays, or objects as Fields columns. Therefore, the SiteConfig object resorts to storing data in an encoded string format.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' vEncoded is a Variant
' vArray is a Variant
' oSiteConfig is a Commerce SiteConfig object
vEncoded = oSiteConfig.MakeStringFromArray(vArray)

See Also

SiteConfig Object


SiteConfig.MakeStringFromSimpleList

Use this method to convert a SimpleList object into an encoded string that can be written to the Fields property.

Definition

Function MakeStringFromSimpleList(
slist As Object
) As String

Parameters

slist

An object reference to the SimpleList object that you wish to convert into an encoded string.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

Important

  • A special group of methods is used with multivalued arrays. These methods are the only approved and recommended way of storing and retrieving multivalued arrays in the Administration database. You must use the following methods with any property that has the structure of a multivalued array:
    • MakeArrayFromSimpleList

    • MakeSimpleListFromArray

    • MakeArrayFromString

    • MakeStringFromArray

Note

  • This method can only be used when updating values exposed by the Fields object. The client-side disconnected ADO recordset has no support for Variants, Arrays, SimpleLists or objects as Fields columns. Therefore, the SiteConfig object resorts to storing data in an encoded string format.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' vEncoded is a string
' vArray is a Variant
' varMySimpleList is a SimpleList object
' oSiteConfig is a Commerce SiteConfig object
vEncoded = oSiteConfig.MakeStringFromSimpleList(varMySimpleList)

See Also

SiteConfig Object


SiteConfig.PutSQLScript

Use this method to put the specified SQL script file into the Administration database.

Definition

Sub PutSQLScript(
sResource As String,
sScriptName As String,
sScriptContents As String
)

Parameters

sResource

A String that contains the name of the resource associated with the SQL script file.

sScriptName

A String that contains the name of the SQL script file.

sScriptContents

A String that contains the SQL script file contents.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The Initialize method must be called before this method can be used.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' sMySQLFileName.sql, sMyRes and sMyContents are strings
' oSiteConfig is a Commerce SiteConfig object
oSiteConfig.PutSQLScript(sMyRes, "sMySQLFileName.sql" ,sMyContents )

See Also

SiteConfig Object


SiteConfig.SaveConfig

Use this method to save any site configuration settings that have been changed or updated.

Definition

Sub SaveConfig()

Parameters

None.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The Initialize method must be called before this method can be used.

This method saves the entire configuration for a site. If two users are trying to update different parts of the site configuration at the same time, the last one to save will overwrite the changes made by the first user updating the site configuration.

See Also

SiteConfig Object


SiteConfigReadOnly Object

Use this object to load site configuration information from the Administration database.

ProgID: | Commerce.SiteConfigReadOnly (Externally creatable)
COM Class Name: | SiteConfigReadOnly
Type Library Name: | Microsoft Commerce 2000 Configuration Type Library
DLL Name: | MSCSCfg.dll
Threading Model: | Apartment

The single property of the SiteConfigReadOnly object is shown in the following table.

Property | Type | Description
Fields | Fields | Returns configuration settings of the site and the site resources. This property is read-only.

The methods of the SiteConfigReadOnly object are shown in the following table.

Method | Description
GetAppsInSite | Gets a list of Commerce Server 2000 applications for the specified site.
GetIfCollection | Use this method to convert values read from the Fields property, if appropriate, into either a SimpleList object or a Variant Array.
Initialize | Loads the site configuration data from the Administration database.
MakeArrayFromSimpleList | Converts the specified SimpleList object into an Array.
MakeArrayFromString | Converts values read from Fields property into an Array.
MakeSimpleListFromArray | Converts an Array into a SimpleList object.
MakeStringFromArray | Converts an Array into an encoded string, which can be written to the Fields property.
MakeStringFromSimpleList | Converts a SimpleList object into an encoded string, which can be written to the Fields property.

Remarks

The SiteConfigReadOnly object allows access to more configuration data than does the SiteConfig object. With the SiteConfigReadOnly object, group resource values are returned when you access references to resources. In contrast, with the SiteConfig object, only references to the names of the resources are returned.

Depending on how you add your own custom resource, you should be able to use this object to access configuration settings from the Administration database.

See Also

Configuration Objects

Integrating Cutom Resources

GlobalConfigObject

SiteConfig Object


SiteConfigReadOnly.Fields

The Fields property is a read-only Fields object. The Fields object contents hold the configuration settings of the site and its resources.

Definition

Property Fields As Object

Parameters

None.

Error Values

This property sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The Initialize method must be called before this method can be used.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

SiteConfigReadOnly Object

SiteConfigReadOnly.Initialize


SiteConfigReadOnly.GetAppsInSite

Use this method to get a list of Commerce Server 2000 applications for the specified site.

Definition

Function GetAppsInSite(
strSiteName As String
) As Variant

Parameters

strSiteName

A String that contains the name of the site for which you want the list of running Commerce Server 2000 applications.

Return Values

If this method completes successfully, it returns Variant that contains the list of Commerce Server 2000 applications.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The Initialize method must be called before this method can be used.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' sMySiteName is a String
' vVariant is a Variant
' oSiteConfigReadOnly is a Commerce SiteConfigReadOnly object
vVariant = oSiteConfigReadOnly.GetAppsInSite(sMySiteName)

See Also

SiteConfigReadOnly Object


SiteConfigReadOnly.GetIfCollection

Use this method to convert values read from the Fields property into the appropriate object such as a SimpleList object or Variant Array.

Definition

Function GetIfCollection(
strList As Variant
) As Variant

Parameters

strList

A Variant that contains the encoded string to be converted.

Return Values

If this method completes successfully, it returns a Variant containing the converted data in the appropriate data type.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

If the encoding in the string contained in the Fields property indicates a SimpleList object, then a SimpleList object is returned. If the encoding indicates a Variant Array, then a Variant Array is returned. If no collection object is indicated, then the method returns the original encoded input string.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' vVariant is a Variant; vEncodedString is a Variant
' oSiteConfigReadOnly is a Commerce SiteConfigReadOnly object
vVariant = oSiteConfigReadOnly.GetIfCollection(vEncodedString)

See Also

SiteConfigReadOnly Object


SiteConfigReadOnly.Initialize

Use this method to load the site configuration from the Administration database.

Definition

Sub Initialize(
bstrSiteName As String
)

Parameters

bstrSiteName

A String that contains the site name.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The Initialize method must be called before the object can be used.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' sMySiteName is a string
' oSiteConfigReadOnly is a Commerce SiteConfigReadOnly object
oSiteConfigReadOnly.Initialize(sMySiteName)

See Also

SiteConfigReadOnly Object


SiteConfigReadOnly.MakeArrayFromSimpleList

Use this method to convert the specified SimpleList object into an Array.

Definition

Function MakeArrayFromSimpleList(
list As Object
) As Variant

Parameters

list

The object reference to the SimpleList object that you wish to convert into an Array.

Return Values

If this method completes successfully, it returns a Variant containing the converted Array.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

Important

  • There is a special group of methods used with multivalued arrays. These methods are the only approved and recommended way of storing and retrieving multivalued arrays in the Administration database. You must use the following methods with any property that has the structure of a multivalued array:
    • MakeArrayFromSimpleList

    • MakeSimpleListFromArray

    • MakeArrayFromString

    • MakeStringFromArray

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' vMyVariant is a Variant
' varMySimpleList is a SimpleList object
' oSiteConfigReadOnly is a Commerce SiteConfigReadOnly object
vMyVariant = oSiteConfigReadOnly.MakeArrayFromSimpleList(varMySimpleList)

See Also

SiteConfigReadOnly Object


SiteConfigReadOnly.MakeArrayFromString

Use this method to convert an encoded string read from the Fields property into an Array. If the encoded string does not indicate Array properties, then the method returns the original string that was passed into it.

Definition

Function MakeArrayFromString(
strList As Variant
) As Variant

Parameters

strList

A Variant that contains the encoded string.

Return Values

If this method completes successfully, it returns a Variant that contains the converted Array or unconverted String.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

Important

  • There is a special group of methods used with multivalued arrays. These methods are the only approved and recommended way of storing and retrieving multivalued arrays in the Administration database. You must use the following methods with any property that has the structure of a multivalued array:
    • MakeArrayFromSimpleList

    • MakeSimpleListFromArray

    • MakeArrayFromString

    • MakeStringFromArray

Note

  • This method can only be used on values exposed by the Fields object. The client-side disconnected ADO recordset has no support for Variants, Arrays, or objects as Fields columns. Therefore, the SiteConfigReadOnly object resorts to storing data in an encoded string format.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' vEncoded is a Variant containing an encoded string
‘ read from the Fields property
' vArray is a Variant
' oSiteConfigReadOnly is a Commerce SiteConfigReadOnly object
vArray = oSiteConfigReadOnly.MakeArrayFromString(vEncoded)

See Also

SiteConfigReadOnly Object


SiteConfigReadOnly.MakeSimpleListFromArray

Use this method to convert an Array into a SimpleList object.

Definition

Function MakeSimpleListFromArray(
varArray As Variant
) As Object

Parameters

varArray

A Variant that contains the SimpleList object to convert.

Return Values

If this method completes successfully, it returns an object reference to the converted SimpleList object.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

Important

  • There is a special group of methods used with multivalued arrays. These methods are the only approved and recommended way of storing and retrieving multivalued arrays in the Administration database. You must use the following methods with any property that has the structure of a multivalued array:
    • MakeArrayFromSimpleList

    • MakeSimpleListFromArray

    • MakeArrayFromString

    • MakeStringFromArray

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' vMyArray is a Variant
' varMySimpleList is an object reference to a SimpleList object
' oSiteConfigReadOnly is a Commerce SiteConfigReadOnly object
varMySimpleList = oSiteConfigReadOnly.MakeSimpleListFromArray(vMyArray)

See Also

SiteConfigReadOnly Object


SiteConfigReadOnly.MakeStringFromArray

Use this method to convert an Array object into an encoded string, which can be written to the Fields property.

Definition

Function MakeStringFromArray(
varArray As Variant
) As Variant

Parameters

varArray

A Variant that contains the Array to encode.

Return Values

If this method completes successfully, it returns Variant that contains the encoded string.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

Important

  • There is a special group of methods used with multivalued arrays. These methods are the only approved and recommended way of storing and retrieving multivalued arrays in the Administration database. You must use the following methods with any property that has the structure of a multivalued array:
    • MakeArrayFromSimpleList

    • MakeSimpleListFromArray

    • MakeArrayFromString

    • MakeStringFromArray

Note

  • This method can only be used when updating values exposed by the Fields object. The client-side disconnected ADO recordset has no support for Variants, Arrays, or objects as Fields columns. Therefore, the SiteConfigReadOnly object resorts to storing data in an encoded string format.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' vEncoded is a Variant
' vArray is a Variant
' oSiteConfigReadOnly is a Commerce SiteConfigReadOnly object
vEncoded = oSiteConfigReadOnly.MakeStringFromArray(vArray)

See Also

SiteConfigReadOnly Object


SiteConfigReadOnly.MakeStringFromSimpleList

Use this method to convert a SimpleList object into an encoded string, which can be written to the Fields property.

Definition

Function MakeStringFromSimpleList(
slist As Object
) As String

Parameters

slist

An object reference to the SimpleList object that you wish to convert into an encoded string.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

Important

  • There is a special group of methods used with multivalued arrays. These methods are the only approved and recommended way of storing and retrieving multivalued arrays in the Administration database. You must use the following methods with any property that has the structure of a multivalued array:
    • MakeArrayFromSimpleList

    • MakeSimpleListFromArray

    • MakeArrayFromString

    • MakeStringFromArray

Note

  • This method can only be used when updating values exposed by the Fields object. The client-side disconnected ADO recordset has no support for Variants, Arrays, SimpleLists or objects as Fields columns. Therefore, the SiteConfigReadOnly object resorts to storing data in an encoded string format.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' vEncoded is a string
' vArray is a Variant
' varMySimpleList is a SimpleList object
' oSiteConfigReadOnly is a Commerce SiteConfigReadOnly object
vEncoded = oSiteConfigReadOnly.MakeStringFromSimpleList(varMySimpleList)

See Also

SiteConfigReadOnly Object


StandardSManager Object

Use this object to facilitate the run time creation and retrieval of shopper IDs.

ProgID: | Commerce.StandardSManager (Externally creatable)
COM Class Name: | MSCSStandardSManager_3_0
Type Library Name: | Commerce 1.0 Type Library
DLL Name: | Commerce.dll
Threading Model: | Both

The single property of the StandardSManager object is shown in the following table.

Property | Type | Description
Mode | Integer | Determines how the GetShopperID and PutShopperID methods of the Page object retrieve and store shopper IDs.

The methods of the StandardSManager object are shown in the following table.

Method | Description
CreateShopperId | Creates a unique shopper ID for the current user.
GetShopperId | Returns the unique shopper ID for the current user.
InitManager | Initializes the StandardSManager object.
PutShopperId | Writes the specified shopper ID to a cookie and/or stores it for use in a URL or SURL, depending on the initialization mode of the StandardSManager for the site.

Remarks

This object is only included for purposes of backward compatibility with Site Server 3.0 Commerce Edition; it has been replaced by the AuthManager object.

See Also

Backward Compatibility Objects

AuthManager Object


StandardSManager.CreateShopperId

Use this method to create a unique shopper ID for the current user.

Definition

Function CreateShopperId() As String

Parameters

None.

Return Values

If this method completes successfully, it returns a String containing the new shopper ID.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

StandardSManager Object

StandardSManager.InitManager

StandardSManager.GetShopperId

StandardSManager.PutShopperId


StandardSManager.GetShopperId

Use this method to retrieve the shopper ID for the current user. The shopper ID is returned from a URL query string or a cookie, depending on the initialization mode of the StandardSManager object for the site.

Definition

Function GetShopperId(
pdispContext As Object
) As Variant

Parameters

pdispContext

An object reference that holds the ASP scripting context.

Return Values

If this method completes successfully, it returns a Variant that specifies the shopper ID.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

If no shopper ID is found, the GetShopperID method returns an empty string.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

StandardSManager Object

StandardSManager.Mode

StandardSManager.PutShopperId


StandardSManager.InitManager

Use this method to initialize the StandardSManager object to the specified site name and mode.

Definition

Sub InitManager(
bstrStoreKey As String,
bstrMode As String
)

Parameters

bstrStoreKey

A String that contains the name of the site.

bstrMode

A String that indicates how user information is to be stored. For more information about initialization modes, see the Remarks section.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

The bstrMode parameter can take the following values:

Mode | Behavior
Cookie | The PutShopperID method stores the shopper ID in a cookie on the client system. The GetShopperID method retrieves this cookie.
url | The PutShopperID method appends the shopper ID to the URL, using MCSSIDUrlKey as the name part of the URL variable. The GetShopperID method retrieves the shopper ID from the URL.
Cookieurl | The PutShopperID method stores the shopper ID in a cookie on the client system and in the URL. The GetShopperID method first attempts to retrieve the shopper ID from the cookie, and then from the URL.
Urlcookie | The PutShopperID method stores the shopper ID in a URL, and stores it as a cookie on the client system. The GetShopperID method first attempts to retrieve the shopper ID from the URL, then from the cookie.

This object is only included for purposes of backward compatibility with Site Server 3.0 Commerce Edition.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Example

' oStdSManager is a Commerce.StandardSManager object
oStdSManager.InitManager("mySiteName", "Cookie")

See Also

StandardSManager Object

StandardSManager.Mode

StandardSManager.PutShopperId


StandardSManager.Mode

The Mode property is a read/write Integer that determines how the GetShopperID and PutShopperID methods of the Page object retrieve and store shopper IDs.

Definition

Property Mode As Integer

Parameters

None.

Error Values

This property sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

After creating a StandardSManager object, but before calling the GetShopperID or PutShopperID methods, you must initialize the StandardSManager object. To do this, call the InitManager method of the StandardSManager object, specifying the site name and the initialization mode.

The following table shows the values that the mode property integer can take.

Mode | Behavior
0 | Look only at cookie
1 | Look only at URL
2 | Look at cookie and then URL
3 | Look at URL and then cookie

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

StandardSManager Object

Page Object

StandardSManager.InitManager


StandardSManager.PutShopperId

Use this method to store a shopper ID for the current user. After the object has been initialized, the shopper ID will be stored in a cookie or as part of the URL.

Definition

Sub PutShopperId(
pdispContext As Object,
bstrShopperID As String
)

Parameters

pdispContext

An object reference that holds the ASP scripting context.

bstrShopperID

A String that contains the shopper ID to be stored.

Return Values

None.

Error Values

This method sets the Number property of the global Err object to S_OK (&H00000000) to indicate success and to standard COM error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object. In particular, the Description property may contain a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

StandardSManager Object

StandardSManager.Mode

StandardSManager.GetShopperId


C++ Invocation

This section describes the Component Object Model (COM) objects supplied with Microsoft Commerce Server 2000 and how to invoke their properties and methods from C++. The following table lists each object and provides a brief description of its purpose.

Object | Description
AdminEventLog | Writes error, informational, warning, and success messages to the event log.
AdminFiles | Provides read-only access to server-side binary and text files.
AdminSite | Provides read/write access to site configuration properties and allows site administration. This object is supplied for backward compatibility purposes only.
AdminWebServer | Allows enumeration of Web sites and their properties.
AppConfig | Allows retrieval of country, region codes, and names from the site configuration store.
AppFrameWork | Provides formatting and validation methods that simplify forms processing in Active Server Pages (ASP).
AsyncRpt | Provides asynchronous rendering and exporting of static reports.
Auction | Provides methods for supporting auctions.
AuthManager | Provides a secure, standardized, and extensible way to manage authentication of users.
BizDeskSecurity | Allows specific Commerce Server Business Desk modules to be hidden from particular users.
CacheManager | Provides generic caching services.
CatalogManager | Allows management of catalogs across the entire Product Catalog System.
CatalogSets | Allows filtering of multiple custom catalogs for different users and organizations.
CatalogToVendorAssociation | Allows a catalog to be associated with particular vendor.
Category | Allows management of a product hierarchy within a particular catalog.
ContentList | Contains a representation of each content item eligible for a given request for content. Also provides services to Content Selection Framework (CSF) components such as filtering and sorting.
ContentListFactory | Allows creation of ContentList objects, and stores data shared by those objects.
ContentListSchema | Allows manipulation of the schema for a ContentListFactory object.
ContentSelector | Allows specification and retrieval of page content.
DataFunctions | Provides methods to perform locale-based data type handling and value range checking.
DBStorage | Provides methods for mapping Dictionary and SimpleList objects to and from a database, primarily for the storage of receipt and order information.
Dictionary | Supports the creation, storage, and retrieval of name/value pairs in memory.
DictionaryXMLTransforms | Transforms data in a Dictionary object into Extensible Markup Language (XML), and XML data into a Dictionary object.
EuroDisplay | Converts and formats currency amounts for use where multiple currencies must be displayed.
ExpressionEval | Allows selection and evaluation of one or more expressions against a set of profiles.
ExpressionStore | Provides methods to create, save, modify, and retrieve expressions.
ExprEvalContext | Stores a specific evaluation context (set of profiles) that can be used for multiple expression evaluation operations.
ExprFltrQueryBldr | Translates an expression in XML form into a SQL filter query string.
GenID | Provides methods to generate globally unique identifiers (GUID), and to create and maintain multiple, global sequential counters which are persisted in a database.
GlobalConfig | Provides methods for the configuration management of global resources.
ListManager | Provides methods to create, destroy, manage, and manipulate lists.
LRUCache | Provides a least recently used (LRU) cache for the CacheManager object. It stores a limited number of entries and sorts them according to the least recently used element.
MessageManager | Stores text strings in multiple languages. One usage involves the Order Processing pipeline (OPP) components describing error conditions generated during order form processing.
MicroPipe | Runs a single pipeline component from an ASP page without using a pipeline configuration file (.pcf).
MtsPipeline | Executes a non-transacted Microsoft Commerce Server 2000 pipeline.
MtsTxPipeline | Executes a transacted Microsoft Commerce Server 2000 pipeline.
OrderForm | Provides in-memory storage of user and purchase information.
OrderGroup | Allows management of complex orders, such as those containing items from different suppliers, and multiple shipments.
OrderGroupManager | Provides methods to manage OrderGroup and OrderForm objects.
OrderPipeline | Runs a Microsoft Commerce Server 2000 pipeline, and is particularly useful in the Content Selection Framework.
Page | Provides formatting and validation methods that simplify forms processing in ASP pages. This object is supplied for backward compatibility purposes only.
PooledPipeline | Executes a non-transacted Microsoft Commerce Server 2000 pipeline that uses COM+ object pooling for better performance.
PooledTxPipeline | Executes a transacted Microsoft Commerce Server 2000 pipeline that uses COM+ object pooling for better performance.
PredictorClient | Provides methods for downloading prediction models, setting prediction context, and performing predictions.
PredictorServiceAdmin | Allows retrieval of prediction models and prediction model configurations.
PredictorServiceSiteAdmin | Allows management of prediction models and prediction model configurations.
PredModelBuilder | Provides properties and methods to control multiple build threads of prediction models.
Product | Allows manipulation of the relationships between a product variant and a product category.
ProductCatalog | Allows creation, deletion, and modification of catalog data.
ProfileObject | Provides run-time read/write access to profile property data and read-only access to property attributes.
ProfileService | Allows creation, deletion, and retrieval of instances of profile schemas.
ReportRenderer | Provides synchronous rendering and exporting of static reports.
RowCollection | Allows enumeration of the rows returned from the ActiveRows and AllRows properties, and the Search method, of a ContentList object, and from the AllRows property and the Search method of a ContentListFactory object.
Shipping | Creates shipping cost preview information.
ShippingMethodManager | Allows management of multiple shipping methods.
SimpleFindResultInfo | Allows the specification of search criteria when using the OrderGroup and OrderGroupManager objects.
SimpleFindSearchInfo | Allows the specification of search criteria when performing search and delete operations using the OrderGroup and OrderGroupManager objects.
SimpleList | Allows creation of an array of Variants that supports enumeration.
SiteConfig | Provides for configuration management of site resources.
SiteConfigReadOnly | Provides methods to read global and site configuration values from the Administration database.
StandardSManager | Facilitates the run time creation and retrieval of user IDs. This object is supplied for backward compatibility purposes only.


AdminEventLog Object

Use this object to write error, informational, and warning messages to the event log.

ProgID: | Commerce.AdminEventLog (Externally creatable)
COM Class Name: | AdminEventLog
COM Interface Name: | IAdminEventLog
Interface ID Constant: | None
Header File: | None
Type Library Name: | Commerce Admin 1.0 Type Library
DLL Name: | MSCSadmin.dll
Threading Model: | Both

In C++, use the IAdminEventLog interface to access the methods of the AdminEventLog object.

The methods of the AdminEventLog object are shown in the following table.

Method | Description
Initialize | Initializes the site, the source, and the event server for writing events.
WriteErrorEvent | Writes error messages (such as resource problems, missing files, and so on) to the Commerce Server event log.
WriteInformationalEvent | Writes informational messages (such as names of logged-on users) to the Commerce Server event log.
WriteWarningEvent | Writes warning messages (such as low memory levels) to the Commerce Server event log.


IAdminEventLog::Initialize

Use this method to initialize the object.

Definition

HRESULT IAdminEventLog::Initialize(
BSTR bstrServer
);

Parameters

bstrServer

[in] A BSTR that contains the server name.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

AdminEventLog Object


IAdminEventLog::WriteErrorEvent

Use this method to write an error event to the Commerce Server event log.

Definition

HRESULT IAdminEventLog::WriteErrorEvent(
BSTR bstrSiteName,
BSTR bstrMessage
);

Parameters

bstSiteName

[in] A BSTR that contains the site name.

bstrMessage

[in] A BSTR that contains the error event message string.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

AdminEventLog Object

IAdminEventLog::WriteInformationalEvent

IAdminEventLog::WriteWarningEvent


IAdminEventLog::WriteInformationalEvent

Use this method to write an informational event to the Commerce Server event log.

Definition

HRESULT IAdminEventLog::WriteInformationalEvent(
BSTR bstrSiteName,
BSTR bstrMessage
);

Parameters

bstSiteName

[in] A BSTR that contains the site name.

bstrMessage

[in] A BSTR that contains the informational event message string.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

AdminEventLog Object

IAdminEventLog::WriteErrorEvent

IAdminEventLog::WriteWarningEvent


IAdminEventLog::WriteWarningEvent

Use this method to write a warning event to the Commerce Server event log.

Definition

HRESULT IAdminEventLog::WriteWarningEvent(
BSTR bstrSiteName,
BSTR bstrMessage
);

Parameters

bstSiteName

[in] A BSTR that contains the site name.

bstrMessage

[in] A BSTR that contains the warning event message string.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

AdminEventLog Object

IAdminEventLog::WriteErrorEvent

IAdminEventLog::WriteInformationalEvent


AdminFiles Object

Use this object for read-only access to server-side files. Different methods are provided to access binary and text files, respectively.

ProgID: | Commerce.AdminFiles (Externally creatable)
COM Class Name: | CAdminFiles
COM Interface Name: | IAdminFiles
Interface ID Constant: | None
Header File: | None
Type Library Name: | Commerce Admin 1.0 Type Library
DLL Name: | MSCSadmin.dll
Threading Model: | Both

In C++, use the IAdminFiles interface to access the methods of the AdminFiles object.

The methods of the AdminFiles object are shown in the following table.

Method | Description
ReadFromBinaryFile | Reads the content of the specified binary file.
ReadFromFile | Reads the content of the specified text file.

See Also

General Purpose Objects


IAdminFiles::ReadFromBinaryFile

Use this method to read the contents of the specified binary file. The file can contain any type of data, such as a numeric data or a bitmap.

Definition

HRESULT IAdminFiles::ReadFromBinaryFile(
BSTR bstrFileName,
VARIANT* prgByte
);

Parameters

bstrFileName

[in] A BSTR that specifies the path and file name to read.

prgByte

[out] The address of a VARIANT used to return the file contents.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The prgByte parameter contains valid data only if the method returns successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

AdminFiles Object

IAdminFiles::ReadFromFile


IAdminFiles::ReadFromFile

Use this method to return the contents of the specified text file. The contents of the file are returned as a text string.

Definition

HRESULT IAdminFiles::ReadFromFile(
BSTR bstrFileName,
BSTR* pbstrOut
);

Parameters

bstrFileName

[in] A BSTR that specifies the path and file name to read.

pbstrOut

[out] The address of a BSTR used to return the file contents.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pbstrOut parameter contains valid data only if the method returns successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

AdminFiles Object

IAdminFiles::ReadFromBinaryFile


AdminSite Object

Use this object to gain centralized access to the Site Server 3.0 Commerce Edition site configuration, so that you can configure and maintain the site.

Important

  • You cannot use this object with Commerce Server 2000 sites. It is included only for backwards compatibility with Site Server 3.0 Commerce Edition.
ProgID: | Commerce.AdminSite (Externally creatable)
COM Class Name: | AdminSite
COM Interface Name: | IAdminSite
Interface ID Constant: | None
Header File: | None
Type Library Name: | Commerce Admin 1.0 Type Library
DLL Name: | MSCSadmin.dll
Threading Model: | Both

In C++, use the IAdminSite interface to access the properties and methods of the AdminSite object.

The properties of the AdminSite object are shown in the following table.

Property | Type | Description
Directory | BSTR | Stores the currently registered Site Server 3.0 Commerce Edition site physical directory. This property is read/write.
Status | VARIANT | Stores the open/closed status of a Site Server 3.0 Commerce Edition site. This property is read/write.
Version | long | Stores the Site Server 3.0 Commerce Edition version number. This property is read-only.

The methods of the AdminSite object are shown in the following table.

Method | Description
Create | Creates a Site Server 3.0 Commerce Edition site.
Delete | Deletes a Site Server 3.0 Commerce Edition site.
Initialize | Initializes the AdminSite object to load information related to the Site Server 3.0 Commerce Edition site.
InitializeFromMDPath | Initializes the AdminSite object from a metabase path.
IsValidName | Determines whether a given text string is a valid short name for a Site Server 3.0 Commerce Edition site.
ReadDefaultProperties | Reads the properties from the Site.csc file and returns a Dictionary object containing these properties.
ReadManagerProperties | Reads the properties from the Site.csc file and returns a Dictionary object (the site dictionary) containing these properties.
Reload | Resets all application and session objects for the Site Server 3.0 Commerce Edition site.
WriteDefaultProperties | Writes the properties from the specified site dictionary to the Site.csc file.
WriteManagerProperties | Writes the properties from the specified site dictionary to the Site\Manager\Config\Site.csc file.

Remarks

The AdminSite object provides methods for administering a site, such as specifying data sources and user accounts. The object keeps a number of properties related to the configuration in the site dictionary, which is an implementation of a Dictionary object called MSCSSite. These properties include the short and long names of the site, the secure host, the non-secure host, and the names of other Dictionary objects such as lists of named connection strings and named queries.

See Also

Backward Compatibility Objects


IAdminSite::Create

Use this method to create a Site Server 3.0 Commerce Edition site and to optionally create an application and the Config\SQL\SqlSvr and Config\SQL\Oracle subdirectories.

Definition

HRESULT IAdminSite::Create(
BSTR bstrInstance,
BSTR bstrVDir,
BSTR bstrDir,
long nAuthorization,
VARIANT_BOOL bIsApplication,
VARIANT_BOOL bIsCommerceSite
);

Parameters

bstrInstance

[in] A numeric value expressed as a BSTR representing a Web site. For the default Web site, use (1).

bstrVDir

[in] A BSTR that contains the Site Server 3.0 Commerce Edition site short name (virtual directory).

bstrDir

[in] A BSTR that specifies the physical directory in which to create the site.

nAuthorization

[in] A long that contains the authorization type.

bIsApplication

[in] A VARIANT_BOOL that controls whether an application is created for the site. If set to TRUE, an application is created for the site. Otherwise no application is created. This setting must be TRUE for a Site Server 3.0 Commerce Edition site.

bIsCommerceSite

[in] A VARIANT_BOOL that controls whether SQL Server and Oracle subdirectories are created for the site. When set to TRUE, the method marks the site for administration by Site Server 3.0 Commerce Edition and creates the Directory\Config\SQL\SqlSvr and Directory\Config\SQL\Oracle subdirectories (where Directory is the value passed in the bstrDir parameter). When set to FALSE, the method creates the top level Directory directory only.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

An AdminSite object must be initialized before most of its other methods can be called (the Create and IsValidName methods are exceptions). An object that has been created by the Create method of the AdminSite object is automatically initialized and does not need an explicit call to its Initialize method.

The valid characters and length for a Web site name are determined by the restrictions on the names of Microsoft SQL Server tables. In addition, a short name must not conflict with another short name on the server.

Before you actually create a site, use the IsValidName method to ensure that the short name of the site is valid. The name must conform to several rules for forming valid names in many environments. For example, Commerce Server appends the short name of a site to database tables and to generated pages.

See Also

AdminSite Object

IAdminSite::Delete

IAdminSite::Initialize

IAdminSite::IsValidName


IAdminSite::Delete

Use this method to delete a Site Server 3.0 Commerce Edition site. The Delete method removes attributes of the site from the Internet Information Services (IIS) metabase (directories and databases are not removed).

Definition

HRESULT IAdminSite::Delete(
);

Parameters

None.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

An AdminSite object must be initialized before most of its other methods can be called (the Create and IsValidName methods are exceptions). An object that has been created by the Create method of the AdminSite object is automatically initialized and does not need an explicit call to its Initialize method.

See Also

AdminSite Object

IAdminSite::Create


IAdminSite::get_Directory, put_Directory

The Directory property is a read/write string that contains the currently registered Site Server 3.0 Commerce Edition site physical directory.

Definition

Get method:

HRESULT IAdminSite::get_Directory(
BSTR* Directory
);

Put method:

HRESULT IAdminSite::put_Directory(
BSTR Directory
);

Parameters

Directory

[in] When putting the property, a BSTR that contains the name of the directory.
[out] When getting the property, the address of a BSTR used to return the name of the directory.

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

This property returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The valid characters and length for a Web site name are determined by the restrictions on the file system.

The Directory parameter contains valid data only if the property is accessed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

AdminSite Object

IAdminSite::InitializeFromMDPath


IAdminSite::Initialize

Use this method to initialize the AdminSite object so that information related to the Site Server 3.0 Commerce Edition site can be loaded. The site is uniquely identified using the site short name and the server instance. The ReadDefaultProperties method uses this information to load the site properties.

Definition

HRESULT IAdminSite::Initialize(
BSTR bstrInstance,
BSTR bstrVDir
);

Parameters

bstrInstance

[in] A numeric value, expressed as a BSTR that represents a Web site.

bstrVDir

[in] A BSTR that contains the Site Server 3.0 Commerce Edition site short name (virtual directory).

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

You must initialize an AdminSite object before you can use any other methods of the object (except Create and IsValidName). An object created by the Create method of the AdminSite object is initialized automatically and does not need an explicit call to the Initialize method.

See Also

AdminSite Object

IAdminSite::ReadDefaultProperties

IAdminSite::Create

IAdminSite::IsValidName


IAdminSite::InitializeFromMDPath

Use this method to initialize the AdminSite object from a specified Internet Information Services (IIS) metabase path. The metabase path can be retrieved using a call to the Request.ServerVariables method.

Definition

HRESULT IAdminSite::InitializeFromMDPath(
BSTR bstrMDPath
);

Parameters

bstrMDPath

[in] A BSTR that contains the metabase path. The metabase path can be retrieved using a call to the Request.ServerVariables method.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

Unlike the Initialize method, which requires that a server instance and virtual directory be specified separately, this method requires a metabase path to be specified.

See Also

AdminSite Object

IAdminSite::Initialize


IAdminSite::IsValidName

Use this method to determine the validity of a site name. The IsValidName method returns a value of True if the specified Site Server 3.0 Commerce Edition site short name is valid, and False otherwise.

Definition

HRESULT IAdminSite::IsValidName(
BSTR bstrName,
BSTR bstrInstance,
VARIANT_BOOL* pbRet
);

Parameters

bstrName

[in] A BSTR that specifies the short name to be tested.

bstrInstance

[in] A BSTR that specifies the Web server instance. To obtain a list of server instances, use the GetWebSites method. For the default Web site, use "1".

pbRet

[out] The address of a VARIANT_BOOL used to return an indication of whether or not the site name is valid.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The valid characters and length for a Web site name are determined by the restrictions on the names of Microsoft SQL Server tables. In addition, a short name must not conflict with any other short name on the server.

The pbRet parameter contains valid data only if the method returns successfully.

Before you actually create a site, use this method to ensure that the short name of the site is valid. The name must conform to several rules for forming valid names in many environments. For example, Commerce Server appends the short name of a site to database tables and to generated pages.

The IsValidName method of an object can be called without calling the Initialize or Create methods of the object.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

AdminSite Object

IAdminSite::Initialize


IAdminSite::ReadDefaultProperties

Use this method to read the properties from the Site.csc file and return a site dictionary containing these properties.

Definition

HRESULT IAdminSite::ReadDefaultProperties(
IDictionary** ppIDictProp
);

Parameters

ppIDictProp

[out] The address of a pointer used to return the IDictionary interface of the Dictionary object that contains the site properties read from the Site.csc file.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The Site.csc file for the Site Server 3.0 Commerce Edition site resides in the site\Config directory, and the Site.csc file for the manager site resides in the site\Manager\Config directory.

The ppIDictProp parameter contains valid data only if the method returns successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

AdminSite Object

IAdminSite::WriteDefaultProperties

IAdminSite::ReadManagerProperties

IAdminSite::Initialize


IAdminSite::ReadManagerProperties

Use this method to read the properties from the configuration file of the management page (site\Manager\Config\Site.csc) and to return a site dictionary containing these properties.

Definition

HRESULT IAdminSite::ReadManagerProperties(
IDictionary** ppIDict
);

Parameters

ppIDict

[out] The address of a pointer used to return the IDictionary interface of the Dictionary object that contains the properties read from the configuration file of the management page.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The manager site dictionary properties are DefaultConnectionString and ConnectionStringMap. These properties are distinct from the corresponding properties in the main site configuration.

The ppIDict parameter contains valid data only if the method returns successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

AdminSite Object

IAdminSite::WriteManagerProperties

IAdminSite::ReadDefaultProperties


IAdminSite::Reload

Use this method to reset all application and session objects for the Site Server 3.0 Commerce Edition site.

Definition

HRESULT IAdminSite::Reload(
);

Parameters

None.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

After a reload, the next browser request will load the Global.asa file.

See Also

AdminSite Object


IAdminSite::get_Status, put_Status

The Status property is a read/write Boolean that indicates whether or not the Site Server 3.0 Commerce Edition site is open or closed. In addition, the Status property either opens or closes the Site Server 3.0 Commerce Edition site, when the value is set.

Definition

Get method:

HRESULT IAdminSite::get_Status(
VARIANT_BOOL* Status
);

Put method:

HRESULT IAdminSite::put_Status(
VARIANT_BOOL Status
);

Parameters

Status

[in] When putting the property, a VARIANT_BOOL that contains the open/closed status of the site.
[out] When getting the property, the address of a VARIANT_BOOL used to return the open/closed status of the site. A value of True indicates that the site is open. A value of False indicates that the site is closed.

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

This property returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

Changing this property sets a value in the site configuration to the text "Open" or "Closed." When the site is reloaded, this value is read by the Global.asa file into the com_compref_frnc.htm value of the site Dictionary object. Each page in the Site Server 3.0 Commerce Edition site then determines whether or not to redirect the browser by checking the value of the Site.Status property. If the text does not equal "Open," then the browser is redirected to the address specified by the Site.CloseRedirectURL property.

When getting the property, the Status parameter contains valid data only if the property is accessed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

AdminSite Object


IAdminSite::get_Version

The Version property is a read-only integer used to return the version of Site Server 3.0 Commerce Edition in use.

Definition

HRESULT IAdminSite::get_Version(
long* Version
);

Parameters

Version

[out] A pointer to a long used to return the version of Site Server 3.0 Commerce Edition in use.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This property returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The Version parameter contains valid data only if the property is accessed successfully.

See Also

AdminSite Object


IAdminSite::WriteDefaultProperties

Use this method to write the properties from the specified site Dictionary object to the Site.csc file.

Definition

HRESULT IAdminSite::WriteDefaultProperties(
IDictionary* pIDictProp
);

Parameters

pIDictProp

[in] A pointer to the IDictionary interface of the Dictionary object that contains the properties to be written to the Site.csc file.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

See Also

AdminSite Object

IAdminSite::ReadDefaultProperties

IAdminSite::WriteManagerProperties


IAdminSite::WriteManagerProperties

Use this method to write the properties from the specified site Dictionary object to the configuration file of the management page (site\Manager\Config\Site.csc).

Definition

HRESULT IAdminSite::WriteManagerProperties(
IDictionary* pIDictProp
);

Parameters

pIDictProp

[in] A pointer to the IDictionary interface of the Dictionary object that contains the properties to be written to the configuration file of the management page.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The manager site dictionary properties are DefaultConnectionString and ConnectionStringMap. These properties are distinct from the corresponding properties in the main site configuration. This means that the password and user name information required to access site management pages can be different from those used in user pages.

See Also

AdminSite Object

IAdminSite::ReadManagerProperties

IAdminSite::WriteDefaultProperties


AdminWebServer Object

Use this object to enumerate all Web sites on a server, to obtain the properties of those Web sites, and to enumerate all Commerce sites on a Web site.

ProgID: | Commerce.AdminWebServer (Externally creatable)
COM Class Name: | AdminWebServer
COM Interface Name: | IAdminWebServer
Interface ID Constant: | None
Header File: | None
Type Library Name: | Commerce Admin 1.0 Type Library
DLL Name: | MSCSadmin.dll
Threading Model: | Both

In C++, use the IAdminWebServer interface to access the methods of the AdminWebServer object.

The methods of the AdminWebServer object are shown in the following table.

Method | Description
GetCommerceSites | Given a server instance of a Web Site, enumerates all Site Server 3.0 Commerce Edition sites under that Web site.
GetWebSiteProperties | Given a server instance, returns the properties of the site as name/value pairs in a Dictionary object.
GetWebSites | Enumerates all Web sites. Returns an array of numbers representing all Web sites (server instances).

Remarks

Active Server Pages (ASP) scripts that access the Microsoft Internet Information Services (IIS) metabase require administrator privileges on the computer on which IIS is running. When you execute these scripts from a remote computer, you must connect through a secure connection, such as the Microsoft Windows NT Challenge/Response Authentication method. You can create a server or directory for your administrative .asp files and set the directory security authentication method to Windows NT Challenge/Response for the server or directory.

See Also

Configuration Objects


IAdminWebServer::GetCommerceSites

Use this method to enumerate all Commerce Server sites associated with the specified Web site. The method returns an array of numbers that represents all Commerce Server site instances.

This method does not work with Commerce Server 2000 sites. It is included only for backward compatibility with Site Server 3.0 Commerce Edition sites.

Definition

HRESULT IAdminWebServer::GetCommerceSites(
BSTR bstrInstance,
VARIANT* pVarRet
);

Parameters

bstrInstance

[in] A numeric value, expressed as a BSTR, that represents a server instance for a site.

pVarRet

[out] The address of a VARIANT used to return an array of numbers that represent all Commerce Server site instances.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pVarRet parameter contains valid data only if the method returns successfully.

The GetCommerceSites method determines whether a site is a Commerce Server site by examining a reserved key in the metabase.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

AdminWebServer Object


IAdminWebServer::GetWebSiteProperties

Use this method to retrieve, given a server instance, the properties of a site as name/value pairs in a Dictionary object.

Definition

HRESULT IAdminWebServer::GetWebSiteProperties(
BSTR bstrInstance,
IDictionary** ppIDictSiteProperties
);

Parameters

bstrInstance

[in] A numeric value, expressed as a BSTR, representing a server instance for a site.

ppIDictSiteProperties

[out] The address of a pointer used to return the IDictionary interface of the Dictionary object containing the properties of the specified site.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The ppIDictSiteProperties parameter contains valid data only if the method returns successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

AdminWebServer Object


IAdminWebServer::GetWebSites

Use this method to enumerate all Web sites. The method returns an array of numbers that represent the server instance number for each Web site.

Definition

HRESULT IAdminWebServer::GetWebSites(
VARIANT* pvarInstances
);

Parameters

pvarInstances

[out] An address of a VARIANT used to return an array of numbers that represent all server instances.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pvarInstances parameter contains valid data only if the method returns successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

AdminWebServer Object


AppConfig Object

Use this object to retrieve site configuration settings from the site configuration store. Also, use this object to retrieve the names and codes of various countries and regions from the site configuration store.

ProgID: | Commerce.AppConfig (Externally creatable)
COM Class Name: | AppCfg
COM Interface Name: | IAppCfg
Interface ID Constant: | IID_IAppCfg
Header File: | mspu_guids.h
Type Library Name: | Microsoft Commerce 2000 App Helper Type Library
DLL Name: | AppHelper.dll
Threading Model: | Both

In C++, use the IAppCfg interface to access the methods of the AppConfig object.

Because this object is primarily intended for use within ASP script, access from C++ will not be common.

The methods of the AppConfig object are shown in the following table.

Method | Description
DecodeStatusCode | Decodes the specified status code.
GetCountryCodeFromCountryName | Returns the country code for the specified country name.
GetCountryNameFromCountryCode | Returns the country name for the specified country code.
GetCountryNamesList | Returns an alphabetical list of country names.
GetOptionsDictionary | Returns a Dictionary object that maps site configuration keys to site configuration values.
GetRegionCodeFromCountryCodeAndRegionName | Returns the region code for the specified country code and region name.
GetRegionNameFromCountryCodeAndRegionCode | Returns the region name for the specified country code and region code.
GetRegionNamesListFromCountryCode | Returns an alphabetical list of region names for the specified country code.
Initialize | Initializes the AppConfig object.
RefreshCache | Refreshes the AppConfig object cache.

Remarks

This object is usually created once and initialized in the Global.asa file, for performance reasons. An instance of it is stored in the Application object and used on ASP pages as necessary.

The following example illustrates these steps:

Dim oAppConfig
Set oAppConfig = Server.CreateObject("Commerce.AppConfig")
Set Application("MSCSAppCfg") = oAppConfig

Country codes may or may not be the same as ISO Country codes, depending on what values have been added in the Business Desk.

See Also

Configuration Objects

Table of Country Names and Codes


IAppCfg::DecodeStatusCode

Use this method to decode the specified status code.

Definition

HRESULT IAppCfg::DecodeStatusCode(
int iStatusCode,
BSTR* pbstrStatusCode
);

Parameters

iStatusCode

[in] An integer that specifies the status code to be decoded.

pbstrStatusCode

[out, retval] The address of a BSTR used to return the decoded status code. If the specified status code is not in the system, that same status code is returned.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pbstrStatusCode parameter contains valid data only if the method returns successfully.

Status codes are entered in the Commerce Server Business Desk.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

AppConfig Object


IAppCfg::GetCountryCodeFromCountryName

Use this method to get the country code corresponding to the specified country name.

Definition

HRESULT IAppCfg::GetCountryCodeFromCountryName(
BSTR bstrCountryName,
BSTR* pbstrCountryCode
);

Parameters

bstrCountryName

[in] A BSTR that contains the name of the country for which the country code is being requested.

pbstrCountryCode

[out, retval] The address of a BSTR used to return the country code being requested.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pbstrCountryCode parameter contains valid data only if the method returns successfully.

If the country code is not found, the method returns an empty string.

Country codes and country names may be set in Commerce Server Business Desk.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

AppConfig Object

IAppCfg::GetCountryNameFromCountryCode

IAppCfg::GetCountryNamesList

Table of Country Names and Codes


IAppCfg::GetCountryNameFromCountryCode

Use this method to get the country name corresponding to the specified country code.

Definition

HRESULT IAppCfg::GetCountryNameFromCountryCode(
BSTR bstrCountryCode,
BSTR* pbstrCountryName
);

Parameters

bstrCountryCode

[in] A BSTR that contains the code of the country for which the country name is being requested.

pbstrCountryName

[out, retval] The address of a BSTR used to return the requested country name.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pbstrCountryName parameter contains valid data only if the method returns successfully.

If the country name is not found, the method returns the country code specified in the bstrCountryCode parameter.

Country codes and country names may be set in Commerce Server Business Desk.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

AppConfig Object

IAppCfg::GetCountryCodeFromCountryName

IAppCfg::GetCountryNamesList

Table of Country Names and Codes


IAppCfg::GetCountryNamesList

Use this method to get an alphabetical list of the country names that are in the site configuration database.

Definition

HRESULT IAppCfg::GetCountryNamesList(
ISimpleList** pplistCountryNames
);

Parameters

pplistCountryNames

[out, retval] The address of a pointer used to return an ISimpleList interface. Upon successful completion of the method, this list contains an alphabetical list of country names.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pplistCountryNames parameter contains valid data only if the method returns successfully.

Country codes and country names may be set in Commerce Server Business Desk.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

AppConfig Object

IAppCfg::GetCountryCodeFromCountryName

Table of Country Names and Codes


IAppCfg::GetOptionsDictionary

Use this method to retrieve a Dictionary object that contains the site configuration information.

Definition

HRESULT IAppCfg::GetOptionsDictionary(
BSTR bstrUserID,
IDictionary** ppdispOptionsDictionary
);

Parameters

bstrUserID

[in] A BSTR that contains an empty string ("").

ppdispOptionsDictionary

[out, retval] The address of a pointer used to return an IDictionary interface pointer. The associated Dictionary object contains the site configuration information. See the Remarks section for a list of some dictionary keys.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The ppdispOptionsDictionary parameter contains valid data only if the method returns successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Some options dictionary keys, such as i_AuctionOptions, are reserved for future use. The following table lists the names of the keys in the Dictionary object returned by this method that are mapped in the Microsoft Management Console (MMC).

Programmatic Name | MMC Default Config Mapping
i_AddItemRedirectOptions | Add item redirect options
i_AddressBookOptions | Address Book Options
f_AltCurrencyConversionRate | Currency: Alternate currency conversion Rate
i_AltCurrencyLocale | Currency: Alternate currency locale
i_AltCurrencyOptions | Currency: Alternate currency options
i_BaseCurrencyLocale | Currency: Base currency locale
i_BillingOptions | Payment options: Billing options
i_BizTalkOptions | BizTalk Options
i_CookiePathCorrectionOptions | Cookie Path Correction Options
i_CurrencyDisplayOrderOptions | Currency: Currency display order options
i_DelegatedAdminOptions | Delegated admin options
i_FormLoginOptions | Form login options
i_FormLoginTimeOut | AuthManager Auth ticket Timeout
i_HostNameCorrectionOptions | Host Name Correction Options
i_PaymentOptions | Payment options
i_SitePrivacyOptions | Site privacy options
i_SiteRegistrationOptions | Site registration options
i_SiteTicketOptions | Site ticket options
s_AltCurrencySymbol | Currency: Alternate currency symbol
s_BaseCurrencySymbol | Currency: Base currency symbol
s_BizTalkCatalogDocType | BizTalk Catalog Doc Type
s_BizTalkConnString | BizTalk connection String
s_BizTalkOrderDocType | BizTalk PO Doc Type
s_BizTalkSourceQualifierID | BizTalk Source Org Qualifier
s_BizTalkSourceQualifierValue | BizTalk Org Qualifier Value
s_BizTalkSubmittypeQueue | BizTalk Submit type
s_PageEncodingCharset | Page encoding charset
s_SMTPServerName | SMTP server name
s_WeightMeasure | Unit of Measure for Weight

The following table lists keys in the Dictionary object returned by this method that are not mapped in the MMC.

Programmatic Name | Value or Description
i_IsFullTextSearchInstalled | Indicates whether SQL Server has full text search enabled
s_BizDataStoreConnectionString | Profile Service: s_BizDataStoreConnectionString
s_CampaignsConnectionString | Campaigns: connstr_db_Campaigns
s_CatalogConnectionString | Product Catalog: connstr_db_Catalog
s_CommerceProviderConnectionString | Profile Service: s_CommerceProviderConnectionString
s_NonSecureHostname | This value is set in the global.asa file to the non-secure host name of the application.
s_ProfileServiceConnectionString | Profile Service: s_ProfileServiceConnectionString
s_SecureHostname | This value is set in the global.asa file to the secure host name of the application.
s_SiteName | Name of the Site
s_TransactionConfigConnectionString | Transaction Config: connstr_db_TransactionConfig
s_TransactionsConnectionString | Transactions: connstr_db_Transactions

See Also

AppConfig Object


IAppCfg::GetRegionCodeFromCountryCodeAndRegionName

Use this method to get a string that contains the region code for the specified country code and region name.

Definition

HRESULT IAppCfg::GetRegionCodeFromCountryCodeAndRegionName(
BSTR bstrCountryCode,
BSTR bstrRegionName,
BSTR* pbstrRegionCode
);

Parameters

bstrCountryCode

[in] A BSTR that contains the code of the country for which the region code is being requested.

bstrRegionName

[in] A BSTR that contains the name of the region within the specified country for which the region code is being requested.

pbstrRegionCode

[out, retval] The address of a BSTR used to return the requested region code. An empty BSTR indicates that the code was not found.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pbstrRegionCode parameter contains valid data only if the method returns successfully.

This method returns an empty string if the region code was not found.

Country codes, country names, region codes, and region names may be set in Commerce Server Business Desk.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

AppConfig Object

IAppCfg::GetCountryCodeFromCountryName

IAppCfg::GetCountryNamesList

IappCfg::GetRegionNameFromCountryCodeAndRegionCode

IAppCfg::GetRegionNamesListFromCountryCode

Table of Country Names and Codes


IAppCfg::GetRegionNameFromCountryCodeAndRegionCode

Use this method to get the name of the region associated with the specified country code and region code.

Definition

HRESULT IAppCfg::GetRegionNameFromCountryCodeAndRegionCode(
BSTR bstrCountryCode,
BSTR bstrRegionCode,
BSTR* pbstrRegionName
);

Parameters

bstrCountryCode

[in] A BSTR that contains the code of the country for which the region name is being requested.

bstrRegionCode

[in] A BSTR that contains the code of the region within the specified country for which the region name is being requested.

pbstrRegionName

[out, retval] The address of a BSTR used to return the region name. If the region name is not found, the BSTR will contain the region code specified in the bstrRegionCode parameter.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pbstrRegionName parameter contains valid data only if the method returns successfully.

If the region name is not found, this method returns the region code specified in the bstrRegionCode parameter.

Country codes, country names, region codes, and region names may be set in Commerce Server Business Desk.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

AppConfig Object

IAppCfg::GetCountryCodeFromCountryName

IAppCfg::GetCountryNamesList

IAppCfg::GetRegionCodeFromCountryCodeAndRegionName

IAppCfg::GetRegionNamesListFromCountryCode

Table of Country Names and Codes


IAppCfg::GetRegionNamesListFromCountryCode

Use this method to retrieve an alphabetical list of region names associated with a specified country code.

Definition

HRESULT IAppCfg::GetRegionNamesListFromCountryCode(
BSTR bstrCountryCode,
ISimpleList** pplistRegionNames
);

Parameters

bstrCountryCode

[in] A BSTR that contains the code of the country for which a list of region names is being requested.

pplistRegionNames

[out, retval] The address of a pointer used to return an ISimpleList interface pointer. Upon successful completion, the list contains an alphabetical list of region names associated with the specified country code.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pplistRegionNames parameter contains valid data only if the method returns successfully.

Country codes, country names, region codes, and region names may be set in Commerce Server Business Desk.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

AppConfig Object

IAppCfg::GetCountryCodeFromCountryName

IAppCfg::GetCountryNamesList

IAppCfg::GetRegionCodeFromCountryCodeAndRegionName

Table of Country Names and Codes


IAppCfg::Initialize

Use this method to initialize an AppConfig object.

Definition

HRESULT IAppCfg::Initialize(
BSTR bstrSiteName
);

Parameters

bstrSiteName

[in] A BSTR that contains the name of the site with which this AppConfig object should be associated. This name is not case-sensitive.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The AppConfig object must be initialized before any other method on this object can be used. The initialization usually happens only once in Global.asa immediately after the object is created.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

AppConfig Object

IAppCfg::RefreshCache


IAppCfg::RefreshCache

Use this method to refresh the cache associated with the AppConfig object.

Definition

HRESULT IAppCfg::RefreshCache(
);

Parameters

None.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

Users can add and change country and region codes and other values from within Commerce Server Business Desk; the RefreshCache method allows you to programmatically incorporate those changes at any time.

See Also

AppConfig Object

IAppCfg::Initialize


AppFrameWork Object

Use this object to simplify forms processing in Active Server Pages (ASP).

ProgID: | Commerce.AppFrameWork (Externally creatable)
COM Class Name: | AppFrameWork
COM Interface Name: | IAppFrameWork
Interface ID Constant: | None
Header File: | None
Type Library Name: | AspLib 1.0 Type Library
DLL Name: | asplib.dll
Threading Model: | Both

In C++, use the IAppFrameWork interface to access the methods of the AppFrameWork object.

Because this object is primarily intended for use within ASP script, access from C++ will not be common.

The methods of the AppFrameWork object are shown in the following table.

Method | Description
Option | Generates an option tag on a page.
RequestDate | Retrieves a value from a URL query string or form post variable and converts it to a Date value (Date Variant).
RequestDateTime | Retrieves a value from a URL query string or form post variable and converts it to a DateTime value (Date Variant).
RequestFloat | Retrieves a value from a URL query string or form post variable and converts it to a floating-point value.
RequestMoneyAsNumber | Retrieves a value from a URL query string or form post variable and converts it as money, based on the specified locale.
RequestNumber | Retrieves a value from a URL query string or form post variable and converts it to a number.
RequestString | Retrieves a value from a URL query string or form post variable and performs string processing on it.
RequestTime | Retrieves a value from a URL query string or form post variable and converts it to a Time value (Date Variant).
VerifyWith | Generates hidden input fields that contain verification values.
VirtualDirectory | Returns the name of the virtual directory for the site.

Remarks

The AppFrameWork object methods fall mainly into the following categories:

  • Formatting. The Option method makes it possible for you to easily format HTML page items, and where applicable, to determine HTML item values based upon a run time evaluation of other variables used in your page.

  • Validation. These methods begin with Request, and are used to retrieve values from a URL query string, convert the values to given data types based on a locale value, and validate these values against a specified range.

Before you create this object, you must create the Commerce.DataFunctions object in Application scope.

See Also

Display Objects


IAppFrameWork::Option

Use this method to generate an OPTION item in an HTML form selection list with the value and selection state that you specify.

Definition

HRESULT IAppFrameWork::Option(
VARIANT vtVal1,
VARIANT vtVal2,
BSTR* pbstrRet
);

Parameters

vtVal1

[in] A VARIANT that contains the value of the option in the selection list.

vtVal2

[in] A VARIANT that contains a value that indicates whether the list option is the selected option. If the vtVal2 parameter is equal to the vtVal1 parameter, then the HTML keyword SELECTED is inserted in the definition of the option list.

pbstrRet

[out, retval] A pointer to a BSTR used to return the OPTION item.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pbstrRet parameter points to valid data only if the method completed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

AppFrameWork Object


IAppFrameWork::RequestDate

Use this method to retrieve a value from a URL query string or form post variable and convert it to a Date value (Date Variant), based on the specified or default locale.

Definition

HRESULT IAppFrameWork::RequestDate(
BSTR bstrName,
VARIANT vtDefault,
VARIANT vtMin,
VARIANT vtMax,
VARIANT vtLocale,
VARIANT* pvtRet
);

Parameters

bstrName

[in] A BSTR that contains the name of the URL query string or form post variable to retrieve.

vtDefault

[in, optional] A VARIANT that contains the date value to return if the requested URL query string or form post variable does not exist or contains no value. The default cannot contain DateTime and Time values.

vtMin

[in, optional] A VARIANT that contains a date value that specifies the low end of the range against which to validate the value of the bstrName parameter. If the variant is of type VT_NULL, the vtMin parameter value is not considered in the validation process. If the converted value is less than vtMin, then NULL is returned.

vtMax

[in, optional] A VARIANT that contains a date value that specifies the high end of the range against which to validate the value of the bstrName parameter. If the variant is of type VT_NULL, the vtMax parameter value is not considered in the validation process. If the converted value is greater than vtMax, then NULL is returned.

vtLocale

[in, optional] A VARIANT that contains a number that specifies the locale to use to convert the date. If this value is not specified, the RequestDate method uses the value of the Locale property of the DataFunctions object.

pvtRet

[out, retval] A pointer to a VARIANT used to return the processed date value. If any validation fails, the return value will be NULL.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pvtRet parameter points to valid data only if the method completed successfully. If any validation fails, the pvtRet parameter will be NULL.

This method converts the specified String based on the locale specified in the vtLocale parameter if the vtLocale parameter is specified; otherwise it uses the default locale found in the DataFunctions object. It validates the result of the conversion against the vtMin and vtMax parameters, if they are specified. If the validation fails this method returns NULL.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

AppFrameWork Object

IDataFunctions_4_0::get_Locale, put_Locale

IAppFrameWork.RequestDateTime

IDataFunctions_4_0::ConvertDateString

IDataFunctions_4_0::Date


IAppFrameWork::RequestDateTime

Use this method to retrieve a value from a URL query string or form post variable and convert it to a DateTime value (Date Variant), based on the specified or default locale.

Definition

HRESULT IAppFrameWork::RequestDateTime(
BSTR bstrName,
VARIANT vtDefault,
VARIANT vtMin,
VARIANT vtMax,
VARIANT vtLocale,
VARIANT* pvtRet
);

Parameters

bstrName

[in] A BSTR that contains the name of the URL query string or form post variable to retrieve.

vtDefault

[in, optional] A VARIANT that contains the value to return if the requested URL query string or form post variable does not exist or contains no value. If this parameter is not supplied, the method returns NULL. The default cannot contain Time values.

vtMin

[in, optional] A VARIANT that contains a DateTime value that specifies the low end of the range against which to validate the value of the bstrName parameter. If the variant is of type VT_NULL, the vtMin parameter value is not considered in the validation process. If the converted value is less than vtMin, then NULL is returned.

vtMax

[in, optional] A VARIANT that contains a DateTime value that specifies the high end of the range against which to validate the value of the bstrName parameter. If the variant is of type VT_NULL, the vtMax parameter value is not considered in the validation process.If the converted value is greater than vtMax, then NULL is returned.

vtLocale

[in, optional] A VARIANT that contains the number that identifies the locale to be used to convert the date/time string. If this parameter is not specified, the RequestDateTime method uses the value of the Locale property of the DataFunctions object.

pvtRet

[out, retval] A pointer to a VARIANT used to return the DateTime value. If any validation fails, the return value will be NULL.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pvtRet parameter points to valid data only if the method completed successfully. If any validation fails, the pvtRet parameter will be NULL.

This method converts the specified String based on the locale specified in the vtLocale parameter if the vtLocale parameter is specified; otherwise it uses the default locale found in the DataFunctions object. It validates the result of the conversion against the vtMin and vtMax parameters, if they are specified. If the validation fails this method returns NULL.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

AppFrameWork Object

IDataFunctions_4_0::get_Locale, put_Locale

IAppFrameWork::RequestDate

IDataFunctions_4_0::ConvertDateTimeString

IAppFrameWork::RequestTime


IAppFrameWork::RequestFloat

Use this method to retrieve a value from a URL query string or form post variable and convert it to a floating-point value, based on the specified or default locale.

Optionally, the RequestFloat method also checks the converted number against the specified range.

Definition

HRESULT IAppFrameWork::RequestFloat(
BSTR bstrName,
VARIANT vtDefault,
VARIANT vtMin,
VARIANT vtMax,
VARIANT vtLocale,
VARIANT* pvtRet
);

Parameters

bstrName

[in] A BSTR that contains the name of the URL query string or form post variable to retrieve.

vtDefault

[in, optional] A VARIANT that contains the value to return if the requested URL query string or form post variable is not present or contains no value. If this parameter is not supplied, the method returns NULL.

vtMin

[in, optional] A VARIANT that contains the number that specifies the low end of the range of values against which to validate the converted value. If the variant is of type VT_NULL, the vtMin parameter value is not considered in the validation process. If the converted value is less than vtMin, then NULL is returned.

vtMax

[in, optional] A VARIANT that contains the number that specifies the high end of the range of values against which to validate the converted value. If the variant is of type VT_NULL, the vtMax parameter value is not considered in the validation process. If the converted value is greater than vtMax, then NULL is returned.

vtLocale

[in, optional] A VARIANT that contains the number that identifies the locale to use to convert the value. If this value is not specified, the RequestFloat method uses the value of the Locale property of the DataFunctions object.

pvtRet

[out, retval] A pointer to a VARIANT used to return the floating-point value. If any validation fails, the return value will be NULL.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pvtRet parameter points to valid data only if the method completes successfully. If any validation fails, the pvtRet parameter will be NULL.

This method converts the specified String based on the locale specified in the vtLocale parameter if the vtLocale parameter is specified; otherwise it uses the default locale found in the DataFunctions object. It validates the result of the conversion against the vtMin and vtMax parameters, if they are specified. If the validation fails this method returns NULL.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

AppFrameWork Object

IDataFunctions_4_0::get_Locale, put_Locale

IAppFrameWork::RequestNumber

IDataFunctions_4_0::ConvertFloatString

IDataFunctions_4_0::Float

IDataFunctions_4_0::ValidateFloat


IAppFrameWork::RequestMoneyAsNumber

Use this method to retrieve a value from a URL query string or form post variable and convert it as money, based on the specified locale.

Definition

HRESULT IAppFrameWork::RequestMoneyAsNumber(
BSTR bstrName,
VARIANT vtDefault,
VARIANT vtMin,
VARIANT vtMax,
VARIANT vtLocale,
VARIANT* pvtRet
);

Parameters

bstrName

[in] A BSTR that contains the name of the URL query string or form post variable to retrieve.

vtDefault

[in, optional] A VARIANT that contains the value to return if the requested URL query string or form post variable is not present or contains no value. If this parameter is not supplied, the method returns NULL. If the default value is a string value, it will be converted into the base monetary value, otherwise, it is assumed that the value is in base monetary units.

vtMin

[in, optional] A VARIANT that contains the monetary value that specifies the low end of the range against which to validate the converted value. A value in base monetary units is expected for the vtMin parameter. If the converted value is less than vtMin, then NULL is returned.

vtMax

[in, optional] A VARIANT that contains the monetary value that specifies the high end of the range against which to validate the converted value. If the variant is of type VT_NULL, the vtMax parameter value is not considered in the validation process. A value in base monetary units is expected for the vtMax parameter. If the converted value is greater than vtMax, then NULL is returned.

vtLocale

[in, optional] A VARIANT that contains the number that specifies the locale to use to convert the bstrName parameter. If this parameter is not used, the RequestMoneyAsNumber method uses the value of the Locale property of the DataFunctions object.

pvtRet

[out, retval] A pointer to a VARIANT used to return the number in the base monetary units of the specified or default locale. If any validation fails, the return value will be NULL.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pvtRet parameter points to valid data only if the method completed successfully. If any validation fails, the pvtRet parameter will be NULL.

If this method completes successfully it returns a number that represents the value of the specified string in the base monetary unit of the specified local. Thus, given a value in US dollars, it returns the number of cents in that value.

This method converts the specified String based on the locale specified in the vtLocale parameter if the vtLocale parameter is specified; otherwise it uses the default locale found in the DataFunctions object. It validates the result of the conversion against the vtMin and vtMax parameters, if they are specified. If the validation fails this method returns NULL.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

AppFrameWork Object

IDataFunctions_4_0::get_Locale, put_Locale

IDataFunctions_4_0::ConvertMoneyStringToNumber

IDataFunctions_4_0::Money

IAppFrameWork::RequestFloat

IAppFrameWork::RequestNumber


IAppFrameWork::RequestNumber

Use this method to retrieve a value from a URL query string or form post variable and convert it to a number based on the specified or default locale.

Optionally, the RequestNumber method checks the converted number against the specified range and validates it based on the specified locale.

Definition

HRESULT IAppFrameWork::RequestNumber(
BSTR bstrName,
VARIANT vtDefault,
VARIANT vtMin,
VARIANT vtMax,
VARIANT vtLocale,
VARIANT* pvtRet
);

Parameters

bstrName

[in] A BSTR that contains the name of the URL query string or form post variable to retrieve.

vtDefault

[in, optional] A VARIANT that contains the value to return if the requested URL query string or form post variable is not present or contains no value. If this parameter is not supplied, the method returns NULL.

vtMin

[in, optional] A VARIANT that contains the number value that specifies the low end of the range against which to validate the converted value. If the converted value is less than vtMin, then NULL is returned. If the variant is of type VT_NULL, the vtMin parameter value is not considered in the validation process.

vtMax

[in, optional] A VARIANT that contains the number value that specifies the high end of the range against which to validate the converted value. If the converted value is greater than vtMax, then NULL is returned. If the variant is of type VT_NULL, the vtMax parameter value is not considered in the validation process.

vtLocale

[in, optional] A VARIANT that contains the number that specifies the locale to use to convert the bstrName parameter. If this parameter is not used, the RequestNumber method uses the value of the Locale property of the DataFunctions object.

pvtRet

[out, retval] A pointer to a VARIANT used to return the converted number. If any validation fails, the return value will be NULL.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pvtRet parameter points to valid data only if the method completed successfully. If any validation fails, the pvtRet parameter will be NULL.

This method converts the specified String based on the locale specified in the vtLocale parameter if the vtLocale parameter is specified; otherwise it uses the default locale found in the DataFunctions object. It validates the result of the conversion against the vtMin and vtMax parameters, if they are specified. If the validation fails this method returns NULL.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

AppFrameWork Object

IDataFunctions_4_0::get_Locale, put_Locale

IAppFrameWork::RequestFloat

IDataFunctions_4_0::ConvertNumberString

IDataFunctions_4_0::Number

IDataFunctions_4_0::ValidateNumber


IAppFrameWork::RequestString

Use this method to retrieve a value from a URL query string or form post variable and perform string processing on it.

Definition

HRESULT IAppFrameWork::RequestString(
BSTR bstrName,
VARIANT vtDefault,
VARIANT vtMin,
VARIANT vtMax,
VARIANT vtStripWhite,
VARIANT vtStripReturn,
VARIANT vtCase,
VARIANT vtLocale,
VARIANT* pvtRet
);

Parameters

bstrName

[in] A BSTR that contains the name of the URL query string or form post variable to retrieve.

vtDefault

[in, optional] A VARIANT that contains the string to return if the specified URL query string or form post variable does not exist or contains no value. If this parameter is not supplied, the method returns NULL.

vtMin

[in, optional] A VARIANT that contains the number that indicates the minimum length against which the length of the bstrName parameter must be validated. If the variant is of type vtMissing, the vtMin parameter value is not considered in the validation process. If this value is invalid or length of the bstrName/vtDefault parameters is not in range, the method returns NULL.

vtMax

[in, optional] A VARIANT that contains the number that indicates the maximum length against which the length of the bstrName parameter must be validated. If the variant is of type vtMissing, the vtMax parameter value is not considered in the validation process. If this value is invalid or length of the bstrName/vtDefault parameters is not in range, the method returns NULL.

vtStripWhite

[in, optional] A VARIANT that contains a Boolean value that indicates whether leading and trailing white spaces should be stripped from the string. The default value is True.

vtStripReturn

[in, optional] A VARIANT that contains a Boolean value that indicates whether carriage returns should be stripped from the string. The default value is True.

vtCase

[in, optional] A VARIANT that contains the number that indicates the case to which the string should be converted. The default value is zero (0), which results in no modification to the case of the string. If the vtCase parameter is one (1), the string is converted to uppercase. If the vtCase parameter is two (2), the string is converted to lowercase.

vtLocale

[in, optional] A VARIANT that contains the number that specifies the locale to be used as the basis of the conversion. If this value is not specified, the RequestString method uses the value of the Locale property of the DataFunctions object.

pvtRet

[out, retval] A pointer to a VARIANT used to return the processed string.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pvtRet parameter points to valid data only if the method completed successfully.

This method can optionally perform several types of string processing. It can trim leading and trailing white space (space and tab characters) from the string. It can remove carriage returns from the string. It can convert the string to upper- or lowercase.

This method converts the specified String based on the locale specified in the vtLocale parameter if the vtLocale parameter is specified; otherwise it uses the default locale found in the DataFunctions object. It validates the result of the conversion against the vtMin and vtMax parameters, if they are specified.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

AppFrameWork Object

IDataFunctions_4_0::get_Locale, put_Locale


IAppFrameWork::RequestTime

Use this method to retrieve a value from a URL query string or form post variable and convert the string to a Date Variant, based on the specified or default locale.

Definition

HRESULT IAppFrameWork::RequestTime(
BSTR bstrName,
VARIANT vtDefault,
VARIANT vtMin,
VARIANT vtMax,
VARIANT vtLocale,
VARIANT* pvtRet
);

Parameters

bstrName

[in] A BSTR that contains the name of the URL query string or form post variable to retrieve.

vtDefault

[in, optional] A VARIANT that contains the string to return if the specified URL query string or form post variable does not exist or contains no value. If this parameter is not supplied, the method returns NULL. The default cannot contain DateTime or Date values.

vtMin

[in, optional] A VARIANT that contains the time value that specifies the low end of the range against which to validate the bstrName parameter. If the VARIANT is of type vtMissing, the vtMin parameter value is not considered in the validation process. If the converted value is less than vtMin, then NULL is returned.

vtMax

[in, optional] A VARIANT that contains the time value that specifies the high end of the range against which to validate the bstrName parameter. If the variant is of type vtMissing, the vtMax parameter value is not considered in the validation process. If the converted value is greater than vtMax, then NULL is returned.

vtLocale

[in, optional] A VARIANT that contains the number that specifies the locale to use to convert the DateTime value. If this value is not specified, the RequestTime method uses the value of the Locale property of the DataFunctions object.

pvtRet

[out, retval] A pointer to a VARIANT used to return the date. If any validation fails, the value will be set to NULL.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pvtRet parameter points to valid data only if the method completed successfully. If any validation fails, the pvtRet parameter will be NULL.

This method converts the specified String based on the locale specified in the vtLocale parameter if the vtLocale parameter is specified; otherwise it uses the default locale found in the DataFunctions object. It validates the result of the conversion against the vtMin and vtMax parameters, if they are specified. If the validation fails this method returns NULL.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

AppFrameWork Object

IDataFunctions_4_0::get_Locale, put_Locale

IDataFunctions_4_0::ConvertTimeStringf

IAppFrameWork::RequestDate


IAppFrameWork::VerifyWith

Use this method to generate hidden input fields that contain verification values.

Definition

HRESULT IAppFrameWork::VerifyWith(
IDispatch* pdispOrder,
SAFEARRAY(VARIANT) pParams,
BSTR* pbstrRet
);

Parameters

pdispOrder

[in] A pointer to the IDispatch interface that can be used to retrieve the OrderForm object that contains the fields to verify.

pParams

[in] A SAFEARRAY that contains a list of field names to verify in the supplied OrderForm object.

pvtRet

[out, retval] A pointer to a VARIANT used to return the HTML tags.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pvtRet parameter points to valid data only if the method completed successfully.

Use this method to output HTML tags in the form <INPUT TYPE="HIDDEN"> in an HTML form. These hidden fields contain specified values from the OrderForm object to be used to verify that an order has not been altered between presentation of the OrderForm object and final purchase.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

AppFrameWork Object

OrderForm Object


IAppFrameWork::VirtualDirectory

Use this method to return the name of the virtual directory for the site.

Definition

HRESULT IAppFrameWork::VirtualDirectory(
BSTR* pbstrRet
);

Parameters

pbstrRet

[out, retval] A pointer to a BSTR used to return the site virtual directory.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pbstrRet parameter points to valid data only if the method completed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

AppFrameWork Object

StandardSManager Object


AsyncRpt Object

Use this object to render (display) or export a static report asynchronously.

ProgID: | Commerce.AsyncRpt (Externally creatable)
COM Class Name: | AsyncRpt
COM Interface Name: | IAsyncRpt
Interface ID Constant: | IID_IAsyncRpt
Header File: | AsyncReport.h
Type Library Name: | Microsoft Commerce 2000 Async Report Manager Type Library
DLL Name: | AsyncReport.dll
Threading Model: | Both

In C++, use the IAsyncRpt interface to access the methods of the AsyncRpt object.

Because this object is primarily intended for use within ASP script, access from C++ will not be common.

The methods of the AsyncRpt object are shown in the following table.

Method | Description
RunReport | Runs or exports the report.

Remarks

The AsyncRpt object renders or exports reports asynchronously.

The ReportRender object renders or exports reports synchronously.

The AsyncRpt object calls the ReportRender object passing it a string containing the rendering parameters. For more information about the rendering process, see ReportRender Object.

See Also

Analysis/Reporting Schema

Analysis/Reporting XML Structures

Creating Custom Reports

ListManager Object

ReportRenderer Object

Running Reports


IAsyncRpt::RunReport

Use this method to initialize the AsyncRpt object and to render or export a static report asynchronously.

Definition

HRESULT IAsyncRpt::RunReport(
BSTR bstrRepParam
);

Parameters

bstrRepParam

[in, out] A BSTR used to supply parameters to the AsyncRpt object.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and E_FAIL (0x80004005) to indicate failure. For more information about standard COM errors, see Standard COM Errors.

Remarks

The AsyncRpt object calls the ReportRender object, passing it the bstrRepParam parameter.

The bstrRepParam parameter is identical to the sParamString parameter of the Init method of the ReportRender object. For more information, see ReportRender Object.

See Also

AsyncRpt Object


Auction Object

Use this object to provide auction capabilities to a site. This object enables a site to auction products, accept bids, and determine winners, using rules ranging from simple to sophisticated. Users can set reserve prices, minimum bids, start and end dates, bid increments, and resolve bid conflicts. Users can also notify auction participants of important news via DHTML, HTML, or e-mail at any interval.

ProgID: | Commerce.Auction (Externally creatable)
COM Class Name: | Auction
COM Interface Name: | _Auction
Interface ID Constant: | None
Header File: | None
Type Library Name: | Commerce Server 4.0 Auction Component
DLL Name: | auction.dll
Threading Model: | Apartment

In C++, use the _Auction interface to access the properties and methods of the Auction object.

Because this object is primarily intended for use within ASP script, access from C++ will not be common.

The properties of the Auction object are shown in the following table.

Property | Type | Description
AuctionID | BSTR | Stores the AuctionID GUID. This property is read-only.
dtAMT | DATE | Stores the date/time stamp used by the auction engine. This property is read/write.
objMessageManager | IDispatch | Stores the MessageManager object used to generate error messages. This property is read/write.
szBidOrderBy | BSTR | Stores the sort string used to resolve ties. This property is read/write.
szBidTableName | BSTR | Stores the name of the Bid table in the database. This property is read/write.
szDSN | BSTR | Stores the connection string for the database. This property is read/write.
szItemTableName | BSTR | Stores the name of the Item table in the database. This property is read/write.
szLanguage | BSTR | Stores the language used in by the MessageManager object when generating error messages. This property is read/write.

The methods of the Auction object are shown in the following table.

Method | Description
AuctionAddBid | Adds or updates a bid on an auction.
AuctionAddItem | Adds a new auction item to the Auction database.
AuctionBidNormalize | Normalizes a bid to the bid increment amount.
AuctionDeleteBid | Deletes a bid in an auction.
AuctionDeleteBids | Deletes all bids in a particular auction.
AuctionDeleteItem | Deletes an item and all bids on the item in a particular auction.
AuctionGetBid | Returns a rowset containing a bid from a specific user for a specific auction item.
AuctionGetBids | Returns a rowset containing all bids for an auction item.
AuctionGetItem | Returns a rowset for the item up for auction.
AuctionGetStatus | Returns a Dictionary object containing rowsets for the item up for auction.
AuctionInit | Initializes the Auction object.
AuctionRandomBids | Adds random bids to an auction to aid testing.
AuctionResolve | Resolves the auction based on the current settings and rules.
AuctionUpdateItem | Updates an auction item in the Auction database.

Remarks

The Auction object depends on the presence of the Item and Bid tables, stored in the site database, and a MessageManager object to hold the error messages. The tables must be created before using the Auction object for the first time. The MessageManager object must be properly initialized for the Auction object to pass error messages back to the user.


_Auction::AuctionAddBid

Use this method to add or update a bid on an item. The bid is validated according to all the current rules for the auction.

Definition

HRESULT _Auction::AuctionAddBid(
BSTR szAuctionId,
BSTR szShopperId,
BSTR szBidName,
BSTR szEmail,
CURRENCY cyBidPrice,
long nDesired,
VARIANT_BOOL fTakeLess,
CURRENCY cyMinimumBid,
IDispatch* objErrorList,
VARIANT_BOOL bResolve,
long* plNumErrors
);

Parameters

szAuctionId

[in] A BSTR that contains the unique auction ID.

szShopperId

[in] A BSTR that contains the unique ID of the bidder.

szBidName

[in] A BSTR that contains the name of the bidder.

szEmail

[in] A BSTR that contains the email address of the bidder.

cyBidPrice

[in] A CURRENCY that contains the bid amount.

nDesired

[in] A long that contains the number of wanted items.

fTakeLess

[in] A VARIANT_BOOL that indicates whether the bidder will take less than the wanted number of items. A value of True indicates the bidder will take less. A value of False indicates the bidder will not accept less than the wanted number of items.

cyMinimumBid

[in] A CURRENCY that contains the minimum bid.

objErrorList

[in] A pointer to the IDispatch interface of a SimpleList object that contains a list of errors generated by the MessageManager object.

bResolve

[in, optional, defaultvalue (-1)] A VARIANT_BOOL that indicates whether to call the AuctionResolve method. The default value of True causes the method to be called with the bOptimize parameter of the method set to True. A value of False causes the Auction object to skip the automatic call to the AuctionResolve method.

plNumErrors

[out, retval] A pointer to a long used to return the number of error strings written to the objErrorList object.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Auction Object


_Auction::AuctionAddItem

Use this method to add a new item to the auction system.

Definition

HRESULT _Auction::AuctionAddItem(
BSTR szSKU,
CURRENCY cyReservePrice,
long nAvailable,
CURRENCY cyBidIncrement,
long nAuctionType,
CURRENCY cyMinimumBid,
VARIANT_BOOL fSealedBid,
VARIANT_BOOL fSealedInventory,
VARIANT_BOOL fActive,
DATE dtStartDate,
DATE dtEndDate,
long nAutoCloseSeconds,
IDispatch* objErrorList,
long* plNumErrors
);

Parameters

szSKU

[in] A BSTR that contains the unique ID for the item.

cyReservePrice

[in] A CURRENCY that contains the minimum price that the seller is willing to sell the item for. The reserve price must be greater than the minimum bid.

nAvailable

[in] A long that contains the number of items for sale.

cyBidIncrement

[in] A CURRENCY that contains the amount a bid must be raised in order to bid on the item.

nAuctionType

[in] A long that contains the auction type. For more information, see the table in the Remarks section.

cyMinimumBid

[in] A CURRENCY that contains the minimum opening bid.

fSealedBid

[in] A VARIANT_BOOL that indicates whether to check a bid against the minimum bid. A value of True skips the minimum bid check.

fSealedInventory

[in] A VARIANT_BOOL that indicates whether to check the wanted number of items in a bid against the number of items available for sale. A value of False indicates to check the items. A value of True skips the check (the fTakeLess parameter in the bid is ignored).

fActive

[in] A VARIANT_BOOL that indicates whether the auction is active. A value of True indicates an active auction. A value of False suspends bidding on the auction.

dtStartDate

[in] A DATE that determines when bids will be accepted on the item.

dtEndDate

[in] A DATE that determines when the auction is closed and the items can be purchased.

nAutoCloseSeconds

[in] A long that indicates the number of seconds to wait after the last bid is received to close the auction. This can close an auction before the end date. A value of zero (0) indicates to ignore the time of the last bid and close the auction on the end date.

objErrorList

[in] A pointer to the IDispatch interface that contains the error list.

plNumErrors

[out, retval] A pointer to a long used to return the number of error strings written to the objErrorList object.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The auction type controls the method used to determine the winning bidder and the amount the winning bidder must pay. The following table describes the available auction types.

Auction Type | Value | Description | Example
Winning Price | 0 | Winning bidders receive the item they bid on for the amount bid. If there is more than one item, winning bidders receive the number requested at the amount they bid. | Two items are at auction. Bidder A bids $10.00, Bidder B bids $5.00, and Bidder C bids $3.00, and each bidder requests one item. Bidder A receives one item for $10.00 and Bidder B receives one item for $5.00. However, if Bidder A requested two items at $10.00 each, both items would be awarded to Bidder A.
Clear Price | 1 | Winning bidders receive the item they bid on for the lowest winning bid. | Same conditions as Winning Price auction type example. Bidder A and Bidder B each receive one item for $5.00.
Second Price | 2 | Winning bidders pay the lowest of the following: The highest losing bid plus the bid increment, the lowest winning bid, or the reserve price, assuming the number of bids above the reserve price is less than the number of available items. | Same conditions as Winning Price auction type example with a bid increment of $0.50. Bidder A and Bidder B each receive one item for $3.50.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Auction Object


_Auction::AuctionBidNormalize

Use this method to normalize a bid to a whole multiple of the bid increment.

Definition

HRESULT _Auction::AuctionBidNormalize(
CURRENCY cyBidAmount,
CURRENCY cyBidIncrement,
CURRENCY cyMinimumBid,
CURRENCY* cyBidNormal
);

Parameters

cyBidAmount

[in] A CURRENCY that contains the bid amount.

cyBidIncrement

[in] A CURRENCY that contains the bid increment.

cyMinimumBid

[in] A CURRENCY that contains the minimum bid allowed.

cyBidNormal

[out, retval] A pointer to a CURRENCY used to return the normalized bid.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Auction Object


_Auction::AuctionDeleteBid

Use this method to deletes a bid placed on an item in an auction.

Definition

HRESULT _Auction::AuctionDeleteBid(
BSTR szAuctionId,
BSTR szShopperId,
VARIANT_BOOL bResolve,
VARIANT* unnamed parameter
);

Parameters

szAuctionId

[in] A BSTR that contains the unique auction ID.

szShopperId

[in] A BSTR that contains the unique ID of the bidder.

bResolve

[in, optional, defaultvalue (-1)] A VARIANT_BOOL that indicates whether to call the AuctionResolve method. The default value of True causes the method to be called with the bOptimize parameter of the method set to True. A value of False causes the Auction object to skip the automatic call to the AuctionResolve method.

unnamed parameter

[out, retval] Reserved for future use.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Auction Object


_Auction::AuctionDeleteBids

Use this method to delete all bids on an item made in an auction. The item remains in the auction database and new bids can be accepted.

Definition

HRESULT _Auction::AuctionDeleteBids(
BSTR szAuctionId,
VARIANT_BOOL bResolve,
VARIANT* unnamed parameter
);

Parameters

szAuctionId

[in] A BSTR that contains the unique auction ID.

bResolve

[in, optional, defaultvalue (-1)] A VARIANT_BOOL that indicates whether to call the AuctionResolve method. The default value of True causes the method to be called with the bOptimize parameter of the method set to True. A value of False causes the Auction object to skip the automatic call to the AuctionResolve method.

unnamed parameter

[out, retval] Reserved for future use.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Auction Object


_Auction::AuctionDeleteItem

Use this method to delete an item and all bids for the item from the auction database.

Definition

HRESULT _Auction::AuctionDeleteItem(
BSTR szAuctionId,
VARIANT* unnamed parameter
);

Parameters

szAuctionId

[in] A BSTR that contains the unique auction ID.

unnamed parameter

[out, retval] Reserved for future use.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Auction Object


_Auction::AuctionGetBid

Use this method to retrieve a bid from a specific bidder for a specific auction item.

Definition

HRESULT _Auction::AuctionGetBid(
BSTR szShopperId,
BSTR szAuctionId,
IDispatch** pprsBid
);

Parameters

szShopperId

[in] A BSTR that contains the unique ID of the bidder.

szAuctionId

[in] A BSTR that contains the unique auction ID.

pprsBid

[out, retval] The address of a pointer to the IDispatch interface of an ADODB.Recordset object used to return the specified bid.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Auction Object


_Auction::AuctionGetBids

Use this method to retrieve all the bids for the specified auction item.

Definition

HRESULT _Auction::AuctionGetBids(
BSTR szAuctionId,
DATE dtSinceDate,
IDispatch** rsBids
);

Parameters

szAuctionId

[in] A BSTR that contains the auction ID.

dtSinceDate

[in, optional, defaultvalue (12:00:00 AM)] A DATE that specifies to return only those bids whose status have changed since the indicated date. Status changes are due to bid updates or calculated field updates. A value of NULL indicates to return all bids.

rsBids

[out, retval] The address of a pointer to the IDispatch interface of the ADODB.Recordset object used to return the specified bids.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Auction Object


_Auction::AuctionGetItem

Use this method to retrieve an item up for auction.

Definition

HRESULT _Auction::AuctionGetItem(
BSTR szAuctionId,
IDispatch** rsItem
);

Parameters

szAuctionId

[in] A BSTR that contains the unique auction ID.

rsItem

[out, retval] The address of a pointer to the IDispatch interface of the ADODB.Recordset object used to return the specified item.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Auction Object


_Auction::AuctionGetStatus

Use this method to retrieve a Dictionary object containing information for the item up for auction and the bids on the item.

Definition

HRESULT _Auction::AuctionGetStatus(
BSTR szAuctionId,
IDispatch** dictStatus
);

Parameters

szAuctionId

[in] A BSTR that contains the unique auction ID.

dictStatus

[out, retval] The address of a pointer to the IDispatch interface of a Dictionary object used to return the specified item along with the bids on the item.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The Dictonary object contains two Recordset objects, rsAuctionItem and rsAuctionBids.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Auction Object


_Auction::get_AuctionID

The AuctionID property is a read-only String that contains a GUID that uniquely identifies the Auction object.

Definition

HRESULT _Auction::get_AuctionID(
BSTR* AuctionID
);

Parameters

AuctionID

[out, retval] A BSTR used to return the auction ID, a GUID.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Auction Object


_Auction::AuctionInit

Use this method to initialize the Auction object.

Definition

HRESULT _Auction::AuctionInit(
BSTR szDSN,
BSTR szItemTableName,
BSTR szBidTableName,
BSTR szBidOrderBy,
IDispatch* objMessageManager,
BSTR szLanguage,
DATE dtAMT,
VARIANT* unnamed parameter
);

Parameters

szDSN

[in] A BSTR that contains the connection string to the database containing the Bid and Item tables.

szItemTableName

[in] A BSTR that contains the Item table name.

szBidTableName

[in] A BSTR that contains the Bid table name.

szBidOrderBy

[in] A BSTR that contains the default bid sort order (SQL ORDER BY clause).

objMessageManager

[in] A pointer to the IDispatch interface of a MessageManager object.

szLanguage

[in] A BSTR that contains the language used by the MessageManager object.

dtAMT

[in] A DATE that contains a timestamp.

unnamed parameter

[out, retval] Reserved for future use.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Auction Object


_Auction::AuctionRandomBids

Use this method to enter random bids into an auction for testing or demonstration purposes.

Definition

HRESULT _Auction::AuctionRandomBids(
BSTR szAuctionId,
VARIANT_BOOL fDelete,
long nNumberBids,
VARIANT* unnamed parameter
);

Parameters

szAuctionId

[in] A BSTR that contains the unique auction ID.

fDelete

[in] A VARIANT_BOOL that indicates whether to delete previous random bids before adding the new bids. A value of True specifies to delete the bids. A value of False specifies to save the bids.

nNumberBids

[in] A long that contains the number of random bids to add.

unnamed parameter

[out, retval] Reserved for future use.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

Random bids are entered under the bidder name "Random." The bids are at least the minimum bid and ask for a number of items between one and the number available.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Auction Object


_Auction::AuctionResolve

Use this method to run the auction engine and determine the status of the auction. It updates computed values in both the Item and Bid tables.

Definition

HRESULT _Auction::AuctionResolve(
BSTR szAuctionId,
VARIANT_BOOL bOptimize,
VARIANT* unnamed parameter
);

Parameters

szAuctionId

[in] A BSTR that contains the unique auction ID.

bOptimize

[in, optional, defaultvalue (0)] A VARIANT_BOOL that determines when to stop searching for a winning bid. The default value of True indicates to cease checking for winning bids once a winner has been selected. A value of False indicates to search all records in the database in order to look for winning bids.

unnamed parameter

[out, retval] Reserved for future use.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Auction Object


_Auction::AuctionUpdateItem

Use this method to update an existing item in the auction system.

Definition

HRESULT _Auction::AuctionUpdateItem(
BSTR szAuctionId,
BSTR szSKU,
CURRENCY cyReservePrice,
long nAvailable,
CURRENCY cyBidIncrement,
long nAuctionType,
CURRENCY cyMinimumBid,
VARIANT_BOOL fSealedBid,
VARIANT_BOOL fSealedInventory,
VARIANT_BOOL fActive,
DATE dtStartDate,
DATE dtEndDate,
long nAutoCloseSeconds,
IDispatch* objErrorList,
VARIANT_BOOL bResolve,
long* plNumErrors
);

Parameters

szAuctionId

[in] A BSTR that contains the unique auction ID.

szSKU

[in] A BSTR that contains the unique ID for the item.

cyReservePrice

[in] A CURRENCY that contains the minimum price the seller is willing to sell the item for. The reserve price must be greater than the minimum bid.

nAvailable

[in] A long that contains the number of items for sale.

cyBidIncrement

[in] A CURRENCY that contains the amount a bid must be raised in order to bid on the item.

nAuctionType

[in] A long that contains the auction type. For more information, see the Remarks section.

cyMinimumBid

[in] A CURRENCY that contains the minimum opening bid.

fSealedBid

[in] A VARIANT_BOOL that indicates whether to check a bid against the minimum bid. A value of True skips the minimum bid check. A value of False checks against the minimum bid.

fSealedInventory

[in] A VARIANT_BOOL that indicates whether to check the wanted number of items in a bid against the number of items available for sale. A value of True skips the check (the fTakeLess parameter in the bid is ignored). A value of False checks against the available items.

fActive

[in] A VARIANT_BOOL that indicates whether the auction is active. A value of True indicates the auction is active. A value of False suspends bidding on the auction.

dtStartDate

[in] A DATE that determines when bids will be accepted on the item.

dtEndDate

[in] A DATE that determines when the auction is closed and the items can be purchased.

nAutoCloseSeconds

[in] A long that indicates the number of seconds to wait after the last bid is received to close the auction. This can close an auction before the end date. A value of zero (0) indicates to ignore the time of the last bid and close the auction on the end date.

objErrorList

[in] A pointer to the IDispatch interface that contains the error list.

bResolve

[in, optional, defaultvalue (-1)] A VARIANT_BOOL that indicates whether to call the AuctionResolve method. The default value of True causes the method to be called with the bOptimize parameter of the method set to False. A value of False causes the Auction object to skip the automatic call to the AuctionResolve method.

plNumErrors

[out, retval] A pointer to a long used to return the number of error strings written to the objErrorList object.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The auction type controls the method used to determine the winning bidder and the amount the winning bidder must pay. The following table describes the available auction types.

Auction Type | Value | Description | Example
Winning Price | 0 | Winning bidders receive the item they bid on for the amount bid. If there is more than one item, winning bidders receive the number requested at the amount they bid. | Two items are at auction. Bidder A bids $10.00, Bidder B bids $5.00, and Bidder C bids $3.00, and each bidder requests one item. Bidder A receives one item for $10.00 and Bidder B receives one item for $5.00. However, if Bidder A requested two items at $10.00 each, both items would be awarded to Bidder A.
Clear Price | 1 | Winning bidders receive the item they bid on for the lowest winning bid. | Same conditions as Winning Price auction type example. Bidder A and Bidder B each receive one item for $5.00.
Second Price | 2 | Winning bidders pay the lowest of the following: The highest losing bid plus the bid increment, the lowest winning bid, or the reserve price, assuming the number of bids above the reserve price is less than the number of available items. | Same conditions as Winning Price auction type example with a bid increment of $0.50. Bidder A and Bidder B each receive one item for $3.50.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Auction Object


_Auction::get_dtAMT, put_dtAMT

The dtAMT property is a read/write DATE value used to timestamp auction actions.

Definition

Get method:

HRESULT _Auction::get_dtAMT(
DATE* dtAMT
);

Put method:

HRESULT _Auction::put_dtAMT(
DATE dtAMT
);

Parameters

dtAMT

[in] When putting the property, a DATE that contains the time stamp.
[out, retval] When getting the property, a pointer to a DATE used to return the time stamp.

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Auction Object


_Auction::get_objMessageManager, put_objMessageManager

The objMessageManager property is a read/write MessageManager object used to return error messages to the bidder.

Definition

Get method:

HRESULT _Auction::get_objMessageManager(
IDispatch** objMessageManager
);

Put method:

HRESULT _Auction::put_objMessageManager(
IDispatch* objMessageManager
);

Parameters

objMessageManager

[in] When putting the property, a pointer to the IDispatch interface of a MessageManager object.
[out, retval] When getting the property, the address of a pointer to the IDispatch interface of a MessageManager object.

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Auction Object


_Auction::get_szBidOrderBy, put_szBidOrderBy

The szBidOrderBy property is a read/write String used to resolve ties.

Definition

Get method:

HRESULT _Auction::get_szBidOrderBy(
BSTR* szBidOrderBy
);

Put method:

HRESULT _Auction::put_szBidOrderBy(
BSTR szBidOrderBy
);

Parameters

szBidOrderBy

[in] When putting the property, a BSTR that contains a comma-separated list of the fields used as criteria for selecting the auction winners.
[out, retval] When getting the property, a pointer to a BSTR used to return a comma-separated list of the fields used as criteria for selecting the auction winners.

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

This string contains the fields (from the Bid table) used as criteria for selecting the auction winners when equal amounts are bid for an item. The string is added to the ORDER BY clause of a SQL string passed to the database for selecting the winners. The default string is "desired, modified_date". This means if two bidders bid the same amount, the bidder requesting more items wins. If still tied, the bidder placing the earliest bid wins.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Auction Object


_Auction::get_szBidTableName, put_szBidTableName

The szBidTableName property is a read/write String used to store the name of the Bid table in the database.

Definition

Get method:

HRESULT _Auction::get_szBidTableName(
BSTR* szBidTableName
);

Put method:

HRESULT _Auction::put_szBidTableName(
BSTR szBidTableName
);

Parameters

szBidTableName

[in] When putting the property, a BSTR that contains the Bid table name.
[out, retval] When getting the property, a pointer to a BSTR used to return the Bid table name.

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The Bid table contains information about bids placed on auction items. The default name for this table in the site database is Auction_bid.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Auction Object


_Auction::get_szDSN, put_szDSN

The szDSN property is a read/write String used to store the connection string for the database.

Definition

Get method:

HRESULT _Auction::get_szDSN(
BSTR* szDSN
);

Put method:

HRESULT _Auction::put_szDSN(
BSTR szDSN
);

Parameters

szDSN

[in] When putting the property, a BSTR that contains the connection string.
[out, retval] When getting the property, a pointer to a BSTR used to return the connection string.

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The connection string defaults to an empty string and must be set before the Auction object can be used.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Auction Object


_Auction::get_szItemTableName, put_szItemTableName

The szItemTableName property is a read/write String used to store the name of the Item table in the database.

Definition

Get method:

HRESULT _Auction::get_szItemTableName(
BSTR* szItemTableName
);

Put method:

HRESULT _Auction::put_szItemTableName(
BSTR szItemTableName
);

Parameters

szItemTableName

[in] When putting the property, a BSTR that contains the Item table name.
[out, retval] When getting the property, a pointer to a BSTR used to return the Item table name.

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The Item table contains information about items available for auction. The default name of this table in the site database is Auction_item.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Auction Object


_Auction::get_szLanguage, put_szLanguage

The szLanguage property is a read/write String used to store the language used by the MessageManager object when generating error messages.

Definition

Get method:

HRESULT _Auction::get_szLanguage(
BSTR* szLanguage
);

Put method:

HRESULT _Auction::put_szLanguage(
BSTR szLanguage
);

Parameters

szLanguage

[in] When putting the property, a BSTR that contains the name of the language used by the MessageManager object.
[out, retval] When getting the property, a pointer to a BSTR used to return the name of the language used by the MessageManager object.

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Auction Object


AuthManager Object

Use this object to perform user identification and authentication and to manage user security information. This object also contains methods for cookie and cookieless browsing.

ProgID: | Commerce.AuthManager (Externally creatable)
COM Class Name: | MSCSAuthManager
COM Interface Name: | IMSCSAuthManager
Interface ID Constant: | IID_IMSCSAuthManager
Header File: | MSCSAuth.h
Type Library Name: | Microsoft Commerce 2000 AuthManager Type Library
DLL Name: | mscsauth.dll
Threading Model: | Both

The AuthManager object is intended to be used only through ASP script. However, the following methods are available in C++ through the IMSCSAuthManager interface: GenerateEncryptionKey, GetUserIDFromCookie, Initialize, Refresh, and UnInitialize.

The methods of the AuthManager object are shown in the following table.

Method | Description
GenerateEncryptionKey | Generates an encryption key for the administration of cookie data. Use this method in administrative or setup components only.
GetProperty | Retrieves the specified custom property stored in a cookie or query string.
GetURL | Generates a Uniform Resource Locator (URL) containing optional name/value pairs.
GetUserID | Retrieves the unique ID for the current user.
GetUserIDFromCookie | Retrieves a user ID from a cookie.
Initialize | Initializes the AuthManager object by caching all the required site configuration resource properties.
IsAuthenticated | Indicates whether or not a user is currently authenticated.
Refresh | Updates the cached site configuration resource properties after any of the properties have been changed.
SetAuthTicket | Generates an encrypted MSCSAuth ticket for a registered user.
SetProfileTicket | Generates an encrypted MSCSProfile ticket for an anonymous user.
SetProperty | Adds a property/value pair to a cookie or query string containing a ticket.
SetUserID | Sets the user ID property on a ticket.
UnInitialize | Removes the site-specific configuration resource properties from the cache.
URLArgs | Generates a URL-encoded query string from arrays of parameter names and values.
URLShopperArgs | Generates a URL-encoded query string from arrays of parameter names and values and appends the ticket of the user to the string.

Remarks

The AuthManager object identifies users and gathers information used for user authentication. The methods and properties of this object control and access the contents of cookies and encoded URL strings.

In the Commerce Server 2000 context, authentication uses tickets. A ticket is a string of property/value pairs that provide information about the user. Two types of tickets are supported. An authentication ticket, named MSCSAuth, is used for registered users while a profile ticket, named MSCSProfile, is used for anonymous users. In this context, registered means a user who has provided information to a site that can be used for identification.

A user may have both types of tickets. In this case, the MSCSAuth ticket takes precedence.

A ticket contains a unique user ID, and for authentication tickets, the time of last login and a time window. For an anonymous user who allows cookies, the MSCSProfile ticket is stored on the local computer of the user as a persistent cookie. For a registered user who allows cookies, the MSCSAuth ticket is stored in a session cookie and is valid for the duration of the session or a specified time window, and then is deleted.

If the user does not allow cookies, the ticket is placed in an encoded URL string. The URL string may be used to pass user information between pages and sites, provided all the URLs and query strings are generated by the AuthManager object.

The AuthManager object provides a transparent interface to the tickets, whether they are stored in cookies or in URL query strings, and handles encryption and decryption of the tickets to ensure security.

The AuthManager object is intended to be used only through Active Server Pages (ASP) since it depends on ASP intrinsic objects. Do not create the AuthManager object in application scope as it has dependencies on individual user sessions. The AuthManager object should be created and destroyed on each ASP page.

See Also

Site Security Objects

Working with Site Security and Filters


IMSCSAuthManager::GenerateEncryptionKey

Use this method to generate an encryption key for encrypting/decrypting the cookie and query string data used for tickets.

Definition

HRESULT IMSCSAuthManager::GenerateEncryptionKey(
BSTR* pbstrRet
);

Parameters

pbstrRet

[out, retval] A pointer to a BSTR used to return a copy of the encryption key.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM error that this method can return.

Constant | Value | Description
E_UPM_AUTHMANAGER_GENERATE_ENCRYPTIONKEY_FAILED | 0xC1004C26 | An error occurred while generating the encryption key using the CryptoAPI.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

This method is used by the setup and Commerce Server Site Packager components during installation, and can be used to change the encryption key at a later time.

The encryption key is stored as part of the site configuration resource properties in the Admin database.

This method is one of the few AuthManager methods used in C++ applications.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

The pbstrRet parameter contains valid data only if the method completes successfully.

See Also

AuthManager Object


IMSCSAuthManager::GetProperty

Use this method to retrieve the value of the specified custom property from the current user ticket.

Definition

HRESULT IMSCSAuthManager::GetProperty(
EnumMSCS_TicketType enumTicketType,
BSTR propName,
VARIANT* pVarCustomPropVal
);

Parameters

enumTicketType

[in] An EnumMSCS_TicketType that indicates the type of ticket that contains the property.

propName

[in] A BSTR that contains the name of the property to retrieve.

PVarCustomPropVal

[out, retval] A pointer to a VARIANT containing a BSTR with the value for the specified property in the current user ticket. If the property is not found, the pointer is set to NULL.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_UPM_AUTHID_INVALID_PROPERTY | 0xC1004C27 | Invalid custom property name or value.
E_UPM_AUTHMANAGER_API_ASP_ONLY | 0xC1004C24 | This method should only be called within an ASP page.
E_UPM_AUTHMANAGER_TICKET_NOT_SET | 0xC1004C25 | Requested ticket not set.
MSG_UPM_AUTH_PROPNOTFOUND_ERROR | 0xC1004C00 | Requested property does not exist on the ticket.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The following table defines the possible values for the EnumMSCS_TicketType.

Name | Value | Description
enumMSCS_ProfileTicketType | 1 | A MSCSProfile ticket used for an anonymous user.
enumMSCS_AuthTicketType | 2 | A MSCSAuth ticket used for a registered user.

Use the SetProperty method to place custom property values in the current user ticket.

The pVarCustomPropVal parameter contains valid data only if the method completes successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

AuthManager Object

IMSCSAuthManager::SetProperty


IMSCSAuthManager::GetURL

Use this method to generate an encoded Uniform Resource Locator (URL) string.

Definition

HRESULT IMSCSAuthManager::GetURL(
BSTR FileName,
BOOL fCookie,
BOOL fSecure,
VARIANT* pVarURLParameters,
VARIANT* pVarURLValues,
BSTR* pbstrRet
);

Parameters

FileName

[in] A BSTR that contains the file name to reference in the URL.

fCookie

[in] A BOOL that indicates whether the user allows cookies.

fSecure

[in] A BOOL that indicates whether the URL is secure (HTTPS versus HTTP).

pVarURLParameters

[in, optional, defaultvalue (NULL)] A pointer to a VARIANT containing a SAFEARRAY of parameter names to include in the URL.

pVarURLValues

[in, optional] A pointer to a VARIANT containing a SAFEARRAY of parameter values that correspond to the parameter names.

pbstrRet

[out, retval] A pointer to a BSTR used to return the encoded URL.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_UPM_AUTHMANAGER_API_ASP_ONLY | 0xC1004C24 | This method should only be called within an ASP page.
MSG_UPM_AUTH_SITE_NEEDED_ERROR | 0xC1004C10 | The Initialize method must be called with the installed site name before calling this method.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The encoded URL includes the host name (retrieved from the site configuration), the virtual directory in which the file is stored (determined by the scripting context), the name of the file, flags for cookie support and security, and optional custom name/value pairs (for example, the name "SKU" and the stock-keeping unit (SKU) value for an item in a shopping cart).

If cookies are not allowed, the cookie flag is set to False and the ticket is appended to the URL.

Note

  • When a cached HTML segment that contains a URL with an appended ticket is retrieved, the ticket needs to be replaced with the correct one (for the current user context).

The secure flag is set to True if the referenced host is secure.

Use the URLArgs or URLShopperArgs methods to encode a URL query string out of name/value pairs.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

The pbstrRet parameter contains valid data only if the method completes successfully.

See Also

AuthManager Object


IMSCSAuthManager::GetUserID

Use this method to retrieve a user ID stored in a ticket.

Definition

HRESULT IMSCSAuthManager::GetUserID(
EnumMSCS_TicketType enumTicketType,
VARIANT* pUserID
);

Parameters

enumTicketType

[in] An EnumMSCS_TicketType that indicates the type of ticket that contains the user ID.

pUserID

[out, retval] A pointer to a VARIANT containing a BSTR used to return the unique ID for the current user. If the appropriate ticket type is not found or there is no user ID, the pointer is set to NULL.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_UPM_AUTHMANAGER_API_ASP_ONLY | 0xC1004C24 | This method should only be called within an ASP page.
MSG_UPM_AUTH_SITE_NEEDED_ERROR | 0xC1004C10 | The Initialize method must be called with the installed site name before calling this method.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The following table defines the possible values for the EnumMSCS_TicketType.

Name | Value | Description
enumMSCS_ProfileTicketType | 1 | A MSCSProfile ticket used for an anonymous user.
enumMSCS_AuthTicketType | 2 | A MSCSAuth ticket used for a registered user.

If the ticket type is a MSCSAuth ticket and the ticket has expired, the ticket will be deleted and the return value will be as if there was no ticket.

If the ticket type is a MSCSAuth ticket and the ticket is within five minutes of expiring, the last login time is refreshed to the current time, allowing an additional period for the ticket to be valid.

The pUserID parameter contains valid data only if the method completes successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

AuthManager Object


IMSCSAuthManager::GetUserIDFromCookie

Use this method to retrieve a user ID stored in a cookie.

Definition

HRESULT IMSCSAuthManager::GetUserIDFromCookie(
BSTR cookieData,
BSTR* pbstrUserID
);

Parameters

cookieData

[in] A BSTR that contains the cookie.

pbstrUserID

[out, retval] A pointer to a BSTR used to return the user ID.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM error that this method can return.

Constant | Value | Description
MSG_UPM_AUTH_SITE_NEEDED_ERROR | 0xC1004C10 | The Initialize method must be called with the installed site name before calling this method.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The cookie data is always URL decoded.

Commerce Server 2000 Analysis applications use this method to extract user IDs from cookies found in Internet Information Services (IIS) logs.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

The pbstrUserID parameter contains valid data only if the method completes successfully.

See Also

AuthManager Object


IMSCSAuthManager::Initialize

Use this method to initialize the AuthManager object.

Definition

HRESULT IMSCSAuthManager::Initialize(
BSTR bstrSiteName,
);

Parameters

bstrSiteName

[in] A BSTR that contains the name of the Commerce Server 2000 Web site.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The AuthManager object must be properly initialized to a valid site name immediately after creating the object and before any other AuthManager object method is used.

The first time any AuthManager object uses this method, it connects to the Administration database and caches the site configuration data using the SiteConfig object. When subsequent AuthManager objects call this method the data is read from the cache.

Use the Refresh method to update the site configuration data after any of the properties have been changed.

Use the UnInitialize method to delete the site-specific configuration resource properties from the cache when the site is no longer valid.

It is suggested to instantiate and initialize the AuthManager object in the Global.asa file to make sure at least one instance of the object exists, and to ensure the dynamic-link library (DLL) is loaded in memory and not flushed out by Internet Information Services (IIS) for performance reasons. This AuthManager object should not be used elsewhere. A separate instance of the AuthManager object must be created and destroyed on each ASP page.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

AuthManager Object


IMSCSAuthManager::IsAuthenticated

Use this method to determine whether the current user has a valid MSCSAuth ticket. This method also allows the determination of whether the user has been authenticated within a specified period of time.

Definition

HRESULT IMSCSAuthManager::IsAuthenticated(
long TimeWindow,
VARIANT_BOOL* pboolAuth
);

Parameters

TimeWindow

[in, optional, defaultvalue (0)] A long that contains a time period in minutes.

pboolAuth

[out, retval] A pointer to a VARIANT_BOOL containing the authentication status of the current user.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_UPM_AUTHMANAGER_API_ASP_ONLY | 0xC1004C24 | This method should only be called within an ASP page.
MSG_UPM_AUTH_SITE_NEEDED_ERROR | 0xC1004C10 | The Initialize method must be called with the installed site name before calling this method.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

A MSCSAuth ticket contains the time the user last logged in and a time window of validity. The ticket is no longer valid if the time since the last login has exceeded the time window specified in the SetAuthTicket method when the ticket was generated.

The optional time window parameter, TimeWindow, of this method allows checking whether the time since the user last logged in has exceeded a shorter time interval than the time window specified by the SetAuthTicket method. The default value of zero (0) is equivalent to setting the time window to the same value as specified in the SetAuthTicket method.

This method returns False if the user does not have an MSCSAuth ticket, the ticket is invalid, or the time since the user last logged in has exceeded the specified time window.

If the ticket is within five minutes of expiring, the last login time is refreshed to the current time, allowing an additional period for the ticket to be valid.

Ensure a log-off page is created and called for any logged-in user. The log-off page should either expire the MSCSAuth cookie or clear its contents.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

The pboolAuth parameter contains valid data only if the method completes successfully.

See Also

AuthManager Object


IMSCSAuthManager::Refresh

Use this method to update the cached site configuration resource properties after any of the properties have been changed.

Definition

HRESULT IMSCSAuthManager::Refresh(
BSTR bstrSiteName
);

Parameters

bstrSiteName

[in] A BSTR that contains the site name.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

This method should be called immediately after changing any of the authentication related site configuration resource properties. Also, use this method when switching between Active Server Pages (ASP) and Microsoft Visual Basic Scripting Edition (VBScript) files and updating the site configuration properties.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

AuthManager Object


IMSCSAuthManager::SetAuthTicket

Use this method to set an encrypted MSCSAuth ticket for a registered user.

Definition

HRESULT IMSCSAuthManager::SetAuthTicket(
BSTR UserID,
VARIANT_BOOL fCookieSupport,
long TimeWindow
);

Parameters

UserID

[in] A BSTR that contains the unique ID for the current user.

fCookieSupport

[in] A VARIANT_BOOL that indicates whether session cookies are supported.

TimeWindow

[in] A long that defines the time window in minutes that the MSCSAuth ticket is valid.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_UPM_AUTHID_INVALID_CHARACTER_PRESENT | 0xC1004C23 | Invalid character (';' or '%' or '=') present in the UserID or the property name/value pair.
E_UPM_AUTHMANAGER_API_ASP_ONLY | 0xC1004C24 | This method should only be called within an ASP page.
MSG_UPM_AUTH_SITE_NEEDED_ERROR | 0xC1004C10 | The Initialize method must be called with the installed site name before calling this method.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The time the user last logged in is stored in the ticket, along with the length of time from the last login that the ticket is valid.

If an MSCSAuth ticket for the user already exists and an empty string is passed in as the ID, UserID, for the user, the existing ticket is deleted.

If the current user is anonymous, use the SetProfileTicket method to generate an MSCSProfile ticket.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

AuthManager Object

IMSCSAuthManager::IsAuthenticated


IMSCSAuthManager::SetProfileTicket

Use this method to set a MSCSProfile ticket for an anonymous user. An anonymous user is not registered with a site.

Definition

HRESULT IMSCSAuthManager::SetProfileTicket(
BSTR UserID,
VARIANT_BOOL fCookieSupport
);

Parameters

UserID

[in] A BSTR that contains the unique ID for the current user.

fCookieSupport

[in] A VARIANT_BOOL that indicates whether persistent cookies are supported.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_UPM_AUTHID_INVALID_CHARACTER_PRESENT | 0xC1004C23 | Invalid character (';' or '%' or '=') present in the UserID or the property name/value pair.
E_UPM_AUTHMANAGER_API_ASP_ONLY | 0xC1004C24 | This method should only be called within an ASP page.
MSG_UPM_AUTH_SITE_NEEDED_ERROR | 0xC1004C10 | The Initialize method must be called with the installed site name before calling this method.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

If an MSCSProfile ticket for the user already exists and an empty string is passed in for the user ID, UserID, the existing ticket is deleted.

If the current user has registered, use the SetAuthTicket method to generate an MSCSAuth ticket.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

AuthManager Object

IMSCSAuthManager::IsAuthenticated


IMSCSAuthManager::SetProperty

Use this method to place a custom property name/value pair into the current ticket for the user.

Definition

HRESULT IMSCSAuthManager::SetProperty(
EnumMSCS_TicketType enumTicketType,
BSTR propName,
BSTR propVal
);

Parameters

enumTicketType

[in] An EnumMSCS_TicketType that indicates the type of ticket.

propName

[in] A BSTR that contains the name of the property.

propVal

[in] A BSTR that contains the value corresponding to the named property.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_UPM_AUTHID_INVALID_CHARACTER_PRESENT | 0xC1004C23 | Invalid character (';' or '%' or '=') present in the UserID or the property name/value pair.
E_UPM_AUTHID_INVALID_PROPERTY | 0xC1004C27 | Invalid custom property name or value.
E_UPM_AUTHMANAGER_API_ASP_ONLY | 0xC1004C24 | This method should only be called within an ASP page.
MSG_UPM_AUTH_SITE_NEEDED_ERROR | 0xC1004C10 | The Initialize method must be called with the installed site name before calling this method.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

Use the GetProperty method to retrieve the custom property values from the current ticket.

The following table defines the possible values for the EnumMSCS_TicketType.

Name | Value | Description
enumMSCS_ProfileTicketType | 1 | A MSCSProfile ticket used for an anonymous user.
enumMSCS_AuthTicketType | 2 | A MSCSAuth ticket used for a registered user.

Note

  • A property with the name "Ticket" is used by the AuthManager object for storing Commerce Server 2000 related information. When creating a custom property, do not set the property name to "Ticket".

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

AuthManager Object

IMSCSAuthManager::GetProperty


IMSCSAuthManager::SetUserID

Use this method to change the user ID property on a ticket.

Definition

HRESULT IMSCSAuthManager::SetUserID(
EnumMSCS_TicketType enumTicketType,
BSTR newUserID
);

Parameters

enumTicketType

[in] An EnumMSCS_TicketType that indicates the type of ticket that will contain the user ID.

newUserID

[in] A BSTR that contains the unique ID for the current user.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_UPM_AUTHID_INVALID_CHARACTER_PRESENT | 0xC1004C23 | Invalid character (';' or '%' or '=') present in the UserID or the property name/value pair.
E_UPM_AUTHMANAGER_API_ASP_ONLY | 0xC1004C24 | This method should only be called within an ASP page.
MSG_UPM_AUTH_SITE_NEEDED_ERROR | 0xC1004C10 | The Initialize method must be called with the installed site name before calling this method.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The value for the user ID may be the logon name for a registered user, a globally unique identifier (GUID) for an anonymous user, or any unique value.

If the appropriate ticket already exists, the value in the user ID is updated. If the ticket already exists and an empty string is passed in as the value for the user ID, newUserID, the existing ticket is deleted.

If the ticket does not exist, a ticket is created with default values for the rest of the data.

The following table defines the possible values for the EnumMSCS_TicketType.

Name | Value | Description
enumMSCS_ProfileTicketType | 1 | A MSCSProfile ticket used for an anonymous user.
enumMSCS_AuthTicketType | 2 | A MSCSAuth ticket used for a registered user.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

AuthManager Object


IMSCSAuthManager::UnInitialize

Use this method to delete the site-specific configuration resource properties from the cache when the site is no longer valid.

Definition

HRESULT IMSCSAuthManager::UnInitialize(
BSTR bstrSiteName,
);

Parameters

bstrSiteName

[in] A BSTR that contains the name of the site.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
MSG_UPM_AUTH_SITE_NEEDED_ERROR | 0xC1004C10 | The Initialize method must be called with the installed site name before calling this method.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

This method must be called to disconnect the AuthManager object cache from the specified site.

The Initialize method loads the site configuration resource properties into the cache.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

AuthManager Object


IMSCSAuthManager::URLArgs

Use this method to generate a Uniform Resource Locator (URL) encoded query string of name/value pairs.

Definition

HRESULT IMSCSAuthManager::URLArgs(
VARIANT* pVarURLParameters,
VARIANT* pVarURLValues,
BSTR* pbstrRet
);

Parameters

pVarURLParameters

[in] A pointer to a VARIANT containing a SAFEARRAY of parameter names.

pVarURLValues

[in] A pointer to a VARIANT containing a SAFEARRAY of parameter values corresponding to the parameter names.

pbstrRet

[out, retval] A pointer to a BSTR that contains the resulting URL-encoded query string.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_UPM_AUTHMANAGER_API_ASP_ONLY | 0xC1004C24 | This method should only be called within an ASP page.
MSG_UPM_AUTH_SITE_NEEDED_ERROR | 0xC1004C10 | The Initialize method must be called with the installed site name before calling this method.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

This method concatenates the parameter name/value pairs into a URL-encoded string. This method will fail if the two arrays containing the parameter names and values are not the same size.

The URLShopperArgs method performs the same URL encoding and additionally appends the ticket to the query string, if a ticket is set.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

The pbstrRet parameter contains valid data only if the method completes successfully.

See Also

AuthManager Object

IMSCSAuthManager::URLShopperArgs


IMSCSAuthManager::URLShopperArgs

Use this method to generate a Uniform Resource Locator (URL) encoded query string of name/value pairs and append the ticket to the query string if a ticket is set.

Definition

HRESULT IMSCSAuthManager::URLShopperArgs(
VARIANT* pVarURLParameters,
VARIANT* pVarURLValues,
BSTR* pbstrRet
);

Parameters

pVarURLParameters

[in] A pointer to a VARIANT containing a SAFEARRAY of parameter names.

pVarURLValues

[in] A pointer to a VARIANT containing a SAFEARRAY of parameter values corresponding to the parameter names.

pbstrRet

[out, retval] A pointer to a BSTR that contains the resulting URL-encoded query string.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_UPM_AUTHMANAGER_API_ASP_ONLY | 0xC1004C24 | This method should only be called within an ASP page.
MSG_UPM_AUTH_SITE_NEEDED_ERROR | 0xC1004C10 | The Initialize method must be called with the installed site name before calling this method.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

This method concatenates the parameter name/value pairs into a URL-encoded string and appends the ticket. This is useful for cookieless shopping support. This method will fail if the two arrays containing the parameters and values are not the same size.

If both types of tickets exist, the MSCSAuth ticket takes precedence.

Use the URLArgs method to perform URL encoding of parameter/value pairs without appending the ticket.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

The pbstrRet parameter contains valid data only if the method completes successfully.

See Also

AuthManager Object

IMSCSAuthManager::SetProperty

IMSCSAuthManager::SetAuthTicket

IMSCSAuthManager::SetProfileTicket

IMSCSAuthManager::URLArgs


BizDeskSecurity Object

Use this object to determine whether to display a module in the navigation pane of Commerce Server Business Desk.

ProgID: | Commerce.BizDeskSecurity (Externally creatable)
COM Class Name: | BizDeskSecurity
COM Interface Name: | IBizDeskSecurity
Interface ID Constant: | None
Header File: | None
Type Library Name: | Microsoft Commerce 2000 BizDesk Security Type Library
DLL Name: | BDSecurity.dll
Threading Model: | Free

In C++, use the IBizDeskSecurity interface to access the one method of the BizDeskSecurity object.

The one method of the BizDeskSecurity object is shown in the following table.

Method | Description
CanUserAccess | Determines whether the user has access rights to read the specified file.

Remarks

The Business Desk framework calls this object to determine which modules to display to the current user.

See Also

Site Security Objects


IBizDeskSecurity::CanUserAccess

Use this method to determine whether the current user has read access rights to the specified Commerce Server Business Desk module.

Definition

HRESULT IBizDeskSecurity::CanUserAccess(
BSTR bstrPath,
VARIANT_BOOL* pbAccessOK
);

Parameters

bstrPath

[in] A BSTR that contains the file name and path for a Business Desk module.

pbAccessOK

[out, retval] The address of a VARIANT_BOOL used to return either TRUE or FALSE. A value of TRUE indicates that the current user has read access rights to the specified file. A value of FALSE indicates that the current user does not have read access rights to the specified file.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

Whether the user has read access to the specified Business Desk module is determined from the entries in the access control lists (ACLs) set for the file.

The pbAccessOK parameter contains valid data only if the method returns successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

BizDeskSecurity Object


CacheManager Object

Use this object to establish and use a collection of data caches. Each data cache is either a Dictionary object or an LRUCache object. You can specify which one you would like to use by setting the CacheObjectProgID property.

ProgID: | Commerce.CacheManager (Externally creatable)
COM Class Name: | CacheManager
COM Interface Name: | ICacheManager
Interface ID Constant: | IID_ICacheManager
Header File: | None
Type Library Name: | Microsoft Commerce 2000 Cache Manager Type Library
DLL Name: | mscscache.dll
Threading Model: | Both

In C++, use the ICacheManager interface to access the properties and methods of the CacheManager object.

The properties of the CacheManager object are shown the following table.

Property | Type | Description
AppUrl | BSTR | Stores the full Uniform Resource Locator (URL) of the application. This property is read/write.
CacheObjectProgId | BSTR | Stores the Programmatic Identifier (ProgID) for the object that is to be used for cache functions internally within the CacheManager object. Determines the type of object returned by the GetCache method. This property is read/write.
LoaderConfig | IDispatch | Stores the configuration Dictionary object that should be passed to the Loader component. This property is read/write.
LoaderProgId | BSTR | Stores the ProgID of the component used to create and populate a data cache. This property is read/write.
RefreshInterval | long | Stores the number of seconds between automatic cache refresh operations. This property is read/write.
RetryInterval | long | Stores the number of seconds to wait before retrying after a cache load has failed. This property is read/write.
WriterConfig | IDispatch | Stores the configuration Dictionary object that should be passed to the Writer component. This property is read/write.
WriterProgId | BSTR | Stores the ProgID of the component used to write out some type of data that has been accumulated since the last refresh. Advertising event data is one example of the type of data that might be accumulated. This property is read/write.

The methods of the CacheManager object are shown in the following table.

Method | Description
GetCache | Retrieves the data cache Dictionary object associated with a specified data cache name.
RefreshCache | Forces an immediate, synchronous refresh of the cache.

See Also

General Purpose Programming Concepts

Code to Implement Custom Cache Components


ICacheManager::get_AppUrl, put_AppUrl

The AppUrl property is a read/write string that contains the full Uniform Resource Locator (URL) of the application.

Definition

Get method:

HRESULT ICacheManager::get_AppUrl(
BSTR* AppUrl
);

Put method:

HRESULT ICacheManager::put_AppUrl(
BSTR AppUrl
);

Parameters

AppUrl

[in] When putting the property, a BSTR that contains the full URL of the application.
[out,retval] When getting the property, a pointer to a BSTR used to return the full URL of the application.

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The default value for this property is the URL of the current Internet Information Services (IIS) 5.0 application. Depending on the URL used to access the IIS application the first time after it is started, this URL could contain the special host name "localhost," preventing it from being accessed externally. Therefore, it is best to explicitly set this property to the full URL of the IIS application.

Unlike the other properties of CacheManager object that are set on a per-cache basis, the AppUrl property is a global property. The AppUrl property is generally used to register all of the caches running in a web server farm so that they can be managed without requiring explicit registration by an administrator. The Publish Campaign module in Commerce Server Business Desk is an example of this.

If the cache object is a Dictionary object, then the value of this property is passed to the CacheLoader and CacheWriter objects during each cache refresh. It will be put in the _AppUrl key in the Dictionary object.

See Also

CacheManager Object


ICacheManager::GetCache

Use this method to retrieve either the Dictionary or LRUCache object for the specified cache name.

Definition

HRESULT ICacheManager::GetCache(
BSTR bstrName,
IDispatch** ppdict
);

Parameters

bstrName

[in] A BSTR that contains the name of the cache to be retrieved.

ppdict

[out,retval] A pointer used to return the IDispatch interface of the data cache Dictionary object.

Return Values

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

This method is designed to be lightweight and fast. It is commonly called several times on any given ASP page.

The first time the GetCache method or the RefreshCache method is called, the data cache object is created and the configured CacheLoader component is invoked to populate it with data. Subsequent calls to the GetCache method may return the same cache object or a new cache object that is created when the cache is refreshed.

If the first call to the GetCache method for a particular cache results in a failed refresh, then the CacheManager object will not immediately retry a refresh when more GetCache method calls are made for the same cache. This is to avoid recurring timeouts that might bring down a system, for example if a database connection becomes temporarily unavailable. In this failure scenario, subsequent calls to the GetCache method will return an error indicating that the cache load failed and will not be retried until the refresh interval has elapsed or until the RefreshCache method is explicitly called.

After a cache has successfully been created, if a subsequent refresh of the cache fails, then the existing cache object is returned until a later refresh succeeds. The CacheManager object provides high availability to cache data at the expense of ensuring the cached data is up to date.

See Also

CacheManager Object


ICacheManager::get_CacheObjectProgId, put_CacheObjectProgId

The CacheObjectProgId property is a read/write String that contains the name of the object to be used internally to perform caching functions for this CacheManager object. It also determines the type of object returned by the GetCache method.

Definition

Get method:

HRESULT ICacheManager::get_CacheObjectProgId(
BSTR bstrName,
BSTR* CacheObjectProgId
);

Put method:

HRESULT ICacheManager::put_CacheObjectProgId(
BSTR bstrName,
BSTR CacheObjectProgId
);

Parameters

bstrName

[in] A BSTR that contains the name of the cache object.

CacheObjectProgId

[in] When putting the property, a BSTR that contains the Programmatic Identifier (ProgID) of the cache object.
[out,retval] When getting the property, a pointer to a BSTR used to return the ProgID of the cache object.

Return Values

These methods return an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The CacheObjectProgId parameter contains valid data only if the property was accessed successfully.

By default, the CacheManager object will have Commerce.Dictionary set as the value for this property.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CacheManager Object


ICacheManager::get_LoaderConfig, putref_LoaderConfig

The LoaderConfig property is a read/write reference to a Dictionary object that contains configuration information for the Loader component.

Definition

Get method:

HRESULT ICacheManager::get_LoaderConfig(
BSTR bstrName,
IDispatch** LoaderConfig
);

Put method:

HRESULT ICacheManager::putref_LoaderConfig(
BSTR bstrName,
IDispatch* LoaderConfig
);

Parameters

bstrName

[in] A BSTR that contains the name of a data cache for which Loader component configuration information is being provided or retrieved.

LoaderConfig

[in] When putting the property, a pointer to the IDispatch interface of the Dictionary object that contains the Loader component configuration information.
[out,retval] When getting the property, the address of a pointer used to return the IDispatch interface of the Dictionary object that contains the configuration information.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

This property, a Dictionary object containing configuration information for a particular Loader component, will be passed to that Loader component when it is created to load the associated data cache. When you set this property, the dictionary is shallow cloned and then the CacheManager object stores the clone of the dictionary. This is as opposed to simply storing a reference to the dictionary. Shallow clone means that scalars in the dictionary are copied by value, but other objects in the dictionary are copied by reference. The Loader component needs to implement the IPipelineComponentAdmin interface in order to read the configuration values from the dictionary, and in particular, the SetConfigData method of that interface. The Dictionary object identified by this property is passed to the newly created Loader component using the SetConfigData method.

See Also

CacheManager Object


ICacheManager::get_LoaderProgId, put_LoaderProgId

The LoaderProgId property is a read/write string that contains the Programmatic Identifier (ProgID) of the component intended for use in populating the cache.

Definition

Get method:

HRESULT ICacheManager::get_LoaderProgId(
BSTR bstrName,
BSTR* LoaderProgId
);

Put method:

HRESULT ICacheManager::put_LoaderProgId(
BSTR bstrName,
BSTR LoaderProgId
);

Parameters

bstrName

[in] A BSTR that contains the name of a data cache for which the Loader component ProgID is being provided or retrieved.

LoaderProgId

[in] When putting the property, a BSTR that contains the ProgID of the Loader component.
[out,retval] When getting the property, a pointer to a BSTR user to return the ProgID of the Loader component.

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

See Also

CacheManager Object


ICacheManager::RefreshCache

Use this method to force an immediate refresh of a data cache Dictionary object. This method is synchronous, not returning to the caller until the specified data cache is refreshed.

Definition

HRESULT ICacheManager::RefreshCache(
BSTR bstrName
);

Parameters

bstrName

[in] A BSTR that contains the name of the data cache to be refreshed.

Return Values

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

If the specified cache is in the middle of being refreshed when the RefreshCache method is invoked, presumably by the background timer thread or a different foreground thread, this method will wait until the refresh operation is complete and then return. It will not result in another refresh operation.

See Also

CacheManager Object


ICacheManager::get_RefreshInterval, put_RefreshInterval

The RefreshInterval property is a read/write number that specifies the approximate number of seconds between automatic cache refresh operations on a specified cache.

Definition

Get method:

HRESULT ICacheManager::get_RefreshInterval(
BSTR bstrName,
long* RefreshInterval
);

Put method:

HRESULT ICacheManager::put_RefreshInterval(
BSTR bstrName,
long RefreshInterval
);

Parameters

bstrName

[in] A BSTR that contains the name of a data cache for which the refresh interval is being provided or retrieved.

RefreshInterval

[in] When putting the property, a long that contains the new refresh interval value.
[out,retval] When getting the property, a pointer to a long used to return the current refresh interval value.

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

A refresh interval value of zero (0) means that the cache is never refreshed automatically.

The default refresh interval value is zero (0).

The value is a measurement of the number of seconds between automatic cache refresh operations.

See Also

CacheManager Object


ICacheManager::get_RetryInterval, put_RetryInterval

The RetryInterval property is a read/write number that specifies the approximate number of seconds to wait before retrying to load the data cache after failing to load.

Definition

Get method:

HRESULT ICacheManager::get_RetryInterval(
BSTR bstrName,
long* RetryInterval
);

Put method:

HRESULT ICacheManager::put_RetryInterval(
BSTR bstrName,
long RetryInterval
);

Parameters

bstrName

[in] A BSTR that contains the name of a data cache for which the retry interval is being provided or retrieved.

RetryInterval

[in] When putting the property, a long that contains the new retry interval value.
[out,retval] When getting the property, a pointer to a long used to return the current retry interval value.

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

A retry interval value provides the number of seconds the CacheManager object should wait before retrying a failed cache refresh operation.

The default retry interval value is 60 (seconds).

The retry interval must be at least 1 (second).

See Also

CacheManager Object


ICacheManager::get_WriterConfig, putref_WriterConfig

The WriterConfig property is a read/write reference to a Dictionary object that contains configuration information for the Writer component.

Definition

Get method:

HRESULT ICacheManager::get_WriterConfig(
BSTR bstrName,
IDispatch** WriterConfig
);

Put method:

HRESULT ICacheManager::putref_WriterConfig(
BSTR bstrName,
IDispatch* WriterConfig
);

Parameters

bstrName

[in] A BSTR that contains the name of a data cache for which Writer component configuration information is being provided or retrieved.

WriterConfig

[in] When putting the property, a pointer to the IDispatch interface of the Dictionary object that contains the Writer component configuration information.
[out,retval] When getting the property, the address of a pointer used to return the IDispatch interface of the Dictionary object that contains the configuration information.

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

This property, a Dictionary object containing configuration information for a particular Writer component, is passed to that Writer component when it is created to report results related to cache usage. When you set this property, the dictionary is shallow cloned and then the CacheManager object stores the clone of the dictionary. This is as opposed to simply storing a reference to the dictionary. Shallow clone means that scalars in the dictionary are copied by value, but other objects in the dictionary are copied by reference. The Writer component needs to implement the IPipelineComponentAdmin interface in order to read the configuration values from the dictionary, and in particular, the SetConfigData method of that interface. The Dictionary object identified by this property is passed to the created Writer component using the SetConfigData method.

See Also

CacheManager Object


ICacheManager::get_WriterProgId, put_WriterProgId

The WriterProgId property is a read/write string that contains the Programmatic Identifier (ProgID) of the component intended for use in populating the cache.

Definition

Get method:

HRESULT ICacheManager::get_WriterProgId(
BSTR bstrName,
BSTR* WriterProgId
);

Put method:

HRESULT ICacheManager::put_WriterProgId(
BSTR bstrName,
BSTR WriterProgId
);

Parameters

bstrName

[in] A BSTR that contains the name of a data cache for which the Writer component ProgID is being provided or retrieved.

WriterProgId

[in] When putting the property, a BSTR that contains the ProgID of the Writer component.
[out,retval] When getting the property, a pointer to a BSTR user to return the ProgID of the Writer component.

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

See Also

CacheManager Object


CatalogManager Object

Use this object to work with the entire Product Catalog System. The methods and properties of this object effect all catalogs contained in the Product Catalog System.

ProgID: | Commerce.CatalogManager (Externally creatable)
COM Class Name: | CatalogManager
COM Interface Name: | ICatalogManager
Interface ID Constant: | IID_ICatalogManager
Header File: | Catalog.h, mspu_guids.h
Type Library Name: | Microsoft Commerce 2000 Catalog Type Library
DLL Name: | Catalog.dll
Threading Model: | Both

In C++, use the ICatalogManager interface to access the properties and methods of the CatalogManager object.

Because this object is primarily intended for use within ASP script, access from C++ will not be common.

The properties of the CatalogManager object are shown in the following table.

Property | Type | Description
Catalogs | _Recordset | Returns a recordset containing a record for each catalog contained in the Product Catalog System, including their properties. This property is read-only.
CategoryDefinitions | _Recordset | Returns a recordset containing the names of all of the category definitions that currently exist in the Product Catalog System. This property is read-only.
CustomCatalogs | _Recordset | Returns a recordset containing a record for each custom catalog. These records include the custom catalog names and the names of the catalogs they are based on. This property is read-only.
ProductDefinitions | _Recordset | Returns a recordset containing the names of all the product definitions that currently exist in the Product Catalog System. This property is read-only.
Properties | _Recordset | Returns a recordset containing the name of each property that currently exists in the Product Catalog System. This property is read-only.

The methods of the CatalogManager object are shown in the following table.

Method | Description
AddDefinitionProperty | Adds a property to a definition.
AddDefinitionVariantProperty | Adds a variant property to a definition.
AddPropertyValue | Adds a value to the list of defined values for this property. Only applies to enumerations.
CreateCatalog | Creates a new catalog.
CreateCategoryDefinition | Creates a new category definition.
CreateProductDefinition | Creates a new product definition.
CreateProperty | Creates a new property.
DeleteCatalog | Deletes a catalog.
DeleteDefinition | Deletes a product or category definition
DeleteProperty | Deletes a property.
ExportCSV | Exports catalog data as a comma-separated value format file.
ExportXML | Exports catalog data as an Extensible Markup Language (XML) format file.
FreeTextSearch | Performs a free-text search of catalogs.
GetCatalog | Returns the specified catalog object.
GetDefinitionProperties | Returns the properties of a specified definition.
GetPropertyAttributes | Returns all the attributes of a specified property.
GetPropertyValues | Returns a list of appropriate values for an enumeration property.
ImportCSV | Imports a comma-separated value format file as catalog data.
ImportXML | Imports an XML format file as catalog data.
Initialize | Initializes the CatalogManager object.
Query | Performs queries against product, variant, and category data in one or more catalogs.
RemoveDefinitionProperty | Removes the specified property or variant property from a definition.
RemovePropertyValue | Removes a defined value from an enumeration property.
RenameDefinition | Renames a definition.
RenameProperty | Renames a property.
SetDefinitionProperties | Use this method to change the properties of a category or product definition.
SetPropertyAttributes | Changes the attributes of a property.

Remarks

Some methods of the CatalogManager object cannot be called in a transacted object. They are the CreateCatalog, DeleteCatalog, GenerateCustomCatalog, ImportCSV, ImportXML, and RegenerateFreeTextSearchIndex methods. These methods involve the creation, deletion, or updating of free text indexes. SQL Server does not allow these operations in a transaction.

Binding to the CatalogManager in a COM+ component that has either the Required or Requires New property set generates a run time error.


ICatalogManager::AddDefinitionProperty

Use this method to add an existing property to an existing category or product definition.

Definition

HRESULT ICatalogManager::AddDefinitionProperty(
BSTR strDefinitionName,
BSTR strPropertyName
);

Parameters

strDefinitionName

[in] A BSTR that contains the name of the definition to which the property will be added.

strPropertyName

[in] A BSTR that contains the name of the property.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_DEFINITION_DOESNT_EXIST | 0x8898000B | The specified definition did not exist.
E_CAT_PROP_DOESNT_EXIST | 0x88980005 | The specified property did not exist.
E_CAT_PROP_IN_DEFINITION | 0x8898000D | The specified property was already in the definition.
OLE_E_BLANK | 0x80040007 | The object was not initialized. The Initialize method must be called before calling any other method.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

This method adds a property to a definition. Any products or categories created from the definition will also have the property. A property can only be added to a definition once. A property cannot be used in a product definition as both a property and a variant property.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CatalogManager Object

ICatalogManager::AddDefinitionVariantProperty

ICatalogManager::RemoveDefinitionProperty


ICatalogManager::AddDefinitionVariantProperty

Use this method to add a variant property to a definition. This method is similar to the AddDefinitionProperty method. The properties added with this method will only be used by product variants.

Definition

HRESULT ICatalogManager::AddDefinitionVariantProperty(
BSTR strDefinitionName,
BSTR strPropertyName
);

Parameters

strDefinitionName

[in] A BSTR that contains the name of the definition to which the specified variant property will be added.

strPropertyName

[in] A BSTR that contains the name of the property to be added to the specified definition.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_DEFINITION_DOESNT_EXIST | 0x8898000B | The specified definition did not exist.
E_CAT_PROP_DOESNT_EXIST | 0x88980005 | The specified property did not exist.
E_CAT_PROP_IN_DEFINITION | 0x8898000D | The specified property was already in the definition.
OLE_E_BLANK | 0x80040007 | The object was not initialized. The Initialize method must be called before calling any other method.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

This method adds a variant property to a definition. Any product variants created from the definition will also have the property. A property can only be added to a definition once. A property cannot be used in a product definition as both a property and a variant property.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CatalogManager Object

ICatalogManager::AddDefinitionProperty

ICatalogManager::RemoveDefinitionProperty


ICatalogManager::AddPropertyValue

Use this method to add a value to the list of defined values for the specified enumeration.

Definition

HRESULT ICatalogManager::AddPropertyValue(
BSTR strPropertyName,
BSTR strLegalValue
);

Parameters

strPropertyName

[in] A BSTR that contains the name of the enumeration property for which a new value will be defined.

strLegalValue

[in] A BSTR that contains the new value.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_PROP_DOESNT_EXIST | 0x88980005 | The property you specified did not exist.
E_CAT_PROP_NOT_ENUM | 0x88980007 | The property you specified was not of type cscEnumeration.
E_CAT_VALUE_ALREADY_ADDED | 0x88980008 | The enumeration value you specified was already present in the list.
OLE_E_BLANK | 0x80040007 | The object was not initialized. The Initialize method must be called before calling any other method.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The AddPropertyValue method is used only for properties whose data type is cscEnumeration.

This method adds a new value to the list of defined values for an enumeration property. Any attempts by a client to set this property to a value other than one of the legal values will result in an error. This method is useful for automatic validation against properties that only have a small, fixed set of values. For example, a Color property may have red, green, and blue as the only defined values.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CatalogManager Object

ICatalogManager::GetPropertyValues

ICatalogManager::RemovePropertyValue


ICatalogManager::get_Catalogs

The Catalogs property is a read-only recordset that describes all the catalogs in the Product Catalog System. The returned recordset includes the properties of each catalog.

Definition

HRESULT ICatalogManager::get_Catalogs(
_Recordset** Catalogs
);

Parameters

Catalogs

[out, retval] A pointer to a _Recordset object used to return the catalogs.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
OLE_E_BLANK | 0x80040007 | The object was not initialized. The Initialize method must be called before calling any other method.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The Catalogs parameter contains valid data only if the property was accessed successfully.

The returned recordset contains the following fields:

Field Name | Data-Type | Description
CatalogName | String 128 Characters | None
Locale | Integer | None
StartDate | DateTime | None
EndDate | DateTime | None
VariantID | String 128 Characters | The name of the property that uniquely identifies a product variant.
ProductID | String 128 Characters | The name of the property that uniquely identifies a product.
Currency | String 128 Characters | None
WeightMeasure | String 128 Characters | None
TimeStamp | Timestamp | None
CatalogID | Integer | The number that uniquely identifies a catalog.
CustomCatalog | Bit | A flag indicating whether this is a custom catalog.
FreeTextIndexCreated | DateTime | None
ProductTableUpdated | Datetime | None

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CatalogManager Object

ICatalogManager::CreateCatalog

ICatalogManager::DeleteCatalog


ICatalogManager::get_CategoryDefinitions

The CategoryDefinitions property is a read-only recordset that contains the names of all the category definitions in the Product Catalog System.

Definition

HRESULT ICatalogManager::get_CategoryDefinitions(
_Recordset** CategoryDefinitions
);

Parameters

CategoryDefinitions

[out, retval] A pointer to a _Recordset object used to return category definitions.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The CategoryDefinitions parameter contains valid data only if the property was accessed successfully.

The returned recordset will contain a single field called DefinitionName and one row for each category definition in the Product Catalog System. This field is a 128 character String.

If no category definitions are currently in the Product Catalog System, then the EOF property of the returned recordset will be set to VARIANT_TRUE.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CatalogManager Object

ICatalogManager::CreateCategoryDefinition

ICatalogManager::DeleteDefinition


ICatalogManager::CreateCatalog

Use this method to create a new catalog.

Definition

HRESULT ICatalogManager::CreateCatalog(
BSTR strCatalogName,
BSTR strProductID,
VARIANT strProductVariantID,
VARIANT lcidLocale,
VARIANT strCurrency,
VARIANT strWeightMeasure,
VARIANT dtStartDate,
VARIANT dtEndDate,
IProductCatalog** ppNewCatalog
);

Parameters

strCatalogName

[in] A BSTR that contains the name of the catalog to be created. See the Remarks section for a list of restricted characters.

strProductID

[in] A BSTR that contains the product ID property.

strProductVariantID

[in, optional] A VARIANT that contains the product variant ID property.

lcidLocale

[in, optional] A VARIANT that contains the locale ID (LCID) of the catalog to be created.

strCurrency

[in, optional] A VARIANT that contains the currency type of the catalog to be created.

strWeightMeasure

[in, optional] A VARIANT that contains the unit of weight or measure of the catalog to be created.

dtStartDate

[in, optional] A VARIANT of subtype DATE that contains the start date.

dtEndDate

[in, optional] A VARIANT of subtype DATE that contains the end date.

ppNewCatalog

[out, retval] A pointer used to return the IProductCatalog interface of the new catalog.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_CATALOG_EXISTS | 0x88980001 | There was already a catalog by that name. Catalog names must be unique throughout the Product Catalog System.
E_CAT_PRODID_DOESNT_EXIST | 0x88980010 | The property you specified for the ProductID did not exist in the Product Catalog System properties.
E_CAT_UPDATE_FREETEXT_INDEX_FAILED | 0x88980015 | This error occurs when full text search is installed but updating the full text search index fails. The catalog is created but full text search does not work. For the catalog to participate in full text searches delete the catalog and recreate it.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The ppNewCatalog parameter contains valid data only if the method completes successfully.

If variants are to be used in this catalog, you must provide a property name in the optional strProductVariantID parameter. If this parameter is not specified upon creation of the catalog, any attempt to create a product variant in that catalog will fail.

If the strProductID or strProductVariantID parameters are of type cscString, cscEnumeration, or cscFileName, they are limited to a length of 256 characters.

The returned ProductCatalog object will be pre-initialized and ready for use.

Notes

  • This method cannot be called in a transacted object. This method involves the creation, deletion, or updating of free text indexes. SQL Server does not allow these operations in a transaction.

  • Catalog names, and therefore the strCatalogName, parameter cannot begin with the pound sign (#) and cannot contain any of the following characters:
    • Blank space ( )

    • Double quote (")

    • Comma (,)

    • Period (.)

    • Left square bracket ([)

    • Right square bracket (])

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CatalogManager Object

ICatalogManager::DeleteCatalog

ICatalogManager::GetCatalog


ICatalogManager::CreateCategoryDefinition

Use this method to create a new category definition.

Definition

HRESULT ICatalogManager::CreateCategoryDefinition(
BSTR strDefinitionName
);

Parameters

strDefinitionName

[in] A BSTR that contains the name of the new category definition.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_DEFINITION_EXISTS | 0x8898000A | The specified category definition name already existed.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

Category and product definition names must be globally unique across the entire Product Catalog System. It is not possible to have a category definition and a product definition with the same name.

The initial definition is empty when it is created. To add individual properties to the definition, use the AddDefinitionProperty method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CatalogManager Object

ICatalogManager::AddDefinitionProperty

ICatalogManager::CreateProductDefinition

ICatalogManager::DeleteDefinition


ICatalogManager::CreateProductDefinition

Use this method to create a new product definition.

Definition

HRESULT ICatalogManager::CreateProductDefinition(
BSTR strDefinitionName
);

Parameters

strDefinitionName

[in] A BSTR that contains the name of the new product definition.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_DEFINITION_EXISTS | 0x8898000A | The specified product definition name already existed.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

Category and product definition names must be globally unique across the entire Product Catalog System. It is not possible to have a category definition and a product definition with the same name.

The initial definition is empty when it is created. To add individual properties to the definition, use the AddDefinitionProperty or AddDefinitionVariantProperty method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CatalogManager Object

ICatalogManager::AddDefinitionProperty

ICatalogManager::AddDefinitionVariantProperty

ICatalogManager::CreateCategoryDefinition

ICatalogManager::DeleteDefinition


ICatalogManager::CreateProperty

Use this method to create a new property.

Definition

HRESULT ICatalogManager::CreateProperty(
BSTR strPropertyName,
CatalogDataTypeEnum eDataType,
VARIANT varMaxLength,
_Recordset** ppRSProperty
);

Parameters

strPropertyName

[in] A BSTR that contains the name of the new property. This parameter can only contain characters that are acceptable in XML tags.

eDataType

[in] An enumeration value that specifies the data type of the new property. See the Remarks section for valid values.

varMaxLength

[in, optional] A VARIANT that contains the maximum length for the property. Even though this parameter is an optional value it must be given if the data type of the property is cscString. Properties of data type cscEnumeration have a fixed default value of 128, which cannot be changed. Properties of data type cscFilePath have a fixed default value of 256, which cannot be changed.

ppRSProperty

[out, retval] A pointer used to return a Recordset object that will contain the new property.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_PROP_EXISTS | 0x88980003 | The specified property name already existed. Property names must be unique across the Product Catalog System.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The ppRSProperty parameter contains valid data only if the property was accessed successfully.

This method returns a single row Recordset object containing the newly created property. For more information about the fields in this Recordset object, see PropertyAttribute Recordset.

The following table shows the values of the CatalogDataTypeEnum enumeration, their associated names, and describes their use.

Name | Value | Description
cscInteger | 0 | Indicates an exact numeric value that holds whole numbers from –2[31] (-2,147,483,648) <= n <= 2[31] –1 (2,147,483,647)
cscBigInteger | 1 | Indicates an exact numeric value with precision 19 (if signed) or 20 (if unsigned) and scale 0 (signed: –2[63] <= n <= 2[63] – 1, unsigned: 0 <= n <= 2[64] – 1) [3], [9].
cscFloat | 2 | Indicates a positive or negative floating-point number. The range of positive values is approximately 2.23E –308 through 1.79E 308 and the range of negative values is approximately –2.23E –308 through –1.79E 308.
cscDouble | 3 | Indicates a positive or negative floating-point number. The range of positive values is approximately 2.23E –308 through 1.79E 308 and the range of negative values is approximately –2.23E –308 through –1.79E 308.
cscBoolean | 4 | Indicates a Boolean (bit), holds either a 1 or 0. Integer values other than 1 or 0 are accepted but are always interpreted as 1.
cscString | 5 | Indicates a variable-length character string with a maximum string length of 255 characters.
cscDateTime | 6 | Indicates a Microsoft SQL Server DateTime data type.
cscCurrency | 7 | Indicates a Microsoft SQL Server Money data type.
cscFilePath | 8 | Indicates a String that holds a file path.
cscEnumeration | 9 | Indicates an Integer associated with a defined constant.
cscInvalid | -1 | Reserved for future use.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CatalogManager Object

ICatalogManager::DeleteProperty

ICatalogManager::GetPropertyAttributes

ICatalogManager::SetPropertyAttributes


ICatalogManager::get_CustomCatalogs

The CustomCatalogs property is a read-only recordset that describes the custom catalogs in the Product Catalog System, and the base catalogs on which they are based.

Definition

HRESULT ICatalogManager::get_CustomCatalogs(
_Recordset** CustomCatalogs
);

Parameters

CustomCatalogs

[out, retval] A pointer to a Recordset object used to return descriptions of the custom catalogs in the Product Catalog System.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The CustomCatalogs parameter contains valid data only if the property was accessed successfully.

The Recordset object contains the following fields:

Field | Data Type | Description
CustomCatalogName | String, 128 Characters | None
CatalogName | String, 128 Characters | None
CustomCatalogID | Integer | The number that uniquely identifies a catalog.
TimeStamp | timestamp | None

The Recordset object is sorted on the CustomCatalogName field.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CatalogManager Object

ICatalogManager::get_Catalogs


ICatalogManager::DeleteCatalog

Use this method to delete a catalog and derived custom catalogs from the Product Catalog System.

Definition

HRESULT ICatalogManager::DeleteCatalog(
BSTR strCatalogName
);

Parameters

strCatalogName

[in] A BSTR that contains the name of the catalog to be deleted.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_CATALOG_DOESNT_EXIST | 0x88980002 | The specified catalog did not exist.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Note

  • This method cannot be called in a transacted object. This method involves the creation, deletion, or updating of free text indexes. SQL Server does not allow these operations in a transaction.

  • Deleting a catalog will also delete and custom catalogs that were derived from it.

See Also

CatalogManager Object

ICatalogManager::CreateCatalog


ICatalogManager::DeleteDefinition

Use this method to delete a definition from the Product Catalog System.

Definition

HRESULT ICatalogManager::DeleteDefinition(
BSTR strDefinitionName,
VARIANT_BOOL fForceDelete
);

Parameters

strDefinitionName

[in] A BSTR that contains the name of the definition to be deleted.

fForceDelete

[in, optional, defaultvalue (0)] A VARIANT_BOOL that specifies whether to force a deletion. A value of True indicates that the definition should be deleted even if it is currently being used in a catalog. A value of False indicates that the definition should only be deleted if it is not currently being used in a catalog.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_DEFINITION_DOESNT_EXIST | 0x8898000B | The definition you specified did not exist.
E_CAT_DEFINITION_USED_IN_CATALOG | 0x8898000C | This error is only returned when the fForceDelete parameter was set to False and the definition was already used in a catalog.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

Use a value of True for the fForceDelete parameter with caution, as the category or product definition, and all categories and products that are based on them in all catalogs will also be deleted. This could result in data loss.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CatalogManager Object

ICatalogManager::CreateCategoryDefinition

ICatalogManager::CreateProductDefinition


ICatalogManager::DeleteProperty

Use this method to delete a property from the Product Catalog System.

Definition

HRESULT ICatalogManager::DeleteProperty(
BSTR strPropertyName
);

Parameters

strPropertyName

[in] A BSTR that contains the name of the property to be deleted.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_PROP_DOESNT_EXIST | 0x88980005 | The specified property did not exist.
E_CAT_PROP_IS_ID | 0x88980011 | The specified property is used as either the ProductID property or VariantID property in one or more catalogs. These properties are defined when the catalog is created and cannot be removed.
E_CAT_PROP_STILL_IN_DEF | 0x88980004 | The specified property is used in a definition. Call the RemoveDefinitionProperty method to remove the property from the definition before calling this method.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CatalogManager Object

ICatalogManager::CreateProperty


ICatalogManager::ExportCSV

Use this method to export catalog data to a comma-separated values format file.

Definition

HRESULT ICatalogManager::ExportCSV(
BSTR strCSVDestination,
BSTR strCatalogToExport
VARIANT_BOOL fRunSynchronously
);

Parameters

strCSVDestination

[in] A BSTR that contains the full path and file name of the export file to be created.

strCatalogToExport

[in] A BSTR that contains the name of the catalog to export.

fRunSynchronously

[in, defaultvalue (0)] A VARIANT_BOOL that specifies whether the method should be run synchronously. A value of True indicates that the method will not return until the export is completed. A value of False indicates that the method will return immediately after spawning the export thread.

Return Values

This method returns an HRESULT indicating it completed successfully.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_IMPORT_IN_PROGRESS | 0x88980025 | There was an existing import method call that had not yet completed. This method cannot run while an import is in progress.
E_CAT_FILE_CREATION_FAILED | 0x88980018 | The method was unable to create the output file.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The ExportCSV method can be used to output product data from the Product Catalog System in a format that can be used in other programs, such as Microsoft Excel.

This method can only output product data from one catalog at a time.

The comma-separated values (CSV) file generated only contains products. The categories, relationships, and hierarchy are not written to the CSV file.

Note

  • This method runs in a separate thread. Prior to spawning the thread, it checks that there is not an existing ExportCSV, ExportXML, ImportCSV or ImportXML method in progress. Once the new thread is spawned, this method returns immediately, if fRunSynchronously is False, with no errors. Any errors that occurred while importing the catalog are logged to the Windows NT Event Log. Use the Windows Event Viewer to view the Windows NT Event Log.

  • If there is a temporary loss of the SQL connection, longer than two minutes, an import or export will be aborted. Other methods should work after the interruption.

Caution

  • Changes made to the catalog while an export is in progress may or may not be reflected in the output file. Additions and deletions made during the export could result in a corrupt file. Changes should be avoided during an export.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CatalogManager Object

ICatalogManager::ExportXML

ICatalogManager::ImportCSV


ICatalogManager::ExportXML

Use this method to export catalog data to an Extensible Markup Language (XML) file.

Definition

HRESULT ICatalogManager::ExportXML(
BSTR strXMLFilePath,
VARIANT strCatalogsToExport
VARIANT_BOOL fRunSynchronously
);

Parameters

strXMLFilePath

[in] A BSTR that contains the path and file name of the XML file to be created.

strCatalogsToExport

[in, optional] A VARIANT that contains the catalogs to export. See the Remarks section for more information.

fRunSynchronously

[in, defaultvalue (0)] A VARIANT_BOOL that specifies whether the method should be run synchronously. A value of True indicates that the method will not return until the export is completed. A value of False indicates that the method will return immediately after spawning the export thread.

Return Values

This method returns an HRESULT indicating it completed successfully.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_IMPORT_IN_PROGRESS | 0x88980025 | There was an existing import method call that had not yet completed. This method cannot run while an import is in progress.
E_CAT_FILE_CREATION_FAILED | 0x88980018 | The method was unable to create the output file.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

If the parameter strCatalogsToExport is missing, or contains an empty string, then all catalogs are exported. Otherwise the parameter strCatalogsToExport is a comma-separated list of catalog names to be exported.

Note

  • This method runs in a separate thread. Prior to spawning the thread, it checks that there is not an existing ExportCSV, ExportXML, ImportCSV or ImportXML method in progress. Once the new thread is spawned, this method returns immediately, if fRunSynchronously is False, with no errors. Any errors that occurred while importing the catalog are logged to the Windows NT Event Log. Use the Windows Event Viewer to view the Windows NT Event Log.

  • If there is a temporary loss of the SQL connection, longer than two minutes, an import or export will be aborted. Other methods should work after the interruption.

Caution

  • Changes made to the catalog while an export is in progress may or may not be reflected in the output file. Additions and deletions made during the export could result in a corrupt file. Changes should be avoided during an export.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CatalogManager Object

ICatalogManager::ExportCSV

ICatalogManager::ImportXML


ICatalogManager::FreeTextSearch

Use this method to perform a free-text search of catalogs.

Definition

HRESULT ICatalogManager::FreeTextSearch(
BSTR strPhrase,
VARIANT strCatalogsToSearch,
VARIANT eClassTypeRequired,
VARIANT strPropertiesToReturn,
VARIANT strPropertyToSortOn,
VARIANT_BOOL fSortAscending,
VARIANT lStartingRecord,
VARIANT lRecordsToRetrieve,
VARIANT* plTotalRecordsInQuery,
_Recordset** ppRSResult
);

Parameters

strPhrase

[in] A BSTR that contains the search phrase.

strCatalogsToSearch

[in, optional] A VARIANT that contains the catalogs to search in a comma-separated list. An empty string indicates search all catalogs.

eClassTypeRequired

[in, optional] A VARIANT that contains the catalog class desired. Valid values are from the CatalogClassTypeEnum enumeration, and are described in the Remarks section below.

strPropertiesToReturn

[in, optional] A VARIANT that contains the properties to return. This is a comma delimited String.

strPropertyToSortOn

[in, optional] VARIANT that contains the property on which to sort. If not included, the returned recordset will be unsorted.

fSortAscending

[in, defaultvalue (-1)] A VARIANT_BOOL that specifies whether to sort in ascending or descending order. A value of True indicates that the returned recordset will be sorted in ascending order. A value of False indicates that the returned recordset will be sorted in descending order.

lStartingRecord

[in, optional] A VARIANT that contains the number of the starting record to retrieve. This is an offset from the first record.

lRecordsToRetrieve

[in, optional] A VARIANT that contains the number of records to retrieve starting from the starting record.

plTotalRecordsInQuery

[out, optional] A pointer to a VARIANT used to return the number of records returned in the search.

ppRSResult

[out, retval] A pointer to a _Recordset object that will be used to return the query results.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_MULTI_CAT_QUERY_NEEDS_PROPS | 0x8898000F | The strPropertiesToReturn parameter must be specified if the search is done across multiple catalogs.
E_CAT_NO_CATALOGS | 0x88980013 | There were no catalogs in the Product Catalog System.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The plTotalRecordsInQuery and ppRSResult parameters contain valid data only if the method completes successfully.

The FreeTextSearch method is used to perform arbitrary lexical comparisons on words or phrases in one or more catalogs. The FreeTextSearch functionality in the Product Catalog System is based on full text indexing in SQL Server 2000, and therefore, inherits keywords and operators from SQL Server 2000 for controlling the free text search.

The following table shows the values of the CatalogClassTypeEnum enumeration, their associated names, and describes their use.

Name | Value | Description
cscCategoryClass | 1 | Requests category data.
cscProductVariantClass | 2 | Requests product variant data.
cscProductClass | 4 | Requests product data.
cscProductFamilyClass | 8 | Requests product family data.
cscProductFamilyForVariantsClass | 16 | Requests family for variant data, which means the product family of a product variant is being requested.
CscProductVariantsForFamily | 32 | Requests variants for family data, which means that all of the product variants for a product family are being requested.

CatalogClassTypeEnum values can be combined in the eClassTypeRequired parameter with logical OR operators, so that specifying cscProductClass OR cscProductVariantClass will return both product and product variant data.

The programming rules regarding the strPropertiesToReturn parameter vary depending on whether a single catalog name is passed in the strCatalogsToSearch parameter or whether multiple catalog names are passed. When a single catalog name is passed, the strPropertiesToReturn parameter is optional and defaults to all properties. When multiple catalog names are passed, the strPropertiesToReturn parameter is required.

If no value is specified for the strPropertiesToReturn parameter the method returns all fields in the specified catalog, otherwise it returns only the fields specified in the strPropertiesToReturn parameter.

For more information, see CatalogProduct Recordset.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CatalogManager Object

ICatalogManager::Query


ICatalogManager::GetCatalog

Use this method to retrieve a specified catalog from the Product Catalog System.

Definition

HRESULT ICatalogManager::GetCatalog(
BSTR strCatalogName,
IProductCatalog** ppCatalog
);

Parameters

strCatalogName

[in] A BSTR that contains the name of the catalog to be retrieved.

ppCatalog

[out] A pointer to an IProductCatalog interface used to return the ProductCatalog object.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following standard COM error value has a particular meaning in the context of this method:

S_FALSE

The catalog specified did not exist.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The ppCatalog parameter contains valid data only if the method completes successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CatalogManager Object

ICatalogManager::CreateCatalog

ICatalogManager::DeleteCatalog


ICatalogManager::GetDefinitionProperties

Use this method to return the properties of the specified catalog or product definition.

Definition

HRESULT ICatalogManager::GetDefinitionProperties(
BSTR strDefinitionName,
_Recordset** ppRSProperties
);

Parameters

strDefinitionName

[in] A BSTR that contains the name of the definition whose properties will be returned.

ppRSProperties

[out, retval] A pointer to a _Recordset object used to return the properties of the definition.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_DEFINITION_DOESNT_EXIST | 0x8898000B | The specified definition did not exist.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The ppRSProperties parameter contains valid data only if the method completes successfully.

The returned recordset contains the following fields:

Field | Data Type | Description
DefinitionID | Integer | The number that uniquely identifies the definition.
PropertyName | String, 256 Characters | None
PropertyOrder | Integer | None
PropertyType | Integer | Zero (0) indicates product or category, one (1) indicates product variant.
TimeStamp | timestamp | None

The rows of the recordset are sorted on the PropertyOrder field.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CatalogManager Object

ICatalogManager::AddDefinitionProperty

ICatalogManager::AddDefinitionVariantProperty

ICatalogManager::RemoveDefinitionProperty


ICatalogManager::GetPropertyAttributes

Use this method to return the attributes of the specified property.

Definition

HRESULT ICatalogManager::GetPropertyAttributes(
BSTR strPropertyName,
_Recordset** ppRSAttributes
);

Parameters

strPropertyName

[in] A BSTR that contains the name of the property whose attributes will be returned.

ppRSAttributes

[out] A pointer to a _Recordset object used to return the attributes of the property.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The ppRSAttributes parameter contains valid data only if the method completes successfully.

This method returns a single row Recordset object containing the requested property. For more information about the fields in this Recordset object, see PropertyAttribute Recordset.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CatalogManager Object

ICatalogManager::SetPropertyAttributes


ICatalogManager::GetPropertyValues

Use this method to return the list of values defined for an enumeration property.

Definition

HRESULT ICatalogManager::GetPropertyValues(
BSTR strPropertyName,
_Recordset** ppRSPropertyValues
);

Parameters

strPropertyName

[in] A BSTR that contains the name of the enumeration property for which the defined values will be returned.

ppRSPropertyValues

[out, retval] A pointer to a _Recordset object used to return the property values.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The ppRSPropertyValues parameter contains valid data only if the method completes successfully.

The returned recordset contains the following fields:

Field | Data Type | Description
PropertyName | String 256 Characters | None
Value | String 256 Characters | None

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CatalogManager Object

ICatalogManager::AddPropertyValue

ICatalogManager::RemovePropertyValue


ICatalogManager::ImportCSV

Use this method to import a comma-separated-value (CSV) format file as catalog data.

Definition

HRESULT ICatalogManager::ImportCSV(
BSTR strCSVFileSource,
BSTR strProductIDColumnName,
BSTR strPriceColumnName,
BSTR strCatalogName,
VARIANT_BOOL fUpdateOnly
VARIANT_BOOL fRunSynchronously
);

Parameters

strCSVFileSource

[in] A BSTR that contains the path and file name of the CSV file to import.

strProductIDColumnName

[in] A BSTR that contains the name of the column that provides a unique ID for products to be imported into the catalog.

strPriceColumnName

[in] A BSTR that contains the name of the column in the CSV file containing the product prices.

strCatalogName

[in] A BSTR that contains the name of the catalog into which the CSV file will be imported. The name of the catalog cannot begin with "#" or consist solely of spaces.

fUpdateOnly

[in, defaultvalue (0)] A VARIANT_BOOL that specifies whether to update an existing catalog or create a new one. A value of True indicates that if the system contains a catalog whose name is the same as the one specified in the strCatalogName parameter, it will be updated with the imported data. A value of False indicates to delete the catalog if it already exists and create a new one with the imported data.

fRunSynchronously

[in, defaultvalue (0)] A VARIANT_BOOL that specifies whether the method should be run synchronously. A value of True indicates that the method will not return until the import is completed. A value of False indicates that the method will return immediately after spawning the import thread.

Return Values

This method returns an HRESULT indicating it completed successfully.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_IMPORT_IN_PROGRESS | 0x88980025 | There was an existing import method call that had not yet completed. This method cannot run while an import is in progress.
E_CAT_FILE_OPEN_ERROR | 0x88980020 | The method was unable to open the file.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

If the parameter strCatalogName specifies a catalog that does not exist, a new catalog will be created and the value of the fUpdateOnly parameter is ignored.

The ImportCSV method is used to bring existing data from a wide variety of sources into the Product Catalog System. The CSV file must conform to the following format:

  • The first row of data consists of column names, separated by commas. Rows are delimited by new lines in the text file.

  • Each subsequent row (called a data row) must have the same number of commas as the very first row. In other words, all columns in the CSV must be defined by the first row.

  • All items in the CSV file (one row per item) are assumed to be products, and are created from a common product definition. If no product definition exists in the destination catalog then one will be created during the import process.

  • Each item must specify a value for the column specified as the ProductID column, as well as for the column specified as the Price column.

  • Missing data is represented my two adjacent commas.

Notes

  • This method runs in a separate thread. Prior to spawning the thread, it checks that the specified file can be opened and that there is not an existing ExportCSV, ExportXML, ImportCSV or ImportXML method in progress. Once the new thread is spawned, this method returns immediately, if fRunSynchronously is False, with no errors. Any errors that occurred while importing the catalog are logged to the Windows NT Event Log. Use the Windows Event Viewer to view the Windows NT Event Log.

  • This method cannot be called in a transacted object. This method involves the creation, deletion, or updating of free text indexes. SQL Server does not allow these operations in a transaction.

  • If there is a temporary loss of the SQL connection, longer than two minutes, an import or export will be aborted. Other methods should work after the interruption.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CatalogManager Object

ICatalogManager::ExportCSV

ICatalogManager::ImportXML


ICatalogManager::ImportXML

Use this method to import an Extensible Markup Language (XML) file as catalog data.

Definition

HRESULT ICatalogManager::ImportXML(
BSTR strXMLFilePath,
VARIANT_BOOL fUpdateOnly
VARIANT_BOOL fRunSynchronously
);

Parameters

strXMLFilePath

[in] A BSTR that contains the path and file name of the XML file to import.

fUpdateOnly

[in, defaultvalue (0)] A VARIANT_BOOL that specifies whether to update an existing catalog or create a new one. A value of True indicates that if the system contains a catalog whose name is the same as the one specified in the strCatalogName parameter, it will be updated with the imported data. A value of False indicates to delete the catalog if it already exists and create a new one with the imported data.

fRunSynchronously

[in, defaultvalue (0)] A VARIANT_BOOL that specifies whether the method should be run synchronously. A value of True indicates that the method will not return until the import is completed. A value of False indicates that the method will return immediately after spawning the import thread.

Return Values

This method returns an HRESULT indicating it completed successfully.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_IMPORT_IN_PROGRESS | 0x88980025 | There was an existing import method call that had not yet completed. This method cannot run while an import is in progress.
E_CAT_FILE_OPEN_ERROR | 0x88980020 | The method was unable to open the file.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

When performing a partial or delta import (when updating an existing catalog by importing new or changed catalog data), it is important that the schema of the data being imported matches the schema of the existing catalog. For more information about the catalog schema, see Import Semantic.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Note

  • This method runs in a separate thread. Prior to spawning the thread, it checks that the specified file can be opened and that there is not an existing ExportCSV, ExportXML, ImportCSV or ImportXMLmethod in progress. Once the new thread is spawned, this method returns immediately, if fRunSynchronously is False, with no errors. Any errors that occurred while importing the catalog are logged to the Windows NT Event Log. Use the Windows Event Viewer to view the Windows NT Event Log.

  • This method cannot be called in a transacted object. This method involves the creation, deletion, or updating of free text indexes. SQL Server does not allow these operations in a transaction.

  • If there is a temporary loss of the SQL connection, longer than two minutes, an import or export will be aborted. Other methods should work after the interruption.

  • The names of catalogs in the source file cannot begin with "#" or consist solely of spaces.

  • If a property existing in the catalog has one type and the property of the same name existing in the import file has a different type, the import will fail. For example, the catalog has a SKU property that is a string, and the XML file being imported has a SKU property that is an integer. This will cause an error.

See Also

CatalogManager Object

ICatalogManager::ExportXML

ICatalogManager::ImportCSV


ICatalogManager::Initialize

Use this method to initialize a CatalogManager object. This method should be called once before calling any other methods or properties.

Definition

HRESULT ICatalogManager::Initialize(
BSTR strConfigString,
VARIANT_BOOL fIsADOConnectionString
);

Parameters

strConfigString

[in] A BSTR that contains the configuration string.

fIsADOConnectionString

[in, defaultvalue (0)] A VARIANT_BOOL that determines whether the strConfigString parameter refers to an ActiveX Data Object (ADO) connection string or a site name. A value of True indicates an ADO connection string. A value of False indicates a site name.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_CATMGR_ALREADY_INITIALIZED | 0x88980062 | The CatalogManager objects was already initialized.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CatalogManager Object


ICatalogManager::get_ProductDefinitions

The ProductDefinitions property is a read-only Recordset object that contains the names of all the product definitions in the Product Catalog System.

Definition

HRESULT ICatalogManager::get_ProductDefinitions(
_Recordset** ProductDefinitions
);

Parameters

ProductDefinitions

[out, retval] A pointer to a _Recordset object used to return the product definitions.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The ProductDefinitions parameter contains valid data only if the property was accessed successfully.

The returned recordset will contain a single field called DefinitionName and one row for each product definition in the Product Catalog System. This field is a 128 character String.

If no product definitions are currently in the Product Catalog System, then the EOF property of the returned recordset will be set to VARIANT_TRUE.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CatalogManager Object

ICatalogManager::CreateProductDefinition

ICatalogManager::DeleteDefinition


ICatalogManager::get_Properties

The Properties property is a read-only recordset that returns the name of each property that currently exists in the Product Catalog System. If the catalog name is specified, only properties used in that catalog are returned.

Definition

HRESULT ICatalogManager::Properties(
VARIANT strCatalogName,
_Recordset** ppRSProperties
);

Parameters

strCatalogName

[in, optional] A VARIANT that contains the name of the catalog for which the properties are returned. If this optional parameter is omitted, all properties are returned.

ppRSProperties

[out] A pointer to a _Recordset object used to return the properties.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The Properties parameter contains valid data only if the property was accessed successfully.

This method returns a Recordset object containing a row for each property returned. For more information about the fields in this Recordset object, see PropertyAttribute Recordset.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CatalogManager Object

ICatalogManager::CreateProperty

ICatalogManager::DeleteProperty


ICatalogManager::Query

Use this method to perform queries against product, variant, and category data in one or more catalogs.

Definition

HRESULT ICatalogManager::Query(
BSTR strPhrase,
VARIANT strCatalogsToSearch,
VARIANT eClassTypeRequired,
VARIANT strPropertiesToReturn,
VARIANT strPropertyToSortOn,
VARIANT_BOOL fSortAscending,
VARIANT lStartingRecord,
VARIANT lRecordsToRetrieve,
VARIANT* plTotalRecordsInQuery,
_Recordset** ppRSResult
);

Parameters

strPhrase

[in] A BSTR that contains the search phrase.

strCatalogsToSearch

[in, optional] A VARIANT that contains the catalogs to search as a comma-separated list. An empty string indicates search all catalogs.

eClassTypeRequired

[in, optional] A Variant that contains the catalog class desired. Valid values are from the CatalogClassTypeEnum enumeration, and are described in the Remarks section below.

strPropertiesToReturn

[in, optional] A VARIANT that contains the properties to return as a comma-separated list.

strPropertyToSortOn

[in, optional] A VARIANT that contains the property on which to sort.

fSortAscending

[in, defaultvalue (-1)] A VARIANT_BOOL that specifies whether to sort in ascending or descending order. A value of True indicates that the returned recordset will be sorted in ascending order. A value of False indicates that the returned recordset will be sorted in descending order.

lStartingRecord

[in, optional] A VARIANT that contains the starting record to retrieve. This is an offset from the first record.

lRecordsToRetrieve

[in, optional] A VARIANT that contains the number of records to retrieve, beginning from the starting record.

plTotalRecordsInQuery

[out, optional] A pointer to a VARIANT used to return the total number of records matching the query.

ppRSResult

[out, retval] A pointer to a _Recordset object used to return the search results.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_MULTI_CAT_QUERY_NEEDS_PROPS | 0x8898000F | The strPropertiesToReturn parameter must be specified if the search is done across multiple catalogs.
E_CAT_NO_CATALOGS | 0x88980013 | There were no catalogs in the Product Catalog System.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The plTotalRecordsInQuery and ppRSResult parameters contain valid data only if the method completes successfully.

The Query method is used to perform arbitrary queries against product, product-variant, and category data in one or more catalogs. The strPhrase parameter is very similarly to the ADO recordset Filter property. Simple queries should follow the key-operator-value convention (for example, length < 100). Queries whose value is a String data type should enclose that value in single quotes (for example, color = 'Blue').

More sophisticated queries can be constructed by using the AND and OR operators to group multiple clauses, such as (level > 10) OR (Name = 'Bob' AND Title='CPA').

The programming rules regarding the strPropertiesToReturn parameter vary depending if a single catalog name is passed in the strCatalogsToSearch parameter, or if multiple catalog names are passed. When a single catalog name is passed, the strPropertiesToReturn parameter is optional and defaults to all properties. When multiple catalog names are passed, the strPropertiesToReturn parameter is required.

The following table shows the values of the CatalogClassTypeEnum enumeration, their associated names, and describes their use.

Name | Value | Description
cscCategoryClass | 1 | Requests category data.
cscProductVariantClass | 2 | Requests product variant data.
cscProductClass | 4 | Requests product data.
cscProductFamilyClass | 8 | Requests product family data.
cscProductFamilyForVariantsClass | 16 | Requests family for variant data, which means the product family of a product variant is being requested.
CscProductVariantsForFamily | 32 | Requests variants for family data, which means that all of the product variants for a product family are being requested.

CatalogClassTypeEnum values can be combined in the eClassTypeRequired parameter with logical OR operators, so that specifying cscProductClass OR cscProductVariantClass will return both product and product variant data.

If no value is specified for the strPropertiesToReturn parameter the method returns all fields in the specified catalog, otherwise it returns only the fields specified in the strPropertiesToReturn parameter.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CatalogManager Object

ICatalogManager::FreeTextSearch


ICatalogManager::RemoveDefinitionProperty

Use this method to remove the specified property or variant property from the specified definition.

Definition

HRESULT ICatalogManager::RemoveDefinitionProperty(
BSTR strDefinitionName,
BSTR strPropertyName
);

Parameters

strDefinitionName

[in] A BSTR that contains the name of the definition for which the specified property will be removed.

strPropertyName

[in] A BSTR that contains the name of the property to be removed.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_DEFINITION_DOESNT_EXIST | 0x8898000B | The specified definition did not exist.
E_CAT_PROP_NOT_IN_DEFINITION | 0x8898000E | The specified property was not included in this definition.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

When you remove a property from a definition, it is also removed from any products, product-variants, or categories created from that definition.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Caution

  • Use caution when using this method. In most cases, calling this method results in the deletion of data.

  • Removing the last variant property in a product family definition will convert it to a product definition and will remove all existing product variants based on this definition.

See Also

CatalogManager Object

ICatalogManager::AddDefinitionProperty

ICatalogManager::AddDefinitionVariantProperty

ICatalogManager::GetDefinitionProperties


ICatalogManager::RemovePropertyValue

Use this method to remove a defined value from an enumeration property.

Definition

HRESULT ICatalogManager::RemovePropertyValue(
BSTR strPropertyName,
BSTR strLegalValue
);

Parameters

strPropertyName

[in] A BSTR that contains the name of the enumeration property from which the specified value will be removed.

strLegalValue

[in] A BSTR that contains the defined value to be removed as a choice from the specified enumeration property.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_PROP_DOESNT_EXIST | 0x88980005 | The specified property did not exist.
E_CAT_PROP_NOT_ENUM | 0x88980007 | The specified property was not of type cscEnumeration. Call this method only for enumeration type properties.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Caution

  • When a value is removed from an enumeration type property all products that have that property set to that value will have the value changed to NULL.

See Also

CatalogManager Object

ICatalogManager::AddPropertyValue

ICatalogManager::GetPropertyValues


ICatalogManager::RenameDefinition

Use this method to rename a definition.

Definition

HRESULT ICatalogManager::RenameDefinition(
BSTR strOldName,
BSTR strNewName
);

Parameters

strOldName

[in] A BSTR that contains the existing name of the definition.

strNewName

[in] A BSTR that contains the wanted name of the definition.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_DEFINITION_DOESNT_EXIST | 0x8898000B | The specified old definition name did not exist.
E_CAT_DEFINITION_EXISTS | 0x8898000A | A definition with the specified new name already existed.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

This method affects every product and category using the definition.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CatalogManager Object

ICatalogManager::RenameProperty


ICatalogManager::RenameProperty

Use this method to rename a property.

Definition

HRESULT ICatalogManager::RenameProperty(
BSTR strOldPropertyName,
BSTR strNewPropertyName
);

Parameters

strOldPropertyName

[in] A BSTR that contains the existing name of the property.

strNewPropertyName

[in] A BSTR that contains the wanted name of the property.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_PROP_DOESNT_EXIST | 0x88980005 | The specified old property name did not exist.
E_CAT_PROP_EXISTS | 0x88980003 | A property with the specified new property name already existed.
E_CAT_PROP_IS_ID | 0x88980011 | The property name you specified was used as a ProductID or VariantID of a catalog. These properties are specified when a catalog is created and cannot be renamed or deleted.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CatalogManager Object

ICatalogManager::RenameDefinition


ICatalogManager::SetDefinitionProperties

Use this method to change the properties of a category or product definition.

Definition

HRESULT ICatalogManager::SetDefinitionProperties(
BSTR strDefinitionName,
Recordset* pRSProperties,
);

Parameters

strDefinitionName

[in] A BSTR that contains the name of the definition.

pRSProperties

[in] A reference to a _Recordset that specifies the new properties.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_PROP_DOESNT_EXIST | 0x88980005 | There was no property with the name you specified.
E_CAT_PROP_CHANGED | 0x88980006 | The attributes of the property have changed since the property was last read. This error occurs when the sForceUpdate parameter is False, and the attributes were modified after a call to the CreateProperty or GetPropertyAttributes methods.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CatalogManager Object

ICatalogManager::CreateProperty


ICatalogManager::SetPropertyAttributes

Use this method to change the attributes of a property.

Definition

HRESULT ICatalogManager::SetPropertyAttributes(
_Recordset* pRSNewState,
VARIANT fForceUpdate
);

Parameters

pRSNewState

[in] A reference to a _Recordset object that specifies the new attribute values.

fForceUpdate

[in, optional] A VARIANT that specifies whether or not to force an update.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_PROP_CHANGED | 0x88980006 | The attributes of the property have changed since the property was last read. This error occurs when the sForceUpdate parameter is False, and the attributes were modified after a call to the CreateProperty or GetPropertyAttributes methods.
E_CAT_PROP_DOESNT_EXIST | 0x88980005 | There was no property with the name you specified.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

Use a Recordset object returned from either the GetPropertyAttributes method or the CreateProperty method as the pRSNewState parameter so that its timestamp can be compared with the timestamp of the existing property for error detection. You can change all attributes for a property except its data type.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CatalogManager Object

ICatalogManager::CreateProperty

ICatalogManager::GetPropertyAttributes


CatalogSets Object

Use this object to work with catalog sets in the catalog management system. Catalog sets allow you to present different collections of catalogs to different users and organizations.

ProgID: | Commerce.CatalogSets (Externally creatable)
COM Class Name: | CatalogSets
COM Interface Name: | _CatalogSets
Interface ID Constant: | None
Header File: | None
Type Library Name: | Microsoft Commerce 2000 Catalog Sets Type Library
DLL Name: | CatalogSets.dll
Threading Model: | Apartment

In C++, use the _CatalogSets interface to access the properties and methods of the CatalogSets object.

Because this object is primarily intended for use within ASP script, access from C++ will not be common.

The methods of the CatalogSets object are shown in the following table.

Method | Description
CreateCatalogSet | Creates a new catalog set.
DeleteCatalogSet | Deletes the specified catalog set.
GetCatalogs | Returns a list of all catalogs.
GetCatalogSetIDForUser | Returns the CatalogSetID for a user.
GetCatalogSetInfo | Returns information about the specified catalog set.
GetCatalogSets | Returns a list of all catalog sets.
GetCatalogsForUser | Returns a list of catalogs associated with the specified user.
GetCatalogsInCatalogSet | Returns a list of catalogs associated with the specified catalog set.
GetCatalogsNotInCatalogSet | Returns a list of all catalogs not associated with the specified catalog set.
Initialize | Initializes the CatalogSets object.
RemoveCatalogFromCatalogSets | Remove a catalog from all catalog sets.
UpdateCatalogSet | Allows modification of an existing catalog set.


_CatalogSets::CreateCatalogSet

Use this method to create a new catalog set in the catalog database.

Definition

HRESULT _CatalogSets::CreateCatalogSet(
BSTR CatalogSetName,
BSTR CatalogSetDescription,
VARIANT_BOOL bWildCard,
_Recordset* CatalogNamesRS,
BSTR* CatalogSetID
);

Parameters

CatalogSetName

[in] A BSTR that contains a name for the new catalog set. The maximum length is 128 characters.

CatalogSetDescription

[in] A BSTR that contains a description of the new catalog set.

bWildCard

[in] A VARIANT_BOOL that indicates whether this catalog set should automatically include all catalogs, including any new catalogs that might be created in the future. A value of True indicates that this catalog set includes all existing catalogs. A value of False indicates that this catalog set only includes a specific set of catalogs.

CatalogNamesRS

[in, optional] A pointer to an ActiveX Data Objects (ADO) _Recordset object that specifies the catalogs to be included in the new catalog set. The _Recordset object should contain a single column named CatalogName, and one row per catalog to be included. If the bWildCard parameter is True, then this parameter will be ignored.

CatalogSetID

[out, retval] A pointer to a BSTR used to return the automatically generated ID (GUID) of the new catalog set.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The CatalogSetID parameter contains valid data only if the new catalog set was created successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CatalogSets Object


_CatalogSets::DeleteCatalogSet

Use this method to delete an existing catalog set from the Catalog database.

Definition

HRESULT _CatalogSets::DeleteCatalogSet(
BSTR CatalogSetID
);

Parameters

CatalogSetID

[in] A BSTR that contains the GUID of the catalog set to be deleted.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

Deleting a catalog set does not delete the catalog set ID. Referencing an invalid catalog set ID will prevent access to the solution sites.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CatalogSets Object


_CatalogSets::GetCatalogs

Use this method to return a list of all catalogs.

Definition

HRESULT _CatalogSets::GetCatalogs(
_Recordset** unnamed parameter
);

Parameters

unnamed parameter

[out, retval] A pointer to hold the reference to the returned _Recordset object, which will contain the unnamed parameter.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The unnamed parameter contains valid data only if the method completes successfully.

The Recordset object returned by this method has a single 128 character field, named CatalogName.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CatalogSets Object


_CatalogSets::GetCatalogSetIDForUser

Use this method to return the CatalogSetID for a specific user.

Definition

HRESULT _CatalogSets::GetCatalogSetIDForUser(
IDispatch* objProfileService,
BSTR user_id,
BSTR defaultCatalogSetID,
VARIANT* unnamed parameter
);

Parameters

objProfileService

[in] A pointer to the IDispatch interface to the ProfileService object.

user_id

[in] A BSTR that contains the user ID.

defaultCatalogSetID

[in] A BSTR that contains the default catalog set ID.

unnamed parameter

[out, retval] A pointer to a VARIANT used to return the catalog set ID.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The unnamed parameter contains valid data only if the method completes successfully.

If the user defined in the objProfileService parameter has a catalog set associated with it, this method returns that ID; if not, it returns the catalog set associated with the user organization. If this catalog set does not exist, it returns the value supplied in the defaultCatalogSetID parameter.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CatalogSets Object

ProfileService Object


_CatalogSets::GetCatalogSetInfo

Use this method to return the basic properties for a catalog set.

Definition

HRESULT _CatalogSets::GetCatalogSetInfo(
BSTR CatalogSetID,
_Recordset** unnamed parameter
);

Parameters

CatalogSetID

[in] A BSTR that contains the catalog set ID, a GUID.

unnamed parameter

[out, retval] A pointer to hold the reference to the returned _Recordset object, which will contain the unnamed parameter.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The unnamed parameter contains valid data only if the method completes successfully.

This method returns a forward-only Recordset object with a single row and the following fields:

Field | Type | Description
CatalogSetID | GUID | None
CatalogSetName | String, maximum of 255 characters | None
CatalogSetDescription | String, maximum of 255 characters | None
bWildCard | Integer | A Boolean that indicates whether this catalog set automatically includes all catalogs, including any new catalogs that might be created in the future. A value of True indicates that this catalog set includes all existing catalogs. A value of False indicates that this catalog set only includes a specific set of catalogs.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CatalogSets Object


_CatalogSets::GetCatalogSets

Use this method to return a list of all catalog sets.

Definition

HRESULT _CatalogSets::GetCatalogSets(
_Recordset** unnamed parameter
);

Parameters

unnamed parameter

[out, retval] A pointer to hold the reference to the returned _Recordset object, which will contain the unnamed parameter.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The unnamed parameter contains valid data only if the method completes successfully.

This method returns a forward-only Recordset object with a row for each catalog set and the following fields:

Field | Type | Description
CatalogSetID | GUID | None
CatalogSetName | String, 255 characters | None
CatalogSetDescription | String, 255 characters | None
bWildCard | Integer | A Boolean that indicates whether this catalog set automatically includes all catalogs, including any new catalogs that might be created in the future. A value of True indicates that this catalog set includes all existing catalogs. A value of False indicates that this catalog set only includes a specific set of catalogs.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CatalogSets Object


_CatalogSets::GetCatalogsForUser

Use this method to return the list of catalogs that have been assigned to a particular user through the catalog set specified in their profile.

Definition

HRESULT _CatalogSets::GetCatalogsForUser(
IDispatch* objProfileService,
BSTR user_id,
BSTR defaultCatalogSetID,
_Recordset** unnamed parameter
);

Parameters

objProfileService

[in] A pointer to the IDispatch interface to the profile service.

user_id

[in] A BSTR that contains the user ID.

defaultCatalogSetID

[in] A BSTR that contains the default catalog set ID.

unnamed parameter

[out, retval] A pointer to hold the reference to the returned _Recordset object, which will contain the unnamed parameter.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The unnamed parameter contains valid data only if the method completes successfully.

This method returns a Recordset object with a row for each catalog in the catalog set associated with the user profile in the user_id parameter and the following fields:

Field | Type | Description
CatalogName From the CatalogSet_Catalogs table. | String maximum of 255 characters | None
CatalogName From the CatalogGlobal table. | String maximum of 128 characters | None

If the user profile object passed to this method has not been initialized, the object will return the default catalog set.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CatalogSets Object


_CatalogSets::GetCatalogsInCatalogSet

Use this method to return the catalogs that are included in a particular catalog set.

Definition

HRESULT _CatalogSets::GetCatalogsInCatalogSet(
BSTR CatalogSetID,
_Recordset** unnamed parameter
);

Parameters

CatalogSetID

[in] A BSTR that contains the catalog set ID.

unnamed parameter

[out, retval] A pointer to hold the reference to the returned _Recordset object, which will contain the unnamed parameter.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The unnamed parameter contains valid data only if the method completes successfully.

This method returns a Recordset object with a row for each catalog in the catalog set and the following fields:

Field | Type | Description
CatalogName From the CatalogSet_Catalogs table. | String maximum of 255 characters | None
CatalogName From the CatalogGlobal table. | String maximum of 128 characters | None

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CatalogSets Object


_CatalogSets::GetCatalogsNotInCatalogSet

Use this method to return the catalogs that are not included in a specified catalog set.

Definition

HRESULT _CatalogSets::GetCatalogsNotInCatalogSet(
BSTR CatalogSetID,
_Recordset** unnamed parameter
);

Parameters

CatalogSetID

[in] A BSTR that contains the catalog set ID.

unnamed parameter

[out, retval] A pointer to hold the reference to the returned _Recordset, which will contain the unnamed parameter.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The unnamed parameter contains valid data only if the method completes successfully.

The Recordset object returned by this method has a single 128 character field, named CatalogName.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CatalogSets Object


_CatalogSets::Initialize

Use this method to initialize a new CatalogSet object.

Definition

HRESULT _CatalogSets::Initialize(
BSTR CatalogConnectionString,
BSTR TransactionConfigConnectionString
);

Parameters

CatalogConnectionString

[in] A BSTR that contains the catalog connection string.

TransactionConfigConnectionString

[in] A BSTR that contains the transaction configuration connection string. Not used

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Note

  • The TransactionConfigConnectionString parameter is required, but not used. The contents of the String are ignored. This parameter is reserved for future use.

See Also

CatalogSets Object


_CatalogSets::RemoveCatalogFromCatalogSets

Use this method to remove a catalog from all catalog sets.

Definition

HRESULT _CatalogSets::RemoveCatalogFromCatalogSets(
BSTR CatalogName
);

Parameters

CatalogName

[in] A BSTR that contains the catalog name to be removed.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

This method should be called whenever a catalog is deleted, before or after calling the CatalogManager.DeleteCatalog or ProductCatalog.DeleteCustomCatalog methods.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CatalogSets Object


_CatalogSets::UpdateCatalogSet

Use this method to update an existing catalog set and its basic properties.

Definition

HRESULT _CatalogSets::UpdateCatalogSet(
BSTR CatalogSetID,
BSTR CatalogSetName,
BSTR CatalogSetDescription,
VARIANT_BOOL bWildCard,
_Recordset* CatalogNamesRS
);

Parameters

CatalogSetID

[in] A BSTR that contains the catalog set ID (GUID).

CatalogSetName

[in] A BSTR that contains the catalog set name. The maximum length is 128 characters.

CatalogSetDescription

[in] A BSTR that contains the catalog set description.

bWildCard

[in] A VARIANT_BOOL that indicates which catalogs to use. A value of TRUE indicates use all catalogs. A value of FALSE indicates use the catalogs contained in the CatalogNameRS parameter.

CatalogNamesRS

[in, optional] A reference to a _Recordset object that contains the catalog names.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CatalogSets Object


CatalogToVendorAssociation Object

Use this object to associate catalogs with vendors.

ProgID: | Commerce.CatalogToVendorAssociation (Externally creatable)
COM Class Name: | CatalogToVendorAssociation
COM Interface Name: | _CatalogToVendorAssociation
Interface ID Constant: | None
Header File: | None
Type Library Name: | Microsoft Commerce 2000 Catalog Vendor Association Type Library
DLL Name: | CatalogVendorAssociation.dll
Threading Model: | Apartment

In C++, use the _CatalogToVendorAssociation interface to access the properties and methods of the CatalogToVendorAssociation object.

The methods of the CatalogToVendorAssociation object are shown in the following table.

Method | Description
GetVendorInfoForCatalog | Returns information about the vendor associated with the specified catalog.
GetVendorList | Returns a list of vendors available for association with catalogs.
Initialize | Initializes a CatalogToVendorAssociation object by connecting to the appropriate database.
SpecifyVendorForCatalog | Associates the specified vendor and catalog.
UnspecifyVendorForCatalog | Disassociates the specified vendor and catalog.


_CatalogToVendorAssociation::GetVendorInfoForCatalog

Use this method to retrieve information about the vendor associated with the specified catalog.

Definition

HRESULT _CatalogToVendorAssociation::GetVendorInfoForCatalog(
BSTR szCatalogID,
_Recordset** rsVendorInfo
);

Parameters

szCatalogID

[in] A BSTR that contains the ID of the catalog for which vendor information will be returned.

rsVendorInfo

[out, retval] The address of a pointer used to return an ADO _Recordset object containing the requested vendor information.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The returned ADO RecordSet object will contain valid data only if the method completed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CatalogToVendorAssociation Object


_CatalogToVendorAssociation::GetVendorList

Use this method to retrieve a list of vendors associated with the passed alias qualifier and value, and associated with the input document name.

Definition

HRESULT _CatalogToVendorAssociation::GetVendorList(
BSTR szSourceAliasQualifier,
BSTR szSourceAliasValue,
BSTR szInputDocumentName,
_Recordset** rsVendorList
);

Parameters

szSourceAliasQualifier

[in] A BSTR that contains the source alias qualifier.

szSourceAliasValue

[in] A BSTR that contains the source alias value.

szInputDocumentName

[in] A BSTR that contains the input document name.

rsVendorList

[out, retval] The address of a pointer used to return an ADO _Recordset object containing the requested list of vendors.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The returned ADO RecordSet object will contain valid data only if the method completed successfully.

Note

  • This method is only available when BizTalk Server is installed. It requires the BizTalKDBInternal object.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CatalogToVendorAssociation Object


_CatalogToVendorAssociation::Initialize

Use this method to initialize a CatalogToVendorAssociation object.

Definition

HRESULT _CatalogToVendorAssociation::Initialize(
BSTR vConnectionString
);

Parameters

vConnectionString

[in] A BSTR that contains the connection string for the database containing the catalog to vendor associations.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CatalogToVendorAssociation Object


_CatalogToVendorAssociation::SpecifyVendorForCatalog

Use this method to associate a vendor with a particular catalog.

Definition

HRESULT _CatalogToVendorAssociation::SpecifyVendorForCatalog(
BSTR szCatalogID,
BSTR szVendorQualifier,
BSTR szVendorQualifierValue,
BSTR szVendorName
);

Parameters

szCatalogID

[in] A BSTR that contains the identifier of the catalog with which to associated the specified vendors.

szVendorQualifier

[in] A BSTR that contains the qualifier of the vendor to be associated with the specified catalog.

szVendorQualifierValue

[in] A BSTR that contains the qualifier value of the vendor to be associated with the specified catalog.

szVendorName

[in] A BSTR that contains the name of the vendor to be associated with the specified catalog.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CatalogToVendorAssociation Object


_CatalogToVendorAssociation::UnspecifyVendorForCatalog

Use this method to disassociate a catalog with any previously associated vendors.

Definition

HRESULT _CatalogToVendorAssociation::UnspecifyVendorForCatalog(
BSTR szCatalogID
);

Parameters

szCatalogID

[in] A BSTR that contains the identifier of the catalog for which no vendors should be associated.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CatalogToVendorAssociation Object


Category Object

Use this object to work with relationships between categories and products. You can also use this object to manipulate parent/child relationships for a category.

ProgID: | Dependent (See Remarks for more information)
COM Class Name: | Category
COM Interface Name: | ICategory
Interface ID Constant: | IID_ICategory
Header File: | Catalog.h, mspu_guids.h
Type Library Name: | Microsoft Commerce 2000 Catalog Type Library
DLL Name: | Catalog.dll
Threading Model: | Both

In C++, use the ICategory interface to access the properties and methods of the Category object.

Because this object is primarily intended for use within ASP script, access from C++ will not be common.

The properties of the Category object are shown in the following table.

Property | Type | Description
AncestorCategories | _Recordset | Contains a recordset of category names that exist anywhere above this category, and that directly or indirectly contain this category in the hierarchy. This property is read-only.
CatalogName | BSTR | Contains the name of the catalog of which this Category object is a member. This property is read-only.
CategoryName | BSTR | Contains the name of this category. This property is read-only.
ChildCategories | _Recordset | Contains a recordset containing the child Category objects for this category. This property is read-only.
DescendantProducts | _Recordset | Contains all products that exist anywhere below this category. Accessing this property on the root category returns every product in the entire catalog. This property is read-only.
GetCategoryProperties | _Recordset | Contains a recordset containing the property values for this category. This property is read-only.
ParentCategories | _Recordset | Contains a recordset containing the names of the Category objects that are parent categories to this category. This property is read-only.
Products | _Recordset | Contains the products that exist within this category, but not within descendant categories. This property is read-only.
RelatedCategories | _Recordset | Contains a recordset that describes all of the categories and product families that have relationships to this category. This property is read-only.
RelatedProducts | _Recordset | Contains a recordset that describes all the product variants and product families that have relationships to this category. This property is read-only.

The methods of the Category object are shown in the following table.

Method | Description
AddChildCategory | Adds another specified category as a child of this category.
AddParentCategory | Adds another specified category as a parent of this category.
AddProduct | Adds another specified product variant as a child of this category.
AddRelationshipToCategory | Adds a relationship from another category to this category.
AddRelationshipToProduct | Adds a relationship from this category to a specified product.
RemoveChildCategory | Removes the specified category as a child of this category.
RemoveParentCategory | Removes the specified category as a parent of this category.
RemoveProduct | Removes a product from this category.
RemoveRelationshipToCategory | Removes the relationship between this category and a specified category.
RemoveRelationshipToProduct | Removes the relationship between this category and a specified product.
SetCategoryProperties | Assigns new properties to a category.

Remarks

The Category object is a dependent object. Obtain a pointer to the ICategory interface by calling one of the following methods:

  • IProductCatalog::CreateCategory

  • IProductCatalog::GetCategory


ICategory::AddChildCategory

Use this method to add a category as a child to this category.

Definition

HRESULT ICategory::AddChildCategory(
BSTR strCategoryName
);

Parameters

strCategoryName

[in] A BSTR that contains the name of the category to be added as a child to this category.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_CATEGORY_ALREADY_ADDED | 0x8898002D | The specified category has already been added as child to this category.
E_CAT_CATEGORY_DOESNT_EXIST | 0x8898001C | The specified category did not exist.
E_CAT_INVALID_CHILDCATEGORY | 0x8898005D | The category that you specified already exists as a parent of this category.
E_CAT_INVALID_RELATION | 0x88980039 | A category cannot be a parent or child of itself.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Category Object

ICategory::AddParentCategory

ICategory::RemoveChildCategory


ICategory::AddParentCategory

Use this method to add the specified category as a parent of this category.

Definition

HRESULT ICategory::AddParentCategory(
BSTR strCategoryName
);

Parameters

strCategoryName

[in] A BSTR that contains the name of the category to be added as a parent to this category.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_CATEGORY_ALREADY_ADDED | 0x8898002D | The specified category was already a child of this category.
E_CAT_CATEGORY_DOESNT_EXIST | 0x8898001C | The specified category did not exist.
E_CAT_PARENT_CAT_EXISTS_AS_CHILD | 0x88980052 | The category that you specified as a parent category already existed as a child category for this category.
E_CAT_INVALID_RELATION | 0x88980039 | A category cannot be a parent or child of itself.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Category Object

ICategory::AddChildCategory

ICategory::RemoveParentCategory


ICategory::AddProduct

Use this method to add the specified product to this category.

Definition

HRESULT ICategory::AddProduct(
VARIANT varProductID
);

Parameters

varProductID

[in] A VARIANT that contains the of the product to be added.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_PRODUCT_DOESNT_EXIST | 0x8898001E | The specified product did not exist in the catalog.
E_CAT_PRODUCT_ALREADY_ADDED | 0x88980029 | The specified product was already in this category.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

A product may exist in multiple categories simultaneously, without limit.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Category Object

ICategory::RemoveProduct


ICategory::AddRelationshipToCategory

Use this method to add a relationship from this category to another specified category.

Definition

HRESULT ICategory::AddRelationshipToCategory(
BSTR strRelatedCategoryName,
BSTR strRelationshipName,
VARIANT strRelationshipDescription
);

Parameters

strRelatedCategoryName

[in] A BSTR that contains the name of the category to which a relationship is to be added.

strRelationshipName

[in] A BSTR that contains a name for the relationship.

strRelationshipDescription

[in, optional] A VARIANT of sub type String that contains an optional description for the relationship.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_CATEGORY_DOESNT_EXIST | 0x8898001C | The specified category did not exist.
E_CAT_INVALID_RELATION | 0x88980039 | The relationship was invalid. A category or product cannot be related to itself.
E_CAT_INVALID_RELATION_DESC | 0x88980055 | The relationship description exceeded 256 characters.
E_CAT_INVALID_RELATION_NAME | 0x88980054 | The relationship name exceeded 128 characters.
E_CAT_RELATIONSHIP_EXISTS | 0x88980033 | The specified relationship already existed.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

A relationship must be given a name and may optionally be given a description. The description can include information that describes the nature of the relationship between the categories (for example, an "accessory" or "add-on"). Relationships are one way, that is, if category A has a relationship to category B that does not create a reciprocal relationship from category B to category A.

When multiple relationships are created between the same two categories, each relationship must have a unique name.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Category Object

ICategory::RemoveRelationshipToCategory


ICategory::AddRelationshipToProduct

Use this method to add a relationship between the specified product and this category. This relationship must be given a name and may optionally be given a description. The description can include information that describes the nature of the relationship between the categories (for example, an "accessory" or "add-on").

Definition

HRESULT ICategory::AddRelationshipToProduct(
VARIANT varRelatedProductID,
BSTR strRelationshipName,
VARIANT strRelationshipDescription
);

Parameters

varRelatedProductID

[in] A VARIANT that contains the ID of the related product.

strRelationshipName

[in] A BSTR that contains a name for the relationship.

strRelationshipDescription

[in, optional] A VARIANT that contains an optional description for the relationship.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_INVALID_RELATION | 0x88980039 | The relationship was invalid. A category or product cannot be related to itself
E_CAT_INVALID_RELATION_DESC | 0x88980055 | The relationship description exceeded 256 characters
E_CAT_INVALID_RELATION_NAME | 0x88980054 | The relationship name exceeded 128 characters
E_CAT_PRODUCT_DOESNT_EXIST | 0x8898001E | The specified product did not exist.
E_CAT_RELATIONSHIP_EXISTS | 0x88980033 | There was already a relationship with the specified product.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

In order for this method to complete successfully, the product identified must already exist.

When multiple relationships are created between a category and product, each relationship must have a unique name.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Category Object

ICategory::RemoveRelationshipToProduct


ICategory::get_AncestorCategories

The AncestorCategories property is a read-only Recordset object that contains the names of categories that exist anywhere above this category in the hierarchy

Definition

HRESULT ICategory::get_AncestorCategories(
_Recordset** AncestorCategories
);

Parameters

AncestorCategories

[out, retval] A _Recordset object used to return the ancestor categories.

Return Values

This method returns an HRESULT indicating whether it completed successfully.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The AncestorCategories property contains valid data only if it was accessed successfully.

The AncestorCategories property is a Recordset object with a single 128-character field, named Name.

See Also

Category Object

ICategory::get_ParentCategories

ICategory::get_ChildCategories


ICategory::get_CatalogName

The CatalogName property is a read-only String that contains the name of the catalog within which this category exists.

Definition

HRESULT ICategory::get_CatalogName(
BSTR* CatalogName
);

Parameters

CatalogName

[out, retval] A BSTR used to return the catalog name.

Return Values

This method returns an HRESULT indicating whether it completed successfully.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The CatalogName parameter contains valid data only if the property is accessed successfully.

See Also

Category Object


ICategory::get_CategoryName

The CategoryName property is a read-only String that contains the name of this category.

Definition

HRESULT ICategory::get_CategoryName(
BSTR* CategoryName
);

Parameters

CategoryName

[out, retval] A BSTR used to return the category name.

Return Values

This method returns an HRESULT indicating whether it completed successfully.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The CategoryName parameter contains valid data only if the property is accessed successfully.

See Also

Category Object


ICategory::get_ChildCategories

The ChildCategories property is a read-only Recordset object that contains the names of categories that exist below this category in the hierarchy.

Definition

HRESULT ICategory::get_ChildCategories(
_Recordset** ChildCategories
);

Parameters

ChildCategories

[out, retval] A _Recordset object used to return the child categories.

Return Values

This method returns an HRESULT indicating whether it completed successfully.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The ChildCategories parameter contains valid data only if the property is accessed successfully.

The ChildCategories recordset contains a row for each of the categories that are currently children of this category. The following table lists the fields for the ChildCategories recordset.

Field Data Type Description
CategoryName String
maximum of 128 characters 		The name of the category.
DefinitionName String
maximum of 128 characters 		The name of the definition.
CatalogName String
maximum of 128 characters 		The name of the Catalog that contains the category.

If this category has no children, an empty recordset is returned whose EOF property is set to VARIANT_TRUE. Your code should check the value of this property to determine if child categories exist.

See Also

Category Object

ICategory::get_ParentCategories

ICategory::get_AncestorCategories


ICategory::get_DescendantProducts

The DescendantProducts property is a read-only Recordset object that contains all products that exist anywhere below this category. Accessing this property on the root category returns every product in the entire catalog.

Definition

HRESULT ICategory::get_DescendantProducts(
VARIANT eClassTypeRequired,
VARIANT lStartingRecord,
VARIANT lRecordsToRetrieve,
VARIANT* plTotalRecordsInQuery,
_Recordset** DescendantProducts
);

Parameters

eClassTypeRequired

[in, optional] A VARIANT that contains the catalog class desired. Valid values are from the CatalogClassTypeEnum enumeration. For more information, see the Remarks section.

lStartingRecord

[in, optional] A VARIANT that contains the starting record.

lRecordsToRetrieve

[in, optional] A VARIANT that contains the number of records to retrieve.

plTotalRecordsInQuery

[out, optional] A pointer to a VARIANT used to return the total number of records in the query.

DescendantProducts

[out, retval] A _Recordset object used to return the descendant products.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This property returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The DescendantProducts parameter contains valid data only if the property is accessed successfully.

This property gets all the products, which are directly or indirectly under this category.

The returned recordset contains all the fields in the CatalogProduct Recordset.

The following table shows the values of the CatalogClassTypeEnum enumeration, their associated names, and describes their use.

Name | Value | Description
cscCategoryClass | 1 | Requests category data.
cscProductVariantClass | 2 | Requests product variant data.
cscProductClass | 4 | Requests product data.
cscProductFamilyClass | 8 | Requests product family data.
cscProductFamilyForVariantsClass | 16 | Requests family for variant data, which means the product family of a product variant is being requested.
CscProductVariantsForFamily | 32 | Requests variants for family data, which means that all of the product variants for a product family are being requested.

CatalogClassTypeEnum values can be combined in the eClassTypeRequired parameter with logical OR operators, so that specifying cscProductClass OR cscProductVariantClass will return both product and product variant data.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Category Object

ICategory::get_RelatedProducts

ICategory::get_Products


ICategory::get_GetCategoryProperties

The GetCategoryProperties property is a read-only recordset that contains the properties for this category. Both the properties that are present in the definition of this category, and the built-in properties, are returned.

Definition

HRESULT ICategory::get_GetCategoryProperties(
_Recordset** GetCategoryProperties
);

Parameters

GetCategoryProperties

[out, retval] A _Recordset object used to return the category properties.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_CATEGORY_DOESNT_EXIST | 0x8898001C | This category has been removed from the catalog.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The GetCategoryProperties parameter contains valid data only if the property is accessed successfully.

The returned recordset contains all the common fields in the CatalogProduct Recordset. It also contains all the fields that are in the product definitions for the category. The ProductID field (the unique product identifier) is returned even if it is not part of a product definition.

The recordset returned is updateable, but disconnected. If this category has been deleted from the database, this property returns an error.

See Also

Category Object

ICategory::SetCategoryProperties


ICategory::get_ParentCategories

The ParentCategories property is a read-only recordset that contains the names of the parent categories of this category.

Definition

HRESULT ICategory::get_ParentCategories(
_Recordset** ParentCategories
);

Parameters

ParentCategories

[out, retval] A _Recordset object used to return the parent categories.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The ParentCategories parameter contains valid data only if the property is accessed successfully.

The ParentCategories property contains the names of the categories that are parent categories of this category. The recordset returned contains a single 128-character string column named Name, and one row for each parent that exists.

If this category is a root category, it has no parent categories, and an empty recordset is returned whose EOF property is set to VARIANT_TRUE.

See Also

Category Object

ICategory::get_AncestorCategories

ICategory::get_ChildCategories


ICategory::get_Products

The Products property is a read-only recordset that contains product data for all of the products that exist directly within this category.

Definition

HRESULT ICategory::get_Products(
VARIANT eClassTypeRequired,
VARIANT strPropertyToSortOn,
VARIANT lStartingRecord,
VARIANT lRecordsToRetrieve,
VARIANT* plTotalRecordsInQuery,
_Recordset** Products
);

Parameters

eClassTypeRequired

[in, optional] A VARIANT that contains the catalog class desired. Valid values are from the CatalogClassTypeEnum enumeration. For more information, see the Remarks section.

strPropertyToSortOn

[in, optional] A VARIANT that contains the property to sort on.

lStartingRecord

[in, optional] A VARIANT that contains the starting record number.

lRecordsToRetrieve

[in, optional] A VARIANT that contains the number of records to retrieve.

plTotalRecordsInQuery

[out, optional] A pointer to a VARIANT used to return the total number of records in the query.

Products

[out, retval] A _Recordset object used to return the products.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The Products parameter contains valid data only if the property is accessed successfully.

If the properties specified in strPropertyToSortOn parameter are invalid then the recordset will be unsorted.

Note

  • If the value of cscCategoryClass is specified for the eClassTypeRequired parameter, the returned recordset will contain all the products and all the child categories in this category.

The Products property contains the product data for all the products in this category.

The returned recordset contains all the fields in the CatalogProduct Recordset.

If this category contains no products, then the Products property returns an empty recordset whose EOF property is set to VARIANT_TRUE.

The following table shows the values of the CatalogClassTypeEnum enumeration, their associated names, and describes their use.

Name | Value | Description
cscCategoryClass | 1 | Requests category data.
cscProductVariantClass | 2 | Requests product variant data.
cscProductClass | 4 | Requests product data.
cscProductFamilyClass | 8 | Requests product family data.
cscProductFamilyForVariantsClass | 16 | Requests family for variant data, which means the product family of a product variant is being requested.
CscProductVariantsForFamily | 32 | Requests variants for family data, which means that all of the product variants for a product family are being requested.

CatalogClassTypeEnum values can be combined in the eClassTypeRequired parameter with logical OR operators, so that specifying cscProductClass OR cscProductVariantClass will return both product and product variant data.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Category Object

ICategory::get_DescendantProducts

ICategory::get_RelatedProducts


ICategory::get_RelatedCategories

The RelatedCategories property is a read-only recordset that contains all categories related to this category.

Definition

HRESULT ICategory::get_RelatedCategories(
_Recordset** RelatedCategories
);

Parameters

RelatedCategories

[out, retval] A _Recordset object used to return the related categories.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The RelatedCategories parameter contains valid data only if the property is accessed successfully.

The RelatedCategories property contains information on all the relationships this category has to other categories. The recordset returned contains one row for each relationship present.

The returned recordset contains the following fields:

Field Data Type Description
CategoryName String
maximum of 128 characters 		The name of the category.
RelationshipName String
maximum of 128 characters 		The name of the relationship.
RelationshipDescription String
maximum of 256 characters 		The description of the relationship.

See Also

Category Object

ICategory::get_AncestorCategories

ICategory::get_ChildCategories

ICategory::get_ParentCategories

ICategory::AddRelationshipToCategory

ICategory::RemoveRelationshipToCategory


ICategory::get_RelatedProducts

The RelatedProducts property is a read-only recordset containing information about all products related to this category.

Definition

HRESULT ICategory::get_RelatedProducts(
_Recordset** RelatedProducts
);

Parameters

RelatedProducts

[out, retval] A _Recordset object used to return the related products.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The RelatedProducts parameter contains valid data only if the property is accessed successfully.

The recordset returned contains one row for each relationship present.

The following table shows the fields in the returned recordset.

Field | Data Type | Description
<defined ProductID field> | Varies | The unique product identifier, defined during catalog creation.
RelationshipName String
maximum of 128 characters 		The name of the relationship.
RelationshipDescription String
maximum of 256 characters 		The description of the relationship.

See Also

Category Object

ICategory::get_DescendantProducts

ICategory::get_Products

ICategory::AddRelationshipToProduct

ICategory::RemoveRelationshipToProduct


ICategory::RemoveChildCategory

Use this method to remove a category that is a child of this category.

Definition

HRESULT ICategory::RemoveChildCategory(
BSTR strCategoryName
);

Parameters

strCategoryName

[in] A BSTR that contains the name of the category to be removed as a child of this category.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_CATEGORY_DOESNT_EXIST | 0x8898001C | The category you specified either did not exist or was not a child of this category.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

Use the RemoveChildCategory method to remove a child category from this category. If the category named in the strCategoryName parameter does not exist, then this method will fail.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Category Object

ICategory::AddChildCategory

ICategory::RemoveParentCategory


ICategory::RemoveParentCategory

Use this method to remove the specified category as a parent of this category.

Definition

HRESULT ICategory::RemoveParentCategory(
BSTR strCategoryName
);

Parameters

strCategoryName

[in] A BSTR that contains the name of the category to be removed as a parent to this category.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_CATEGORY_DOESNT_EXIST | 0x8898001C | The category you specified either did not exist or was not a parent of this category.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

Use the RemoveParentCategory method to remove a parent category from this category. If the category named in the strCategoryName parameter does not exist, then this method will fail.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Category Object

ICategory::AddParentCategory

ICategory::RemoveChildCategory


ICategory::RemoveProduct

Use this method to remove a product from this category.

Definition

HRESULT ICategory::RemoveProduct(
VARIANT varProductID
);

Parameters

varProductID

[in] A VARIANT that contains the product ID.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_PRODUCT_DOESNT_EXIST | 0x8898001E | The product you specified did not exist.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Category Object

ICategory::AddProduct


ICategory::RemoveRelationshipToCategory

Use this method to remove a relationship between the specified category and this category.

Definition

HRESULT ICategory::RemoveRelationshipToCategory(
BSTR strRelatedCategoryName,
BSTR strRelationshipName
);

Parameters

strRelatedCategoryName

[in] A BSTR that contains the name of the related category.

strRelationshipName

[in] A BSTR that contains the name of the relationship.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_CATEGORY_DOESNT_EXIST | 0x8898001C | The category you specified either did not exist or was not a parent of this category.
E_CAT_DEFN_NO_RELATIONSHIP_EXISTS | 0x88980045 | The specified relationship did not exist.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The RemoveRelationshipToCategory method removes a relationship between this category and the category named in the strRelatedCategoryName parameter. Since more than one relationship may exist between these two categories, you must also specify the name of the relationship you wish to remove in the strRelationshipName parameter. If the category specified as the strRelatedCategoryName parameter does not exist or the relationship specified as the strRelationshipName parameter does not exist, then this method will fail.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Category Object

ICategory::AddRelationshipToCategory

ICategory::RemoveRelationshipToProduct


ICategory::RemoveRelationshipToProduct

Use this method to remove a relationship between the specified product and this category.

Definition

HRESULT ICategory::RemoveRelationshipToProduct(
VARIANT varRelatedProductID,
BSTR strRelationshipName
);

Parameters

varRelatedProductID

[in] A VARIANT that contains the ID of the related product.

strRelationshipName

[in] A BSTR that contains the name of the relationship.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_DEFN_NO_RELATIONSHIP_EXISTS 0x88980045
            The specified relationship did not exist.
    E_CAT_PRODUCT_DOESNT_EXIST | 0x8898001E | The specified product did not exist.

    Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

    Remarks

    The RemoveRelationshipToProduct method removes a relationship between this category and the product identified by the varRelatedProductID parameter. Since more than one relationship may exist between this category and product, you must also specify the name of the relationship you wish to remove in the strRelationshipName parameter. If the product specified as the varRelatedProductID parameter does not exist or the relationship specified as the strRelationshipName parameter does not exist, then this method will fail.

    For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

    See Also

    Category Object

    ICategory::AddRelationshipToProduct


ICategory::SetCategoryProperties

Use this method to set values for the properties of this category.

Definition

HRESULT ICategory::SetCategoryProperties(
_Recordset* pRSCategory,
VARIANT fForceUpdate
);

Parameters

pRSCategory

[in] A reference to a Recordset object that contains the properties for this category.

fForceUpdate

[in, optional] A VARIANT that causes a forced update of the category properties.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_CATEGORY_CHANGED | 0x88980028 | The properties of this category have changed since they were last read. This error is returned only if the fForceUpdate parameter is set to False.
E_CAT_CATEGORY_DOESNT_EXIST | 0x8898001C | This category has been removed from the catalog.
E_CAT_INVALIDVALUE_FOR_PROPERTY 0x88980038 This error is returned if:
  • One of the properties did not satisfy the Min/Max condition.

  • The properties of string or enumeration data type exceeded the maximum length.

  • The value of the enumeration property was not one of the legal values defined.
E_CAT_NULL_PRICE_NOT_ALLOWED | 0x8898003F | The OriginalPrice field in the pRSCategory recordset was blank or NULL. This field is required if the category is used as a pricing category.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

Use the SetCategoryProperties method to modify the properties of a category. The pRSCategory parameter specifies a Recordset object that describes the new property values for this category. Use the Recordset object returned by the GetCategoryProperties method so that its timestamp can be compared for error checking.

If the fForceUpdate parameter is set to False, and the property values in the pRSCategory parameter have changed, the method will fail.

This method will not update the built in fields in the catalog. If this category is being used as a pricing category, then this method will update the price of all the products using this category as the pricing category

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Category Object


ContentList Object

Use this object to access a particular collection of content items. The ContentList object provides aggregated access to the private data that it stores and to the shared data stored in the ContentListFactory object that created it. This object also flows through the Content Selection Framework (CSF) pipeline for the purpose of scoring content items.

ProgID: | Dependent (See Remarks for more information)
COM Class Name: | ContentList
COM Interface Name: | IContentList
Interface ID Constant: | IID_IContentList
Header File: | cacheint.h, mspu_guids.h
Type Library Name: | Microsoft Commerce 2000 Cache Manager Type Library
DLL Name: | mscscache.dll
Threading Model: | Both

In C++, use the IContentList and IDataContainer interfaces to access the methods and properties of a ContentList object.

The properties of the ContentList object are shown in the following table.

Property | Type | Description
ActiveRows | IRowCollection | The collection of rows that meet the current Threshold and RowLimit properties and that have not been filtered out of the ContentList object. This property is read-only.
AllRows | IRowCollection | Contains a RowCollection object containing all rows in this ContentList object. This property is read-only.
Count | long | Contains the number of rows in this ContentList object. This property is read/write.
Factory | IContentListFactory | Contains the ContentListFactory object that created this ContentList object. This property is read-only.
Fields | Fields | Contains the Fields collection for this ContentList object. This property is read-only.
RowLimit | long | Contains the maximum number of active rows. This property is read/write.
Sorted | VARIANT_BOOL | Stores a flag that controls whether or not the rows in the ActiveRows collection property are returned sorted by score. This property is read/write.
Threshold | float | Contains the Threshold score required for active rows. This property is read/write.
TraceMessages | ISimpleList | Stores the list of TraceMessage strings accumulated for a particular row in the ContentList object. This property is read-only.
TraceMode | VARIANT_BOOL | Stores the TraceMode value. A value of True enables score tracing, a value of False disables it. This property is read/write.

The methods of the ContentList object are shown in the following table.

Method | Description
AdjustScore | Adjusts the score associated with an item in the ContentList object by applying a multiplier.
BuildIndex | Builds an index on the specified column.
Filter | Filters items in a ContentList object based on the specified criteria.
GetData | Gets data from a specified row and column in a ContentList object in a high-performance, non-scriptable manner.
GetScore | Gets the score of an item in a ContentList object.
Search | Returns a RowCollection object containing the collection of content items that match the search criteria.
SetData | Sets data at a specified row and column in a ContentList object in a high-performance, non-scriptable manner.
SetScore | Sets the score of an item in a ContentList object.

Remarks

Both the ContentList object and the ContentListFactory object implement a common interface, IDataContainer. Therefore, they share the following methods and properties, which are functionally identical on both objects:

Properties:

  • AllRows

  • Count

  • Fields

Methods:

  • BuildIndex

  • GetData

  • Search

  • SetData

The function of a ContentList object is:

  • To aggregate private data in the ContentList object with shared data in the ContentListFactory object.

  • To provide functionality for scoring, searching, and filtering the list of content.

The ContentList object is a dependent object. Create a new ContentList object and obtain a pointer to its IContentList interface by calling the method IContentListFactory::CreateNewContentList.

Important

  • The ContentList and the ContentListFactory objects are designed to be run in-process with their clients. The GetData and SetData methods assume direct memory access for performance reasons.


IContentList::get_ActiveRows

The ActiveRows property returns a RowCollection object. This property is read-only; however, the RowCollection object is read/write. Changes made to the data within the RowCollection object are also reflected in the ContentList object.

Definition

Get method:

HRESULT IContentList::get_ActiveRows(
IRowCollection** ActiveRows
);

Parameters

ActiveRows

[out,retval] The address of a pointer used to return the IRowCollection interface of a RowCollection object that allows access the set of active items in this ContentList object.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The ActiveRows RowCollection object allows access to the content items of the ContentList object whose score is greater than or equal to the current threshold score contained in the Threshold property. If the value of the Threshold property is set to a negative number, even items that have been filtered out by the Filter method might be included in the ActiveRows collection. This occurs because an item being filtered out has a score set to zero, which is still greater than a negative threshold value.

Regardless of the number of items with scores above the threshold, the number of items in the ActiveRows object is limited by the RowLimit property.

The order of the rows in the ActiveRows collection is undefined unless the Sorted property is set to True.

See Also

ContentList Object

RowCollection Object


IContentList::AdjustScore

Use this method to adjust the score of an item in the ContentList object by applying a multiplier.

Definition

HRESULT IContentList::AdjustScore(
long RowNum,
float Multiplier,
BSTR Component,
BSTR Description
);

Parameters

RowNum

[in] A long that contains the position of the item in the ContentList object for which the score is to be adjusted. Positions are counted from zero (0), not from one (1).

Multiplier

[in] A float that contains the value by which the score will be multiplied.

Component

[in,optional] A BSTR that contains an identifier for the pipeline component that is adjusting the score. By convention, this is the Programmatic Identifier (ProgID) of the pipeline component.

Description

[in,optional] A BSTR that contains a description to be appended to the score adjustment tracing string. This string should briefly describe the nature of the adjustment.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The Component and Description parameters are optional. They are ignored unless the TraceMode property is set to True.

This method assumes that the ContentList object has a column of type CLCOL_R4 with the CLCOL_SCORE_COLUMN flag set.

See Also

ContentList Object


IContentList::get_AllRows

The AllRows property returns a new RowCollection object that allows access to the items in the ContentList object and, through aggregation, the ContentListFactory object. The AllRows property is read-only; however, the RowCollection object is read/write. Changes made to the data in the RowCollection object are reflected in the ContentList object.

Definition

Get method:

HRESULT IContentList::get_AllRows(
IRowCollection** AllRows
);

Parameters

AllRows

[out,retval] The address of a pointer used to return the IRowCollection interface of a RowCollection object that contains all of the items in this ContentList object.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

This property is functionally identical to the one of the same name to be found in the ContentListFactory object.

See Also

ContentList Object


IContentList::BuildIndex

Use this method to build an index for a specific column in a ContentList object.

Definition

HRESULT IContentList::BuildIndex(
VARIANT vCol
);

Parameters

vCol

[in] A VARIANT that identifies the column for which the index will be built. The column is identified by either a number representing a column position, starting at zero (0), or a string containing a column name.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

S_FALSE

An index already exists on the column.

Remarks

An index can be built on any read-only, non-private column that is of type string, integer, or array of strings or integers. (CLCOL_READONLY and not CLCOL_PRIVATE). Also, only columns of type CLCOL_I2, CLCOL_I4, CLCOL_STRING, and CLCOL_VARIANTARRAY can be indexed. The non-private restriction means that the column will actually reside in the corresponding ContentListFactory object.

If a search is conducted on a column for which no index yet exists, the index is automatically created. This means that, although you are never required to call the BuildIndex method, you may want to incur the cost of creating the index at a known time for performance sake.

This method is functionally identical to the one of the same name in the ContentListFactory object.

See Also

ContentList Object


IContentList::get_Count, put_Count

The Count property is a read/write number that gets or sets the number of items in a ContentList object.

Definition

Get method:

HRESULT IContentList::get_Count(
long* Count
);

Put method:

HRESULT IContentList::put_Count(
long Count
);

Parameters

Count

[in] When putting the property, a long that contains the item count.
[out,retval] When getting the property, a pointer to a long used to return the item count.

Return Values

These methods return an HRESULT indicating whether or not they completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

Normally, the Count property is already fixed when a ContentList object is created by a ContentListFactory object. The property may only be set for ContentList objects that are created by a ContentListFactory object that has not yet had any content items stored in it. Also, the Count property cannot be set to a number smaller than the current setting.

This property is functionally identical to the one of the same name in the ContentListFactory object.

See Also

ContentList Object


IContentList::get_Factory

The Factory property is a read-only pointer to the IContentListFactory interface of the ContentListFactory object that created this ContentList object.

Definition

Get method:

HRESULT IContentList::get_Factory(
IContentListFactory** Factory
);

Parameters

Factory

[out,retval] The address of a pointer used to return the IContentListFactory interface of the ContentListFactory object that created this ContentList object.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

See Also

ContentList Object


IContentList::get_Fields

The Fields property creates a new Fields object that allows access to the fields for a specified content item. The Fields property is read-only; however, the Fields object is read/write in that changes made using this object are reflected in the ContentList object.

Definition

Get method:

HRESULT IContentList::get_Fields(
long RowNum,
Fields** Fields
);

Parameters

RowNum

[in] A long that contains the position of the item in the ContentList object for which a Fields object will be returned. Positions are counted from zero (0), not from one (1).

Fields

[out,retval] The address of a pointer used to return a Fields object for the specified row in the ContentList object.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The Fields object exposes the same interface as the ActiveX Data Objects (ADO) Fields object.

This property is functionally identical to the one of the same name in the ContentListFactory object.

See Also

ContentList Object


IContentList::Filter

Use this method to filter items in a ContentList object. Items that do not pass the filter have their scores set to zero (0).

Definition

HRESULT IContentList::Filter(
VARIANT vColumn,
VARIANT vFilterCriteria,
FilterActionEnum FilterAction,
BSTR Component
);

Parameters

vColumn

[in] A VARIANT that identifies the column upon which to filter. The column is identified by either a number representing a column position, starting at zero (0), or a string containing a column name.

vFilterCriteria

[in] A VARIANT that contains the filter criterion. The criterion is either a single BSTR, a SAFEARRAY of BSTRs, or an Integer.

FilterAction

[in] An enumeration value. Valid values are FILTER_REQUIRE and FILTER_EXCLUDE. See the Remarks section for more information about the consequences of these two actions.

Component

[in,optional] A BSTR that is intended to contain the name of the pipeline component doing the filtering. This parameter is optional and is used for score tracing. Trace messages will be generated for content items that are filtered out.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

An item in the ContentList object matches the criteria if the value for the specified column exactly matches a string or number passed in the vFilterCriteria parameter. If the vFilterCriteria parameter is an array of strings, matching any one of the strings in the array is considered a match. If the FilterAction parameter is set to FILTER_REQUIRE, non-matching items have their scores set to zero (0). If the FilterAction parameter is set to FILTER_EXCLUDE, matching items have their scores set to zero (0).

For the sake of uniformity, the pipeline components provided with Commerce Server 2000 pass their own Programmatic Identifier (ProgID) for the Component parameter.

See Also

ContentList Object


IContentList::GetData

This is one of the two ContentList methods that do not support a scriptable interface. The other method is SetData. They are only intended for use in C++.

Definition

HRESULT IContentList::GetData(
long iRow,
long iCol,
BYTE* pData
);

Parameters

iRow

[in] A long that contains the position of the row from which the data should be read. Row positions are counted from zero (0), not one (1).

iCol

[in] A long that contains the position of the column within the specified row from which the data should be read. Column positions are counted from zero (0), not one (1).

pData

[out] A pointer to where the data should be written.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The GetData method does not do type checking. The memory pointed to by the pData parameter must be large enough to receive the value being read. If the allotted memory is too small, memory corruption occurs.

The ContentList object stores some types of data by value and other types of data by reference. Therefore, how you use the GetData and SetData methods depends on the data type.

When you pass a pointer to a String to the SetData method, it stores the String in the ContentList object, not the pointer. The GetData method returns a pointer to the String in the ContentList object, but not the String. Do not hold a reference to the String in the ContentList object beyond the lifetime of the object, as it will be invalid after the object is destroyed. The ContentList object only stores wide character Unicode strings. ANSI strings are not supported.

When you pass an interface pointer to an object to the SetData method, it calls AddRef on the interface pointer and stores it in the ContentList object. The GetData method returns this pointer and calls AddRef on it. The caller must call release on the pointer returned by the GetData method.

When you pass a pointer to a SafeArray to the SetData method, it locks the SafeArray and stores a reference to it in the ContentList object. The GetData method returns a reference to the locked array. The caller should not unlock the array as this could invalidate the reference stored in the ContentList object. It is safe to store the array in a Variant of type VT_ARRAY or VT_VARIANT, as a call to ::VariantClear will not release the SafeArray because it is locked. When the ContentList object is being destroyed the SafeArray will be unlocked and SafeArrayDestroy will be called. Since SafeArrays have a lock count similar to reference counting the array data will be released only if the lock count is zero.

GetData reads and SetData stores all other supported data types by value.

This method is functionally identical to the one of the same name in the ContentListFactory object.

See Also

ContentList Object


IContentList::GetScore

Use this method to retrieve the score of an item in a ContentList object.

Definition

HRESULT IContentList::GetScore(
long RowNum,
float* Score
);

Parameters

RowNum

[in] A long that contains the position of the item in the ContentList object for which the score will be returned. Positions are counted from zero (0), not from one (1).

Score

[out,retval] A pointer to a float used to return the score for the specified item.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

See Also

ContentList Object


IContentList::get_RowLimit, put_RowLimit

The RowLimit property is a read/write number that specifies the maximum number of rows that the object should select for the ActiveRows property.

Definition

Get method:

HRESULT IContentList::get_RowLimit(
long* RowLimit
);

Put method:

HRESULT IContentList::put_RowLimit(
long RowLimit
);

Parameters

RowLimit

[in] When putting the property, a long that specifies the row limit.
[out,retval] When getting the property, a pointer to a long used to return the row limit.

Return Values

These methods return an HRESULT indicating whether or not they completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

See Also

ContentList Object

IContentList::get_ActiveRows


IContentList::Search

Use this method to create a RowCollection object that allows access to each item in the ContentList object that matches the specified criterion.

Definition

HRESULT IContentList::Search(
VARIANT vCol,
VARIANT vSearchCriteria,
IRowCollection** ppIRowCollection
);

Parameters

vCol

[in] A VARIANT that identifies the column to search. The column is identified by either a number representing a column position, starting at zero (0), or a string containing a column name.

vSearchCriteria

[in] A VARIANT that contains the filter criterion. The criterion is usually a BSTR, an array of BSTRs, or an Integer. The Search method will attempt to coerce other types to the type of the column being searched.

ppIRowCollection

[out,retval] A pointer to an address to receive an IRowCollection interface pointer for a new RowCollection object that allows access to the rows that match the search criteria.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

The following standard COM error value has a particular meaning in the context of this method.

S_FALSE

No rows in the ContentList object matched the filter criteria. As a result, the returned RowCollection is empty.

Remarks

Columns must be shared (not private) and read-only in order to be indexed and searched. Columns must also be of type string, integer (long or short), or variant array to be searchable. The search criteria may be any variant type that can be coerced to the type of the column being searched.

When the search criteria is an array of variants, the set of rows returned contains all rows that match any of the search criteria array elements. It is a union of the matches.

This property is functionally identical to the one of the same name in the ContentListFactory object.

See Also

ContentList Object


IContentList::SetData

This is one of the two ContentList methods that do not support a scriptable interface. The other method is GetData. They are only intended for use in C++.

Definition

HRESULT IContentList::SetData(
long iRow,
long iCol,
BYTE* pData
);

Parameters

iRow

[in] A long that contains the position of the row into which the data should be written. Row positions are counted from zero (0), not one (1).

iCol

[in] A long that contains the position of the column within the specified row into which the data should be written. Column positions are counted from zero (0), not one (1).

pData

[in] A pointer to the data to write into the ContentList object.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The SetData method does not do type checking for the data being written. The data pointed to by the pData parameter must be of the correct type for the column. Type (and especially size) mismatches will not result in memory scribbles (which is possible with the GetData method), but some of the data may not be written into the ContentList object.

The ContentList object stores some types of data by value and other types of data by reference. Therefore, how you use the GetData and SetData methods depends on the data type.

When you pass a pointer to a String to the SetData method, it stores the String in the ContentList object, not the pointer. The GetData method returns a pointer to the String in the ContentList object, but not the String. Do not hold a reference to the String in the ContentList object beyond the lifetime of the object, as it will be invalid after the object is destroyed. The ContentList object only stores wide character Unicode strings. ANSI strings are not supported.

When you pass an interface pointer to an object to the SetData method, it calls AddRef on the interface pointer and stores it in the ContentList object. The GetData method returns this pointer and calls AddRef on it. The caller must call release on the pointer returned by the GetData method.

When you pass a pointer to a SafeArray to the SetData method, it locks the SafeArray and stores a reference to it in the ContentList object. The GetData method returns a reference to the locked array. The caller should not unlock the array as this could invalidate the reference stored in the ContentList object. It is safe to store the array in a Variant of type VT_ARRAY or VT_VARIANT, as a call to ::VariantClear will not release the SafeArray because it is locked. When the ContentList object is being destroyed the SafeArray will be unlocked and SafeArrayDestroy will be called. Since SafeArrays have a lock count similar to reference counting the array data will be released only if the lock count is zero.

GetData reads and SetData stores all other supported data types by value.

Objects must be "both threaded" and must aggregate the Free Threaded Marshaller object in order to be stored in a ContentList object. If you ignore this restriction, marshalling errors may occur.

This method is functionally identical to the one of the same name in the ContentListFactory object.

Caution

  • Because ContentList objects do not perform synchronization or locking, take caution when you are writing string, array, or object values in multi-threaded scenarios. Race conditions could exist that might result in resource leaks.

See Also

ContentList Object


IContentList::SetScore

Use this method to set a new score for an item in a ContentList object.

Definition

HRESULT IContentList::SetScore(
long RowNum,
float Score,
BSTR Component,
BSTR Description
);

Parameters

RowNum

[in] A long that contains the position of the item in the ContentList object for which a new score will be set. Positions are counted from zero (0), not from one (1).

Score

[in] A float that contains the new score.

Component

[in,optional] A BSTR that is intended to contain the name of the pipeline component that is setting the new score. This parameter is optional and is used for score tracing.

Description

[in,optional] A BSTR that is intended to contain the reason that the score is being set; for example, Need of Delivery. This parameter is optional and is used for score tracing.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The Component and Description parameters are optional.

This method assumes that the ContentList object has a column of type CLCOL_R4 with the CLCOL_SCORE_COLUMN flag set.

For the sake of uniformity, pipeline components provided with Commerce Server 2000 pass the Programmatic Identifier (ProgID) of the component for the Component parameter.

See Also

ContentList Object


IContentList::get_Sorted, put_Sorted

The Sorted property is a read/write Boolean that determines whether or not the next enumeration of the ContentList object ActiveRows property will be returned in sorted order by score (highest to lowest).

Definition

Get method:

HRESULT IContentList::get_Sorted(
VARIANT_BOOL* Sorted
);

Put method:

HRESULT IContentList::put_Sorted(
VARIANT_BOOL Sorted
);

Parameters

Sorted

[in] When putting the property, a VARIANT_BOOL that specifies whether or not to return the ActiveRows property in sorted order.
[out,retval] When getting the property, a pointer to a VARIANT_BOOL used to return the value of the Sorted property. See the Remarks section for the effects of this property.

Return Values

These methods return an HRESULT indicating whether or not they completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

A value of True indicates that the next enumeration of the ContentList object ActiveRows property should be returned in sorted order by score (highest to lowest). A value of FALSE indicates that it will not be sorted. The items do not actually change positions in the list — that is, the ordinal identifying an item never changes. Setting the value to True only effects the next enumeration of the ActiveRows property, subsequent enumerations will be unsorted unless the property is set to True again.

See Also

ContentList Object


IContentList::get_Threshold, put_Threshold

The Threshold property is a read/write floating point number. This number contains a threshold score that items must meet or exceed to be included in the ActiveRows collection property.

Definition

Get method:

HRESULT IContentList::get_Threshold(
float* Threshold
);

Put method:

HRESULT IContentList::put_Threshold(
float Threshold
);

Parameters

Threshold

[in] When putting the property, a float that contains the new threshold score.
[out,retval] When getting the property, a pointer to a float used to return the threshold score.

Return Values

These methods return an HRESULT indicating whether or not they completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

See Also

ContentList Object


IContentList::get_TraceMessages

The TraceMessages property is a SimpleList object that contains the list of trace strings that have accumulated for the given item in a ContentList object. The TraceMessages property is read-only; however, the returned SimpleList object is read/write.

Definition

Get method:

HRESULT IContentList::get_TraceMessages(
long RowNum,
ISimpleList** TraceMessages
);

Parameters

RowNum

[in] A long that contains the position of the row for which the trace messages will be returned. Row positions start at zero (0), not one (1).

TraceMessages

[out,retval] The address of a pointer used to return the ISimpleList interface of the SimpleList object that contains the trace messages.

Return Values

These methods return an HRESULT indicating whether or not they completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The TraceMode property acts as a global switch to control whether any score tracing is performed. If it is set to True, score tracing is performed. If it is set to False, score tracing is suppressed.

When you use score tracing, you will notice a dramatic negative effect on performance; score tracing should not be used under normal circumstances. However, it can be useful when you are attempting to troubleshoot a scoring-related issue.

The list will be empty if the TraceMode property is set to False or if no score modifications have been made to the item.

Each item in the list is a string in the following format:

<component>,<operator><number>,<description>

Where the fields of the string are defined as follows:

component

The identifier of the component that made the score change, as passed to the AdjustScore, SetScore, and Filter methods.

operator

= if the score set to an absolute value by the SetScore or Filter methods, or * if a multiplier was applied to the score by the AdjustScore method.

number

The score returned by the SetScore method after any adjustments by the Filter or AdjustScore methods.

description

The reason for the score change, as passed to the AdjustScore or SetScore methods, and set by the Filter method.

An example score tracing string is:

"Commerce.AdNod,=0.9875,Need of Delivery".

See Also

ContentList Object


IContentList::get_TraceMode, put_TraceMode

The TraceMode property is a read/write Boolean that controls whether score tracing is enabled or suppressed.

Definition

Get method:

HRESULT IContentList::get_TraceMode(
VARIANT_BOOL* TraceMode
);

Put method:

HRESULT IContentList::put_TraceMode(
VARIANT_BOOL TraceMode
);

Parameters

TraceMode

[out,retval] When getting the property, a pointer to a VARIANT_BOOL used to return the current trace mode setting. A value of True enables score tracing. A value of False suppresses score tracing.
[in] When putting the property, a VARIANT_BOOL that contains a new trace mode setting. A value of True enables score tracing. A value of False suppresses score tracing.

Return Values

These methods return an HRESULT indicating whether or not they completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

This property acts as a global switch to control whether or not score tracing is performed. If it is set to True, a SimpleList object of trace messages will be constructed that can be accessed through the TraceMessages property. If it is set to False, score tracing is suppressed.

When you use score tracing, you will notice a dramatic negative effect on performance; score tracing should not be used under normal circumstances. However, it can be useful when you are attempting to troubleshoot a scoring-related issue.

See Also

ContentList Object


ContentListFactory Object

Use this object to efficiently maintain lists of content items that compete with each other to be selected for display on a Web page by a Content Selection pipeline (CSP).

ProgID: | Commerce.ContentListFactory (Externally creatable)
COM Class Name: | ContentListFactory
COM Interface Name: | IContentListFactory
Interface ID Constant: | IID_IContentListFactory
Header File: | cacheint.h, mspu_guids.h
Type Library Name: | Microsoft Commerce 2000 Cache Manager Type Library
DLL Name: | mscscache.dll
Threading Model: | Both

The properties of the ContentListFactory object are shown in the following table.

Property | Type | Description
AllRows | IRowCollection | The collection of all rows in the ContentListFactory object. This property is read-only.
Count | long | The number of rows in the ContentListFactory object. This property is read/write.
Fields | Fields | The Fields collection for a particular row in the ContentListFactory object. This property is read-only.
Schema | IContentListSchema | Stores a reference to the ContentListSchema object used by this ContentListFactory object. This property is read/write.

The methods of the ContentListFactory object are shown in the following table.

Method | Description
BuildIndex | Builds an index on the specified column.
ConstructFromRecordset | Initializes a ContentListFactory object, and creates and initializes a new ContentListSchema object, from an ADO Recordset object. The ContentListFactory object is populated with the data from the Recordset object.
CreateNewContentList | Creates a new ContentList object based on the schema in use by this ContentListFactory object. The new ContentList object has access to the shared data in the ContentListFactory object that created it.
GetData | Gets data from a specified row and column in a ContentListFactory object in a high-performance, non-scriptable manner.
Search | Returns a RowCollection object containing the collection of content items that match the search criteria.
SetData | Sets data at a specified row and column in a ContentListFactory object in a high-performance, non-scriptable manner.

Remarks

Important

  • The ContentList and the ContentListFactory objects are designed to be run in-process with their clients. The GetData and SetData methods assume direct memory access for performance reasons.

Both the ContentList object and the ContentListFactory object implement a common interface, IDataContainer. Therefore they share the following methods and properties, which are functionally identical on both objects:

Properties:

  • AllRows

  • Count

  • Fields

Methods:

  • BuildIndex

  • GetData

  • Search

  • SetData


IContentListFactory::get_AllRows

The AllRows property returns a new RowCollection object that allows access to the items in the ContentListFactory object. The AllRows property is read-only; however, the RowCollection object is read/write in that changes made using this object are reflected in the ContentListFactory object.

Definition

Get method:

HRESULT IContentListFactory::get_AllRows(
IRowCollection** AllRows
);

Parameters

AllRows

[out,retval] The address of a pointer used to return the IRowCollection interface of a RowCollection object that contains all of the items in this ContentListFactory object.

Return Values

These methods return an HRESULT indicating whether or not they completed successfully. See the Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

This property is functionally identical to the one of the same name in the ContentList object.

See Also

ContentListFactory Object

RowCollection Object


IContentListFactory::BuildIndex

Use this method to build an index for a specific column in a ContentListFactory object.

Definition

HRESULT IContentListFactory::BuildIndex(
VARIANT vCol
);

Parameters

vCol

[in] A VARIANT that identifies the column for which the index will be built. The column is identified by either a number representing a column position, starting at zero (0), or a string containing a column name.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

S_FALSE

An index already exists on the column.

Remarks

An index can be built on any read-only, non-private column that is of type string, integer, or array of strings or integers. (CLCOL_READONLY and not CLCOL_PRIVATE). Also, only columns of type CLCOL_I2, CLCOL_I4, CLCOL_STRING, and CLCOL_VARIANTARRAY can be indexed.

If a search is conducted on a column for which no index yet exists, the index is automatically created. This means that, though you are never required to call the BuildIndex method, you may want to incur the cost of creating the index at a known time for performance sake.

This method is functionally identical to the one of the same name to be found in the ContentList object.

See Also

ContentListFactory Object


IContentListFactory::ConstructFromRecordset

Use this method to initialize a new ContentListFactory object, and create and initialize a new ContentListSchema object, from an ADO Recordset object.

Definition

HRESULT IContentListFactory::ConstructFromRecordset(
_Recordset* Recordset,
VARIANT Skip,
IContentListSchema* Add
);

Parameters

Recordset

[in] A pointer to an ADO Recordset object from which the ContentList object will be constructed.

Skip

[in,optional] A VARIANT that is a SimpleList object. The SimpleList object contains the names of field(s) that exist in the Recordset object but that should not have a column in the new ContentList object.

Add

[in,optional] A pointer to the IContentListSchema interface of a ContentListSchema object that contains information about additional columns or new flags for existing columns that should be accounted for when the new ContentList object is created. Refer to the Remarks section for additional information.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The Skip and Add parameters are both optional.

Columns defined in the ContentListSchema object that do not exist in the Recordset object are added to the new schema for the ContentListFactory object. Schema columns defined in both the ContentListSchema object and in the Recordset object get their flag settings from the former object, overriding the default flag settings otherwise applied. Supplemental columns may be either shared or private. Data for any supplemental, shared columns should be initialized using the SetData method. Data for any supplemental, private columns cannot be provided until a corresponding ContentList object is created.

The default value for dwFlags for columns created from the fields of the Recordset object is CLCOL_READONLY.

The ContentListFactory object attempts to access the RecordCount property of the RecordSet to determine how many rows of data for which space should be allocated. Not all types of RecordSets support this. If the RecordCount property cannot be determined, the ContentListFactory object will grow the factory in chunks of 100 rows. For this reason, it is most efficient to pass a RecordSet for which the RecordCount property is defined.

Column types are mapped from the Recordset object according to the following table.

ADO Type | ContentList Type
adSmallInt, adUnsignedSmallInt | CLCOL_I2
adInteger, adUnsignedInt, adError | CLCOL_I4
adSingle | CLCOL_I4
adDouble | CLCOL_R8
adDBDate, adDBTime, adDBTimeStamp | CLCOL_DATE
adChar, adVarChar, adLongVarChar, adWChar, adVarWChar, adLongVarWChar | CLCOL_STRING
adChapter*, adDispatch | CLCOL_DISPATCH
adChapter | CLCOL_UNKNOWN
adBoolean | CLCOL_BOOL

Note

  • *One level hierarchical Recordset objects are supported. The child Recordset objects are created in the ContentList object as a SimpleList of Dictionary objects.

See Also

ContentListFactory Object


IContentListFactory::get_Count, put_Count

The Count property is a read/write number that gets or sets the number of content items in a ContentListFactory object.

Definition

Get method:

HRESULT IContentListFactory::get_Count(
long* Count
);

Put method:

HRESULT IContentListFactory::put_Count(
long Count
);

Parameters

Count

[in] When putting the property, a long that contains the item count.
[out,retval] When getting the property, a pointer to a long used to return the item count.

Return Values

These methods return an HRESULT indicating whether or not they completed successfully. See the Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The Count property cannot be changed once ContentList objects have been created by the ContentListFactory object. Also, the Count property cannot be set to a smaller number than its current setting.

This property is functionally identical to the one of the same name to be found in the ContentList object.

See Also

ContentListFactory Object


IContentListFactory::CreateNewContentList

Use this method to create a new ContentList object based on the schema established for this ContentListFactory object. The new ContentList object provides a unified interface to the private data that it stores and to the shared data stored in the ContentListFactory object (that created it).

Definition

HRESULT IContentListFactory::CreateNewContentList(
IContentList** NewList
);

Parameters

NewList

[out,retval] The address of a pointer used to return the new ContentList object.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The new ContentList object will be based on the established schema for this ContentListFactory object. Storage for columns marked as CLCOL_PRIVATE in the schema is allocated in the ContentList object. The ContentList object maintains a pointer back to the factory that created it, which is where the storage for "shared" columns is maintained.

A ContentList object cannot exist independently of a ContentListFactory object.

The only prerequisite for calling this method is that a schema has been established. This can be accomplished by setting the Schema property or by calling the ConstructFromRecordset method.

See Also

ContentListFactory Object


IContentListFactory::get_Fields

The Fields property creates a new Fields object that allows access to the fields for a specified content item. The Fields property is read-only; however, the Fields object is read/write in that changes made using this object are reflected in the ContentListFactory object.

Definition

Get method:

HRESULT IContentListFactory::get_Fields(
long RowNum,
Fields** Fields
);

Parameters

RowNum

[in] A long that contains the position of the item in the ContentListFactory object for which a Fields object will be returned. Positions are counted from 0, not from 1.

Fields

[out,retval] The address of a pointer used to return a Fields object for the specified row in the ContentListFactory object.

Return Values

These methods return an HRESULT indicating whether or not they completed successfully. See the Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The Fields object exposes the same interface as the ADO Fields object.

This property is functionally identical to the one of the same name to be found in the ContentList object.

See Also

ContentListFactory Object


IContentListFactory::GetData

Use this method to read data from a specified row and column in a ContentListFactory object.

This is one of the two ContentListFactory methods that do not support a scriptable interface. The other method is SetData. They are only intended for use in C++.

Definition

HRESULT IContentListFactory::GetData(
long iRow,
long iCol,
BYTE* pData
);

Parameters

iRow

[in] A long that contains the position of the row from which the data should be read. Row positions are counted from 0, not 1.

iCol

[in] A long that contains the position of the column within the specified row from which the data should be read. Column positions are counted from 0, not 1.

pData

[out] A pointer to where the data should be written.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The GetData method does not do any type checking. The memory pointed to by the pData parameter must be of sufficient size to receive the value being read. If the allotted memory is too small, memory corruption occurs.

The ContentListFactory object stores some types of data by value and other types of data by reference. Therefore, how you use the GetData and SetData methods depends on the data type.

When you pass a pointer to a String to the SetData method, it stores the String in the ContentListFactory object, not the pointer. The GetData method returns a pointer to the String in the ContentListFactory object, but not the String. Do not hold a reference to the String in the ContentListFactory object beyond the lifetime of the object, as it will be invalid after the object is destroyed. The ContentListFactory object only stores wide character Unicode strings. ANSI strings are not supported.

When you pass an interface pointer to an object to the SetData method, it calls the AddRef method on the interface referenced by the pointer and stores the pointer in the ContentListFactory object. The GetData method returns this pointer and calls the AddRef method on the interface referenced by it. The caller must release the pointer returned by the GetData method.

When you pass a pointer to a SafeArray to the SetData method, it locks the SafeArray and stores a reference to it in the ContentListFactory object. The GetData method returns a reference to the locked array. The caller should not unlock the array as this could invalidate the reference stored in the ContentListFactory object. It is safe to store the array in a Variant of type VT_ARRAY or VT_VARIANT, as a call to the VariantClear method will not release the SafeArray because it is locked. When the ContentListFactory object is destroyed, the SafeArray will be unlocked and the SafeArrayDestroy method will be called. Since SafeArrays have a lock count similar to reference counting the array data will be released only if the lock count is zero.

The GetData method reads all other supported data types by value.

This method is functionally identical to the one of the same name in the ContentList object.

See Also

ContentListFactory Object


IContentListFactory::get_Schema, put_Schema

The Schema property is a ContentListSchema object that contains the schema used by this ContentListFactory object. The Schema property is read/write.

Definition

Get method:

HRESULT IContentListFactory::get_Schema(
IContentListSchema** Schema
);

Put method:

HRESULT IContentListFactory::put_Schema(
IContentListSchema* Schema
);

Parameters

Schema

[in] When putting the property, a pointer to the IContentListSchema interface of the ContentListSchema object that contains the new schema for this ContentListFactory object.
[out,retval] When getting the property, a pointer to an address used to return the IContentListSchema interface of the ContentListSchema object that contains the schema for this ContentListFactory object.

Return Values

These methods return an HRESULT indicating whether or not they completed successfully. See the Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

This property is intended to only be set once. However, until any ContentList object is created using the CreateNewContentList method, or until rows are allocated in the ContentListFactory object by setting the Count property, it can be changed.

If this property is read before it is written, an empty ContentListSchema object will be created and returned.

See Also

ContentListFactory Object


IContentListFactory::Search

Use this method to create a RowCollection object that allows access to each item in the ContentListFactory object that matches the specified criterion.

Definition

HRESULT IContentListFactory::Search(
VARIANT vCol,
VARIANT vSearchCriteria,
IRowCollection** ppIRowCollection
);

Parameters

vCol

[in] A VARIANT that identifies the column to search. The column is identified by either a number representing a column position (starting at 0) or a string containing a column name.

vSearchCriteria

[in] A VARIANT that contains the filter criterion. The criterion is usually a BSTR, an array of BSTRs, or an Integer. An attempt will be made to coerce other types to the type of the column being searched.

ppIRowCollection

[out,retval] A pointer to an address to receive an IRowCollection interface pointer for a new RowCollection object that allows access to the rows that match the search criteria.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

S_FALSE

No rows in the ContentListFactory object matched the filter criteria. As a result, the returned RowCollection is empty.

Remarks

Columns must be shared (not private) and read-only in order to be indexed and searched. Columns must also be of type string, integer (long or short), or variant array to be searchable. The search criteria may be any variant type that can be coerced to the type of the column being searched.

When the search criteria is an array of variants, the set of rows returned contains all rows that match any of the search criteria array elements. It is a union of the matches.

This method is functionally identical to the one of the same name to be found in the ContentList object.

See Also

ContentListFactory Object


IContentListFactory::SetData

Use this method to write data to a specified row and column in a ContentListFactory object.

This is one of the two ContentListFactory methods that do not support a scriptable interface. The other method is GetData. They are only intended for use in C++.

Definition

HRESULT IContentListFactory::SetData(
long iRow,
long iCol,
BYTE* pData
);

Parameters

iRow

[in] A long that contains the position of the row into which the data should be written. Row positions are counted from 0, not 1.

iCol

[in] A long that contains the position of the column within the specified row into which the data should be written. Column positions are counted from 0, not 1.

pData

[in] A pointer to the data to write into the ContentListFactory object.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The SetData method does not do type checking for the data being written. The data pointed to by the pData parameter must be of the correct type for the column. Type (and especially size) mismatches will not result in memory scribbles (which is possible with the GetData method), but some of the data may not be written into the ContentListFactory object.

The ContentListFactory object stores some types of data by value and other types of data by reference. Therefore, how you use the GetData and SetData methods depends on the data type.

When you pass a pointer to a String to the SetData method, it stores the String in the ContentListFactory object, not the pointer. The GetData method returns a pointer to the String in the ContentListFactory object, but not the String. Do not hold a reference to the String in the ContentListFactory object beyond the lifetime of the object, as it will be invalid after the object is destroyed. The ContentListFactory object only stores wide character Unicode strings. ANSI strings are not supported.

When you pass an interface pointer to an object to the SetData method, it calls the AddRef method on the interface referenced by the pointer and stores the pointer in the ContentListFactory object. The GetData method returns this pointer and calls the AddRef method on the interface referenced by it. The caller must release the pointer returned by the GetData method.

When you pass a pointer to a SafeArray to the SetData method, it locks the SafeArray and stores a reference to it in the ContentListFactory object. The GetData method returns a reference to the locked array. The caller should not unlock the array as this could invalidate the reference stored in the ContentListFactory object. It is safe to store the array in a Variant of type VT_ARRAY or VT_VARIANT, as a call to the VariantClear method will not release the SafeArray because it is locked. When the ContentListFactory object is destroyed, the SafeArray will be unlocked and the SafeArrayDestroy method will be called. Since SafeArrays have a lock count similar to reference counting the array data will be released only if the lock count is zero.

The SetData method stores all other supported data types by value.

Objects must be "both threaded" and must aggregate the Free Threaded Marshaller in order to be stored in a ContentListFactory object. If you ignore this restriction, marshalling errors may occur.

This method is functionally identical to the one of the same name to be found in the ContentList object.

See Also

ContentListFactory Object


ContentListSchema Object

Use this object to manipulate the schema for a ContentListFactory object.

ProgID: | Commerce.ContentListSchema (Externally creatable)
COM Class Name: | ContentListSchema
COM Interface Name: | IContentListSchema
Interface ID Constant: | IID_IContentListSchema
Header File: | cacheint.h, mspu_guids.h
Type Library Name: | Microsoft Commerce 2000 Cache Manager Type Library
DLL Name: | mscscache.dll
Threading Model: | Both

The properties of the ContentListSchema object are shown in the following table.

Property | Type | Description
ColumnFlags | long | Stores the column flags, represented as a bit field. This property is read/write.
ColumnName | BSTR | Stores the column name. This property is read/write.
ColumnType | ColumnTypeEnum | Stores the data type of the column. This property is read/write.
Count | long | Stores the number of columns defined by the schema. This property is read-only.
Locked | VARIANT_BOOL | Indicates whether this schema can be modified. This property is read/write. It is initially set to False. Once set to True, it can never be set back to False.

The methods of the ContentListSchema object are shown in the following table.

Method | Description
Add | Adds a new column to the schema.
FindColumn | Returns the position of a named column. Column positions are counted starting from zero (0), not one (1). This position index may be used as the Column index parameter for the GetData, SetData, Filter, and Search methods of the IContentList interface.
GetSchema | Returns the entire schema in a high-performance, non-scriptable manner.
SetSchema | Sets the entire schema in a high-performance, non-scriptable manner.

Remarks

The methods GetSchema and SetSchema are only accessible from C++. Respectively, they get and set the entire schema associated with a ContentListSchema object. They pass the schema as an array of CLCOL_DESCRIPTOR structures, where each element in the array represents a corresponding column in the schema, in the same order that they appear in the array.

The definition of a CLCOL_DESCRIPTOR structure is as follows:

typedef struct
{
  ColumnTypeEnum  coltyp;    // column type
  ULONG           lFlags;    // column flags, represented as a bit field
  ULONG           cchName;   // length of column name
  WCHAR*          pwszName;  // column name
} CLCOL_DESCRIPTOR;

The members of the CLCOL_DESCRIPTOR structure are described in the following table.

Structure Member | Description
coltyp | Contains a value indicating the data type associated with the column. This value should be from the set of values present in the ColumnTypeEnum enumeration. For more information about this enumeration, see the Remarks section of IContentListSchema::get_ColumnType, put_ColumnType
lFlags | Contains a value indicating the column flags associated with the column, represented as a bit field.
cchName | Contains a value indicating the length of the column name string, in characters.
pwszName | Contains a pointer to a NULL-terminated string containing the name of the column.


IContentListSchema::Add

Use this method to add a new column to a schema for use by a ContentListFactory object and its associated ContentList objects.

Definition

HRESULT IContentListSchema::Add(
BSTR sName,
ColumnTypeEnum Type,
long Flags,
long* ColumnNum
);

Parameters

sName

[in] A BSTR that contains a name for the new column.

Type

[in] A value from the ColumnTypeEnum enumeration. See the Remarks section for more details.

Flags

[in] A long that contains the bit mask column flag settings for the new column.

ColumnNum

[out,retval] A pointer to a long used to return the position of the new column. Column positions are numbered starting with zero (0), not one (1).

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

Once the Locked property has been set to True, subsequent calls to this method will fail. The ContentListFactory object will set the Locked property of its ContentListSchema object to True when one of the following conditions is met:

  • Rows of data are allocated in the factory by setting the Count property or calling the ConstructFromRecordset method.

  • The ContentListFactory object has been used to construct one or more ContentList objects using the CreateNewContentList method.

The following table shows the values of the ColumnTypeEnum enumeration, their associated names, and describes their use.

Name | Value | Description
CLCOL_I2 | 2 | A 16-bit integer. This value corresponds to the VARTYPE value VT_I2.
CLCOL_I4 | 3 | A 32-bit integer. This value corresponds to the VARTYPE value VT_I4.
CLCOL_R4 | 4 | A single precision floating point number. This value corresponds to the VARTYPE value VT_R4.
CLCOL_R8 | 5 | A double precision floating point number. This value corresponds to the VARTYPE value VT_R8.
CLCOL_CY | 6 | A 64-bit integer used to store a currency value. This value corresponds to the VARTYPE value VT_CY. Monetary values stored using this type are scaled by 10,000 (4 decimal places). For example, the value 86900 would correspond to a currency value of $8.69 in the US. This is also the same as the money datatype used by SQL7.
CLCOL_DATE | 7 | A double precision floating point number used to store a date/time value. This value corresponds to the VARTYPE value VT_DATE.
CLCOL_DISPATCH | 9 | A reference to an object that supports scripting/automation (inherits from IDispatch). This value corresponds to the VARTYPE value VT_DISPATCH.
CLCOL_BOOL | 11 | A boolean value. This value corresponds to the VARTYPE value VT_BOOL. Do not confuse this with the C++ type BOOL, which is 4 bytes.
CLCOL_UNKNOWN | 13 | A pointer to an IUnknown-based interface that, presumably, does not support scripting/automation (inherits from IUnknown). This value corresponds to the VARTYPE value VT_UNKNOWN.
CLCOL_STRING | 14 | A pointer to a string in the private heap maintained by every ContentListFactory object. There is no corresponding VARTYPE value.
CLCOL_VARIANTARRAY | 15 | A pointer to a SAFEARRAY. The corresponding variant type is VT_ARRAY or VT_VARIANT.

Note

  • With the exception of CLCOL_STRING and CLCOL_VARIANTARRAY, these types are identical to the corresponding VARTYPE and share the same constant value. They may be used as a VARTYPE.

See Also

ContentListSchema Object


IContentListSchema::get_ColumnFlags, put_ColumnFlags

The ColumnFlags property is a read/write long that contains the column flags.

Definition

Get method:

HRESULT IContentListSchema::get_ColumnFlags(
VARIANT vColumn,
long* ColumnFlags
);

Put method:

HRESULT IContentListSchema::put_ColumnFlags(
VARIANT vColumn,
long ColumnFlags
);

Parameters

vColumn

[in] A VARIANT that contains either the column name or the column position in order to identify the column in question. Column positions are counted from zero (0), not one (1).

ColumnFlags

[in] When setting the property, a long that contains the new column flag settings, represented as a bit field.
[out,retval] When getting the property, a pointer to a long used to return the current column flag settings, represented as a bit field.

Return Values

These methods return an HRESULT indicating whether or not they completed successfully. See the Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

Column flags are represented as a bit field. The following table shows the meanings of the bits that are used and the constants provided for manipulating those bits.

Bit | Constant | Description
1 | CLCOL_READONLY (= 0x01) | When the bit is set, data in the column is read-only, and cannot be updated. This will be common for data stored in the ContentListFactory object since that data is shared between multiple page requests. When the bit is cleared, data in the column is read/write, and can be freely updated. No record locking is performed, so update contention could occur when updating data in the ContentListFactory object. This is not a concern for columns that are marked Private since they exist in the individual instances of ContentList objects, and ContentList objects are typically created for and used by a single thread.
2 | CLCOL_PRIVATE (= 0x02) | When the bit is set, the data in the column is private to each ContentList object based on this schema. This means that the data is stored separately in each ContentList object that is created, and not stored in the shared columns in the corresponding ContentListFactory object.
4 | CLCOL_SCORE_COLUMN (= 0x04) | When the bit is set it indicates that the data in this column is the score value associated with the content item. The type of this column must be a single-precision floating-point type (CLCOL_R4); only one column in the schema can have this flag set. Further, since a unique score value must be associated with each individual page request, this bit can only be set in conjunction with the CLCOL_PRIVATE bit. In other words, it must be a column stored in the ContentList object, as opposed to the ContentListFactory object, that is marked as the score column.

See Also

ContentListSchema Object


IContentListSchema::get_ColumnName, put_ColumnName

The ColumnName property is a read/write string that contains the name of the column.

Definition

Get method:

HRESULT IContentListSchema::get_ColumnName(
VARIANT vColumn,
BSTR* ColumnName
);

Put method:

HRESULT IContentListSchema::put_ColumnName(
VARIANT vColumn,
BSTR ColumnName
);

Parameters

vColumn

[in] A VARIANT that contains either the column name or the column position in order to identify the column in question. Column positions are counted from zero (0), not one (1).

ColumnName

[in] When putting the property, a BSTR that contains the new column name.
[out,retval] When getting the property, a pointer to a BSTR used to return the current column name.

Return Values

These methods return an HRESULT indicating whether or not they completed successfully. See the Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

Though using a column name as the value of the vColumn parameter in order to retrieve that same column name may be fruitless, passing a column name does make sense when changing the column name.

See Also

ContentListSchema Object


IContentListSchema::get_ColumnType, put_ColumnType

The ColumnType property is a read/write value from the ColumnTypeEnum enumeration, specifying the data type of the specified column.

Definition

Get method:

HRESULT IContentListSchema::get_ColumnType(
VARIANT vColumn,
ColumnTypeEnum* ColumnType
);

Put method:

HRESULT IContentListSchema::put_ColumnType(
VARIANT vColumn,
ColumnTypeEnum ColumnType
);

Parameters

vColumn

[in] A VARIANT that contains either the column name or the column position in order to identify the column in question. Column positions are counted from zero (0), not one (1).

ColumnType

[in] When putting the property, a value from the ColumnTypeEnum enumeration. See the Remarks section for more details.

[out,retval] When getting the property, a pointer used to return a value from the ColumnTypeEnum enumeration. See the Remarks section for more details.

Return Values

These methods return an HRESULT indicating whether or not they completed successfully. See the Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The following table shows the values of the ColumnTypeEnum enumeration, their associated names, and describes their use.

Name | Value | Description
CLCOL_I2 | 2 | A 16-bit integer. This value corresponds to the VARTYPE value VT_I2.
CLCOL_I4 | 3 | A 32-bit integer. This value corresponds to the VARTYPE value VT_I4.
CLCOL_R4 | 4 | A single precision floating point number. This value corresponds to the VARTYPE value VT_R4.
CLCOL_R8 | 5 | A double precision floating point number. This value corresponds to the VARTYPE value VT_R8.
CLCOL_CY | 6 | A 64-bit integer used to store a currency value. This value corresponds to the VARTYPE value VT_CY. Monetary values stored using this type are scaled by 10,000 (4 decimal places). For example, the value 86900 would correspond to a currency value of $8.69 in the US. This is also the same as the money datatype used by SQL7.
CLCOL_DATE | 7 | A double precision floating point number used to store a date/time value. This value corresponds to the VARTYPE value VT_DATE.
CLCOL_DISPATCH | 9 | A reference to an object that supports scripting/automation (inherits from IDispatch). This value corresponds to the VARTYPE value VT_DISPATCH.
CLCOL_BOOL | 11 | A boolean. This value corresponds to the VARTYPE value VT_BOOL. Do not confuse this with the C++ type BOOL, which is 4 bytes.
CLCOL_UNKNOWN | 13 | A pointer to an IUnknown-based interface that, presumably, does not support scripting/automation (inherits from IUnknown). This value corresponds to the VARTYPE value VT_UNKNOWN.
CLCOL_STRING | 14 | A pointer to a string in the private heap maintained by every ContentListFactory object. There is no corresponding VARTYPE value.
CLCOL_VARIANTARRAY | 15 | A pointer to a SAFEARRAY. The corresponding variant type is VT_ARRAY or VT_VARIANT.

Note

  • With the exception of CLCOL_STRING and CLCOL_VARIANTARRAY, these types are identical to the corresponding VARTYPE and share the same constant value. Indeed, they may be used as a VARTYPE.

See Also

ContentListSchema Object


IContentListSchema::get_Count

The Count property is a read-only value that contains the current number of columns in the schema.

Definition

Get method:

HRESULT IContentListSchema::get_Count(
long* Count
);

Parameters

Count

[out,retval] A pointer to a long used to return the current number of columns in the schema.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

See Also

ContentListSchema Object


IContentListSchema::FindColumn

Use this method to find the position of a column specified by name.

Definition

HRESULT IContentListSchema::FindColumn(
BSTR sName,
long* ColumnNum
);

Parameters

sName

[in] A BSTR that contains the name of the column for which the position will be returned.

ColumnNum

[out,retval] A pointer to a long used to return the position of the specified column.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

Column positions are counted from zero (0), not one (1).

See Also

ContentListSchema Object


IContentListSchema::GetSchema

Use this method to read the entire schema from a ContentListSchema object.

This is one of the two ContentListSchema methods that, in the interest of high performance, do not support a scriptable interface. The other method is SetSchema. They are only intended for use in C++.

Definition

HRESULT IContentListSchema::GetSchema(
long* pnCols,
CLCOL_DESCRIPTOR** prgColDesc
);

Parameters

pnCols

[out] A pointer to a long used to return the number of columns in the schema being returned. This value will be important in processing the array of column descriptors returned in the prgColDesc parameter.

prgColDesc

[out,size_is(,*pnCols)] The address of a pointer used to return the address of an array of CLCOL_DESCRIPTOR structures. These structures represent the entire schema, where each element in the array contains information regarding the column in that same position in the schema. For more information about the column descriptor structure, see ContentListSchema Object.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

Care must be taken in how the memory returned by calls to the GetSchema method gets released. The following code sample illustrates the proper technique:

// Declare variables for the GetSchema call.
long              cCols
CLCOL_DESCRIPTOR *pColDesc;

// Get the schema.
pContentListSchema->GetSchema(&cCols, &pColDesc);

// Use the returned schema as needed.

// When finished with the schema array,
// start by freeing the column name string memory.
for ( int i=0 ; I < cCols ; i++ ) {
    if ( NULL != pColDesc[i].pwszName ) {
        ::CoTaskMemFree(pColDesc[i].pwszName);
    }
}

// Then free the structure array memory.
::CoTaskMemFree(pColDesc);

See Also

ContentListSchema Object


IContentListSchema::get_Locked, put_Locked

The Locked property is a read/write Boolean that indicates whether the ContentListSchema object can be modified. A value of True indicates that the schema is locked and cannot be modified. A value of False indicates that the schema is not locked and can be modified. Once the object is in use it can no longer be modified.

Definition

Get method:

HRESULT IContentListSchema::get_Locked(
VARIANT_BOOL* Locked
);

Put method:

HRESULT IContentListSchema::put_Locked(
VARIANT_BOOL Locked
);

Parameters

Locked

[in] When setting the property, a VARIANT_BOOL that specifies a new lock setting. Since schemas, once locked, cannot be unlocked, only the first call to this method with the Locked parameter set to True will have any effect.
[out,retval] When getting the property, a pointer to a VARIANT_BOOL used to return the state of the schema lock. A value of True indicates that the schema has been locked. A value of False indicates that the schema not yet been locked.

Return Values

These methods return an HRESULT indicating whether or not they completed successfully. See the Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

A ContentListSchema object becomes permanently locked as soon as this property is set to True. Once locked, the contained schema cannot be modified or unlocked. ContentListFactory objects will lock the schema as soon as any rows are allocated or any ContentList objects are created, whichever occurs first.

See Also

ContentListSchema Object


IContentListSchema::SetSchema

Use this method to write an entire schema to a ContentListSchema object.

This is one of the two ContentListSchema methods that, in the interest of high performance, do not support a scriptable interface. The other method is GetSchema. They are only intended for use in C++.

Definition

HRESULT IContentListSchema::SetSchema(
long nCols,
CLCOL_DESCRIPTOR* rgColDesc
);

Parameters

nCols

[in] A long that specifies the number of columns in the column descriptor array passed in the rgColDesc parameter.

rgColDesc

[in,size_is(nCols)] A pointer to an array of CLCOL_DESCRIPTOR structures. These structures represent the entire schema, where each element in the array contains information regarding the column in that same position in the schema. For more information about the column descriptor structure, see ContentListSchema Object.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

See Also

ContentListSchema Object


ContentSelector Object

Use this object to select one or more items of content for display on a Web page. The content may come from customer campaigns (ads, discounts), or from custom applications built on the Content Selection Framework (CSF).

If you want to select custom content for display on your Web pages, you can use the CSF by instantiating and using ContentSelector objects. ContentSelector objects invoke different CSF pipelines to select different types of content based on the dictionary passed to the GetContent method.

ProgID: | Commerce.ContentSelector (Externally creatable)
COM Class Name: | CContentSelector
COM Interface Name: | IContentSelector
Interface ID Constant: | IID_IContentSelector
Header File: | csf.h, mspu_guids.h
Type Library Name: | Microsoft Commerce 2000 CSF Pipeline Component 1.0 Type Library
DLL Name: | CSFComp.dll
Threading Model: | Both

In C++, use the IContentSelector interface to access the properties of the ContentSelector object.

Because this object is primarily intended for use within ASP script, access from C++ will not be common.

The ContentSelector object implements all of the methods and properties of the Dictionary object, only the method not inherited from the Dictionary object is shown in the following table.

Method | Description
GetContent | Executes a Content Selection pipeline. The pipeline selects one or more content items. The selected content items are stored in a SimpleList object, formatted as strings of HTML or XML.

Remarks

The Context dictionary maintains a reference to a ContentSelector object in its ContextProfile entry. This ContentSelector object is used to pass arbitrary properties to the pipeline components. Arbitrary properties can be associated with the ContentSelector object because it inherits from the Dictionary object.

See Also

Content Selection Objects


IContentSelector::GetContent

Use this method to execute a Content Selection pipeline and return the resulting content in a SimpleList object.

Definition

HRESULT IContentSelector::get_GetContent(
IDictionary* pdictCSFContext,
ISimpleList** ppLstContent
);

Parameters

pdictCSFContext

[in] A pointer to a global context dictionary with a configuration for an instance of a CSF application. The dictionary contains global objects and configurations used by the ContentSelector object. At a minimum, the dictionary must contain the Pipeline key so that the ContentSelector object knows which pipeline to execute.

ppLstContent

[out, retval] A pointer to a SimpleList object containing the selected content. The elements of the SimpleList object are HTML or XML strings.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Note

  • This method can also return an error returned by the invoked pipeline.

Remarks

The ContentSelector object reads the Pipeline key of the passed in dictionary object to find the pipeline object to invoke. It copies the values of the dictionary passed to it into a new dictionary. The new dictionary is passed to the pipeline as the pipe Context dictionary. An empty dictionary is created and passed as the Order dictionary for the pipeline. The ContentSelector object adds a reference to itself under the ContextProfile key in the pipe Context dictionary.

When pipeline execution has completed, the ContentSelector object looks for the key _formatted in the Order dictionary, and returns the list assigned to that key as the return value. If the list assigned to the _formatted key does not exist, an empty list is created and returned. The self-reference in the pipe Context dictionary is removed to prevent a circular reference. References to the Order and Context dictionaries are added to the ContentSelector object before it returns, giving the page access to the values written into those dictionaries by the pipeline.

See Also

CacheManager Object

Content Selection Pipelines

ContentSelector Object


DataFunctions Object

Use this object to perform locale-based formatting, parsing, and value range checking in a site. This object also has a variety of utilities useful for site development.

ProgID: | Commerce.DataFunctions (Externally creatable)
COM Class Name: | DataFunctions_4_0
COM Interface Name: | IDataFunctions_4_0
Interface ID Constant: | IID_IDataFunctions_4_0
Header File: | commerce.h, mspu_guids.h
Type Library Name: | Commerce -- MSCSAspHelp Type Library
DLL Name: | MSCSAspHelp.dll
Threading Model: | Both

In C++, use the IDataFunctions_4_0 and IDataFunctions_3_0 interfaces to access the properties and methods of the DataFunctions object.

The properties of the DataFunctions object are shown in the following table.

Property | Type | Description
Locale | Long | Stores a number that represents the default locale to be used to format date, time, money, and number values. This property is read/write.
CurrencySymbol | VARIANT | Stores the currency symbol to use if no currency symbol is specified in the ConvertStringToCurrency and LocalizeCurrency methods. The default value is the system default currency symbol. This property is read/write.

The methods of the DataFunctions object are shown in the following table.

Method | Description
CleanString | Processes the specified string. This processing can include stripping out white spaces, modifying the case of the string, and validating that the length of the string falls within a specified range.
ConvertDateString | Converts the specified string representation of the date to a date VARIANT, based on the default or specified locale.
ConvertDateTimeString | Converts the specified string representation of the date and time to a date VARIANT, based on the default or specified locale.
ConvertFloatString | Converts the specified string representation of a floating-point number to a double VARIANT, based on the default or specified locale.
ConvertMoneyStringToNumber | Converts the specified string representation of a currency value to a long VARIANT, based on the default or specified locale.
ConvertNumberString | Converts the specified string representation of a number to an integer VARIANT, based on the default or specified locale.
ConvertTimeString | Converts the specified string representation of a time value to a date VARIANT, based on the default or specified locale.
Date | Returns a string representation of a date stored in a date VARIANT, based on the default or specified locale.
DateTime | Returns a string representation of a date and time stored in a date VARIANT, based on the default or specified locale.
Float | Returns a string representation of a floating-point number, based on the default or specified locale.
GetLocaleInfo | Retrieves information about the specified locale.
GetLocaleList | Retrieves a list of installed locales.
Money | Returns a formatted currency string, based on the default or specified locale.
Number | Returns a string representation of a number, based on the default or specified locale.
Time | Returns a string representation of a time stored in a date VARIANT, based on the default or specified locale.
ValidateDateTime | Checks whether the specified string contains a valid date and/or time, and optionally checks against a specified range.
ValidateFloat | Checks whether the specified string contains a valid floating-point number, and optionally checks the value of the number against a specified range.
ValidateNumber | Checks whether the specified string contains a valid number, and optionally checks the value of the number against a specified range.
CloneObject | Clones a SimpleList or Dictionary object.
ConvertStringToCurrency | Converts the specified string representation of currency value into a currency VARIANT.
LocalizeCurrency | Creates a string representation of a currency value formatted to a specified locale and currency symbol.


IDataFunctions_4_0::CleanString

Use this method to process a string, based on the default or specified locale. The string processing can include stripping out leading and trailing white spaces, modifying string case, and validating that the length of the string falls within a given range.

Definition

HRESULT IDataFunctions_4_0::CleanString(
VARIANT vtInput,
VARIANT vtMinLen,
VARIANT vtMaxLen,
VARIANT vtStripWhite,
VARIANT vtStripReturn,
VARIANT vtCase,
VARIANT vtLocale,
VARIANT* pvarOutput
);

Parameters

vtInput

[in] A VARIANT that contains the text of the string to process.

vtMinLen

[in] A VARIANT that contains the minimum length against which the length of the input string will be validated. The default value for this parameter is zero (0).

vtMaxLen

[in] A VARIANT that contains the maximum length against which the length of the input string will be validated. The default value for this parameter is no limit.

vtStripWhite

[in] A VARIANT that contains a Boolean value that indicates whether leading and trailing white spaces should be stripped from the input string. The default value is TRUE.

vtStripReturn

[in] A VARIANT that contains the Boolean value that indicates whether the carriage returns contained anywhere in the input string should be stripped. The default value is TRUE.

vtCase

[in] A VARIANT that specifies any conversions to the case of the input string. The default value for this parameter is zero (0), which results in no modification to the case of the input string. If this parameter is set to one (1), the input string is converted to uppercase. If this parameter is set to two (2), the input string is converted to lowercase.

vtLocale

[in] A VARIANT that specifies the locale to use when processing the input string. If this parameter is not specified, the value of the Locale property of the DataFunctions object is used.

pvarOutput

[out, retval] A pointer used to return a VARIANT that contains the processed string.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pvarOutput parameter contains valid data only if the method completes successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

DataFunctions Object

IDataFunctions_4_0::get_Locale, put_Locale

IMSCSPage_3_0::RequestString


IDataFunctions_4_0::CloneObject

Use this method to clone a SimpleList or Dictionary object. This method performs a deep copy of the cloned object, so new memory is allocated for the clone.

Definition

HRESULT IDataFunctions_4_0::CloneObject(
IDispatch* pdispSource,
IDispatch** ppdispDest
);

Parameters

pdispSource

[in] A pointer to the IDispatch interface of the SimpleList or Dictionary object to be cloned.

ppdispDest

[out, retval] The address of a pointer used to return the IDispatch interface of the SimpleList or Dictionary object clone.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The ppdispDest parameter contains valid data only if the method completes successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

DataFunctions Object

IDataFunctions_4_0::get_Locale, put_Locale


IDataFunctions_4_0::ConvertDateString

Use this method to convert a date string to a date Variant, based on the default or specified locale.

Definition

HRESULT IDataFunctions_4_0::ConvertDateString(
VARIANT vtDate,
VARIANT vtLocale,
VARIANT* pvtRet
);

Parameters

vtDate

[in] A VARIANT that contains a string representation of the date to convert.

vtLocale

[in] A VARIANT that specifies the locale to use when processing the string. If this parameter is not specified, the value of the Locale property of the DataFunctions object is used.

pvtRet

[out, retval] A pointer to a date VARIANT used to return the converted date.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pvtRet parameter contains valid data only if the method completes successfully.

In some cases, the DataFunctions.ConvertDateString method returns NULL when converting a string representation of the date to the date Variant type for Latvian and Bulgarian locales. To avoid this problem, remove the constant string added at the end of the Date Representation String according to the Regional Settings in the Control Panel.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

DataFunctions Object

IDataFunctions_4_0::get_Locale, put_Locale

IDataFunctions_4_0::ConvertDateTimeString

IDataFunctions_4_0::Date

IDataFunctions_4_0::DateTime

IMSCSPage_3_0::RequestTime


IDataFunctions_4_0::ConvertDateTimeString

Use this method to convert a date and time string to a date/time Variant, based on the default or specified locale.

Definition

HRESULT IDataFunctions_4_0::ConvertDateTimeString(
VARIANT vtDateTime,
VARIANT vtLocale,
VARIANT* pvtRet
);

Parameters

vtDateTime

[in] A VARIANT that contains a string that specifies the date/time value to convert.

vtLocale

[in] A VARIANT that specifies the locale to use to convert the date. If this value is not specified, the value of the Locale property of the DataFunctions object is used.

pvtRet

[out, retval] A pointer to a VARIANT used to return the converted date/time value.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pvtRet parameter contains valid data only if the method completes successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

DataFunctions Object

IDataFunctions_4_0::get_Locale, put_Locale

IDataFunctions_4_0::ConvertDateString

IDataFunctions_4_0::Date

IDataFunctions_4_0::DateTime

IMSCSPage_3_0::RequestTime


IDataFunctions_4_0::ConvertFloatString

Use this method to convert a floating-point number represented as a string to a double Variant, based on the default or specified locale.

Definition

HRESULT IDataFunctions_4_0::ConvertFloatString(
VARIANT vtNum,
VARIANT vtLocale,
VARIANT* pvtRet
);

Parameters

vtNum

[in] A VARIANT that contains a string representation of the floating-point number to convert.

vtLocale

[in] A VARIANT that specifies the locale to use to convert the string. If this parameter is not specified, the value of the Locale property of the DataFunctions object is used.

pvtRet

[out, retval] A pointer to a double VARIANT used to return the converted floating-point number.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pvtRet parameter contains valid data only if the method completed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

DataFunctions Object

IDataFunctions_4_0::get_Locale, put_Locale

IDataFunctions_4_0::Float

IDataFunctions_4_0::ValidateFloat


IDataFunctions_4_0::ConvertMoneyStringToNumber

Use this method to convert a money string to a number, based on the default or specified locale.

Definition

HRESULT IDataFunctions_4_0::ConvertMoneyStringToNumber(
VARIANT vtMoney,
VARIANT vtLocale,
VARIANT* pvtRet
);

Parameters

vtMoney

[in] A VARIANT that contains a string representation of the monetary value to convert.

vtLocale

[in] A VARIANT that specifies the locale to use to convert the string. If this parameter is not specified, the value of the Locale property of the DataFunctions object is used.

pvtRet

[out, retval] A pointer to a VARIANT used to return the converted monetary value.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pvtRet parameter contains valid data only if the method completes successfully.

The ConvertMoneyStringToNumber method returns the value in the base monetary unit for a given locale. Thus, given a value in dollars, ConvertMoneyStringToNumber returns the number of cents in the dollar value.

Additionally, ConvertMoneyStringToNumber does not round values. For example, if you pass this method "123.009" the method returns 12300, not 12301.

This method returns a Variant of type long, not an OLE currency type.

In some cases, this method returns NULL when converting a string representation of monetary value to the currency Variant type for Swedish and Portuguese Standard locales. To avoid this problem, use the Microsoft Visual Basic Scripting Edition (VBScript) function Replace(MoneyString, CurrencyDigitGroupingSymbol, "") to remove the currency digit grouping symbol from the money string prior to calling the method ConvertMoneyStringToNumber.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

DataFunctions Object

IDataFunctions_4_0::get_Locale, put_Locale

IDataFunctions_4_0::ConvertFloatString

IDataFunctions_4_0::ConvertNumberString


IDataFunctions_4_0::ConvertNumberString

Use this method to convert an integer represented as a string to an integer Variant, based on the default or specified locale.

Definition

HRESULT IDataFunctions_4_0::ConvertNumberString(
VARIANT vtNum,
VARIANT vtLocale,
VARIANT* pvtRet
);

Parameters

vtNum

[in] A VARIANT that contains a string representation of the number to convert.

vtLocale

[in] A VARIANT that specifies the locale to use to convert the string. If this parameter is not specified, the value of the Locale property of the DataFunctions object is used.

pvtRet

[out, retval] A pointer to a VARIANT used to return the converted number.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pvtRet parameter contains valid data only if the method completes successfully.

The ConvertNumberString method is designed to accept only integers. Passing a floating-point number as the vtNum parameter results in an error. To convert floating-point numbers, use the ConvertFloatString method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

DataFunctions Object

IDataFunctions_4_0::get_Locale, put_Locale

IDataFunctions_4_0::ConvertFloatString

IDataFunctions_4_0::Number

IDataFunctions_4_0::ValidateNumber


IDataFunctions_4_0::ConvertStringToCurrency

Use this method to convert a string representation of a monetary value into a currency Variant, based on the specified locale and currency symbol.

Definition

HRESULT IDataFunctions_4_0::ConvertStringToCurrency(
VARIANT vtMoneyString,
VARIANT vtLocale,
VARIANT vtCurrencySymbol,
VARIANT* pvtRet
);

Parameters

vtMoneyString

[in] A VARIANT that contains the currency string to convert.

vtLocale

[in, optional] A VARIANT that contains the locale to be used when converting the string to a currency VARIANT. If this parameter is not specified, the value of the Locale property of the DataFunctions object is used.

vtCurrencySymbol

[in, optional] A VARIANT that contains the currency symbol to expect when converting the currency string.

pvtRet

[out, retval] A pointer to a VARIANT used to return the string representation of the converted monetary value. This will be set to NULL if the monetary value string is not valid.

Return Values

The parameter pvtRet returns the parsed value or NULL if the input monetary value is not parsable. The method returns a failed HRESULT upon critical error, such as receiving an invalid argument.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pvtRet parameter contains valid data only if the method completes successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

DataFunctions Object

IDataFunctions_4_0::get_Locale, put_Locale

IDataFunctions_4_0::LocalizeCurrency

IDataFunctions_4_0::ConvertMoneyStringToNumber


IDataFunctions_4_0::ConvertTimeString

Use this method to convert a time string to a date Variant, based on the default or specified locale.

Definition

HRESULT IDataFunctions_4_0::ConvertTimeString(
VARIANT vtDate,
VARIANT vtLocale,
VARIANT* pvtRet
);

Parameters

vtDate

[in] A VARIANT that specifies a string representation of the time to convert.

vtLocale

[in] A VARIANT that specifies the locale to use to convert the string. If this parameter is not specified, the value of the Locale property of the DataFunctions object is used.

pvtRet

[out, retval] A pointer to a VARIANT used to return the converted time value.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pvtRet parameter contains valid data only if the method completes successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

DataFunctions Object

IDataFunctions_4_0::get_Locale, put_Locale

IDataFunctions_4_0::Time

IDataFunctions_4_0::ValidateDateTime


IDataFunctions_4_0::get_CurrencySymbol, put_CurrencySymbol

The CurrencySymbol property is a read/write string Variant that stores the currency symbol to use if the currency symbol parameter is not specified in the ConvertStringToCurrency and LocalizeCurrency methods. The default value is the system default currency symbol.

Definition

Get method:

HRESULT IDataFunctions_4_0::get_CurrencySymbol(
VARIANT* CurrencySymbol
);

Put method:

HRESULT IDataFunctions_4_0::put_CurrencySymbol(
VARIANT CurrencySymbol
);

Parameters

CurrencySymbol

[in] When putting the property, a string VARIANT that contains the currency symbol.
[out, retval] When getting the property, a pointer to a string VARIANT used to return the currency symbol.

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

When getting the property, the CurrencySymbol parameter contains valid data only if the property is accessed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

DataFunctions Object

IDataFunctions_4_0::ConvertStringToCurrency

IDataFunctions_4_0::LocalizeCurrency


IDataFunctions_4_0::Date

Use this method to convert a date Variant to a string representation of the specified date, based on the default or specified locale.

Definition

HRESULT IDataFunctions_4_0::Date(
DATE dtDate,
VARIANT vtLocale,
VARIANT* pvtRet
);

Parameters

dtDate

[in] A DATE VARIANT that contains the date to format.

vtLocale

[in] A VARIANT that specifies the locale to use to convert the date to a string. If this parameter is not specified, the value of the Locale property of the DataFunctions object is used.

pvtRet

[out, retval] A pointer to a VARIANT used to return the date value formatted as a string.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pvtRet parameter contains valid data only if the method completes successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

DataFunctions Object

IDataFunctions_4_0::get_Locale, put_Locale

IDataFunctions_4_0::DateTime

IDataFunctions_4_0::ValidateDateTime

IDataFunctions_4_0::ConvertDateString


IDataFunctions_4_0::DateTime

Use this method to convert a date Variant to a string representation of the specified date value based on the default or specified locale.

Definition

HRESULT IDataFunctions_4_0::DateTime(
DATE dtDate,
VARIANT vtLocale,
VARIANT* pvtRet
);

Parameters

dtDate

[in] A DATE that contains the date/time value to convert.

vtLocale

[in] A VARIANT that specifies the locale to use to convert the Date Variant to a string. If this parameter is not specified, the value of the Locale property of the DataFunctions object is used.

pvtRet

[out, retval] A pointer to a VARIANT used to return the string representation of the specified date/time value.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pvtRet parameter contains valid data only if the method completes successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

DataFunctions Object

IDataFunctions_4_0::get_Locale, put_Locale

IDataFunctions_4_0::Date

IDataFunctions_4_0::ValidateDateTime

IDataFunctions_4_0::Time


IDataFunctions_4_0::Float

Use this method to convert a number stored in a double to a string representation of that number, based on the default or specified locale.

Definition

HRESULT IDataFunctions_4_0::Float(
double fNumber,
VARIANT vtLocale,
VARIANT* pvtRet
);

Parameters

fNumber

[in] A double (8-byte floating point number) that contains the floating-point number to convert.

vtLocale

[in] A VARIANT that specifies the locale to use to convert the floating-point number to a string. If this parameter is not specified, the value of the Locale property of the DataFunctions object is used.

pvtRet

[out, retval] A pointer to a VARIANT used to return the string representation of the specified floating-point number.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pvtRet parameter contains valid data only if the method completes successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

DataFunctions Object

IDataFunctions_4_0::get_Locale, put_Locale

IDataFunctions_4_0::ValidateFloat

IDataFunctions_4_0::ConvertFloatString


IDataFunctions_4_0::GetLocaleInfo

Use this method to get information on the specified locale.

Definition

HRESULT IDataFunctions_4_0::GetLocaleInfo(
long vtInfo,
VARIANT vtLocale,
VARIANT* pvarRet
);

Parameters

vtInfo

[in] A long that specifies the type of locale information to return in the pvarRet parameter. This value must map to one of the LCTYPE constants. For information about these constants, see the Win32 SDK Help.

vtLocale

[in] A VARIANT that identifies the locale for which to return information. If this VARIANT is empty (VT_EMPTY) or null (VT_NULL), the method returns information for the locale specified by the most recent call to put_Locale.

pvarRet

[out, retval] A pointer to a VARIANT used to return the requested locale information.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pvtRet parameter contains valid data only if the method completes successfully.

The Locale property stores a number value that indicates the default locale to be used by the DataFunctions methods to format date, time, money, and number information. For those DataFunctions methods take a locale value for a parameter, if that value is not supplied, the value of this property is used.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

DataFunctions Object

IDataFunctions_4_0::get_Locale, put_Locale


IDataFunctions_4_0::GetLocaleList

Use this method to retrieve a SimpleList object that contains the locales available on the computer.

Definition

HRESULT IDataFunctions_4_0::GetLocaleList(
VARIANT* pvarList
);

Parameters

pvarList

[out, retval] A pointer to a VARIANT used to return a SimpleList object that specifies the locales available on the computer.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pvtRet parameter contains valid data only if the method completes successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

DataFunctions Object

IDataFunctions_4_0::get_Locale, put_Locale


IDataFunctions_4_0::get_Locale, put_Locale

The Locale property is a read/write long that indicates the default locale to be used by the DataFunctions methods to format date, time, money, and number information. Where the DataFunctions methods take a locale value for a parameter, if that value is not supplied, the value to which you initialize this property is used.

Definition

Get method:

HRESULT IDataFunctions_4_0::get_Locale(
long* Locale
);

Put method:

HRESULT IDataFunctions_4_0::put_Locale(
long Locale
);

Parameters

Locale

[in] When putting the property, a long that specifies the locale.
[out, retval] When getting the property, a pointer to a long used to return the locale.

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

Many of the methods implemented in the Commerce Server objects take locale identifiers as optional parameters. These identifiers are represented by unique hexadecimal codes.

The list of locale and language identifiers can be found in the National Language Support API. This specification can be found in the Microsoft Developer Network. (See Platform SDK, Windows Base Services, International Features).

This list is continually growing and further locale support may be added to any future product.

The following table contains a list of these hexadecimal locale identifiers.

Identifier | Locale
0x0000 | Language Neutral
0x0400 | Process Default Language
0x0401 | Arabic (Saudi Arabia)
0x0801 | Arabic (Iraq)
0x0c01 | Arabic (Egypt)
0x1001 | Arabic (Libya)
0x1401 | Arabic (Algeria)
0x1801 | Arabic (Morocco)
0x1c01 | Arabic (Tunisia)
0x2001 | Arabic (Oman)
0x2401 | Arabic (Yemen)
0x2801 | Arabic (Syria)
0x2c01 | Arabic (Jordan)
0x3001 | Arabic (Lebanon)
0x3401 | Arabic (Kuwait)
0x3801 | Arabic (U.A.E.)
0x3c01 | Arabic (Bahrain)
0x4001 | Arabic (Qatar)
0x0402 | Bulgarian
0x0403 | Catalan
0x0404 | Chinese (Taiwan)
0x0804 | Chinese (PRC)
0x0c04 | Chinese (Hong Kong)
0x1004 | Chinese (Singapore)
0x0405 | Czech
0x0406 | Danish
0x0407 | German (Standard)
0x0807 | German (Swiss)
0x0c07 | German (Austrian)
0x1007 | German (Luxembourg)
0x1407 | German (Liechtenstein)
0x0408 | Greek
0x0409 | English (United States)
0x0809 | English (United Kingdom)
0x0c09 | English (Australian)
0x1009 | English (Canadian)
0x1409 | English (New Zealand)
0x1809 | English (Ireland)
0x1c09 | English (South Africa)
0x2009 | English (Jamaica)
0x2409 | English (Caribbean)
0x2809 | English (Belize)
0x2c09 | English (Trinidad)
0x040a | Spanish (Traditional Sort)
0x080a | Spanish (Mexican)
0x0c0a | Spanish (Modern Sort)
0x100a | Spanish (Guatemala)
0x140a | Spanish (Costa Rica)
0x180a | Spanish (Panama)
0x1c0a | Spanish (Dominican Republic)
0x200a | Spanish (Venezuela)
0x240a | Spanish (Colombia)
0x280a | Spanish (Peru)
0x2c0a | Spanish (Argentina)
0x300a | Spanish (Ecuador)
0x340a | Spanish (Chile)
0x380a | Spanish (Uruguay)
0x3c0a | Spanish (Paraguay)
0x400a | Spanish (Bolivia)
0x440a | Spanish (El Salvador)
0x480a | Spanish (Honduras)
0x4c0a | Spanish (Nicaragua)
0x500a | Spanish (Puerto Rico)
0x040b | Finnish
0x040c | French (Standard)
0x080c | French (Belgian)
0x0c0c | French (Canadian)
0x100c | French (Swiss)
0x140c | French (Luxembourg)
0x040d | Hebrew
0x040e | Hungarian
0x040f | Icelandic
0x0410 | Italian (Standard)
0x0810 | Italian (Swiss)
0x0411 | Japanese
0x0412 | Korean
0x0812 | Korean (Johab)
0x0413 | Dutch (Standard)
0x0813 | Dutch (Belgian)
0x0414 | Norwegian (Bokmal)
0x0814 | Norwegian (Nynorsk)
0x0415 | Polish
0x0416 | Portuguese (Brazilian)
0x0816 | Portuguese (Standard)
0x0418 | Romanian
0x0419 | Russian
0x041a | Croatian
0x081a | Serbian (Latin)
0x0c1a | Serbian (Cyrillic)
0x041b | Slovak
0x041c | Albanian
0x041d | Swedish
0x081d | Swedish (Finland)
0x041e | Thai
0x041f | Turkish
0x0421 | Indonesian
0x0422 | Ukrainian
0x0423 | Belarusian
0x0424 | Slovenian
0x0425 | Estonian
0x0426 | Latvian
0x0427 | Lithuanian
0x0429 | Farsi
0x042a | Vietnamese
0x042d | Basque
0x0436 | Afrikaans
0x0438 | Faeroese

See Also

DataFunctions Object

IDataFunctions_4_0::GetLocaleList


IDataFunctions_4_0::LocalizeCurrency

Use this method to retrieve a string representation of a currency value formatted to a specified locale and currency symbol.

Definition

HRESULT IDataFunctions_4_0::LocalizeCurrency(
VARIANT cyCurrency,
VARIANT vtLocale,
VARIANT vtCurrencySymbol,
VARIANT* pvtRet
);

Parameters

cyCurrency

[in] A currency VARIANT that contains the value to format as a string.

vtLocale

[in, optional] A VARIANT that contains the locale to use when formatting the string.

vtCurrencySymbol

[in, optional] A VARIANT that contains the currency symbol to use when formatting the string.

pvtRet

[out, retval] A pointer to a VARIANT used to return the string representation of the currency value.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pvtRet parameter contains valid data only if the method completes successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

DataFunctions Object

IDataFunctions_4_0::get_Locale, put_Locale

IDataFunctions_4_0::ConvertStringToCurrency


IDataFunctions_4_0::Money

Use this method to convert a long that contains a monetary value to an equivalent string representation, based on the default or specified locale.

Definition

HRESULT IDataFunctions_4_0::Money(
long lMoney,
VARIANT vtLocale,
VARIANT* pvtRet
);

Parameters

lMoney

[in] A long that contains the monetary value to convert to a string, specified in the base monetary unit of the locale used to perform the conversion. (This value is not an OLE currency type.)

vtLocale

[in] A VARIANT that specifies the locale to use to convert the monetary value to a string. If this parameter is not specified, the value of the Locale property of the DataFunctions object is used.

pvtRet

[out, retval] A pointer to a VARIANT used to return the resultant string.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pvtRet parameter contains valid data only if the method completed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

DataFunctions Object

IDataFunctions_4_0::get_Locale, put_Locale

IDataFunctions_4_0::ConvertMoneyStringToNumber


IDataFunctions_4_0::Number

Use this method to convert a long integer to its equivalent string representation, based on the default or specified locale.

Definition

HRESULT IDataFunctions_4_0::Number(
long lNumber,
VARIANT vtLocale,
VARIANT* pvtRet
);

Parameters

lNumber

[in] A long that contains the number to convert to a string.

vtLocale

[in] A VARIANT that specifies the locale to use to convert the number to a string. If this parameter is not specified, the value of the Locale property of the DataFunctions object is used.

pvtRet

[out, retval] A pointer to a VARIANT used to return the string representation of the specified number.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pvtRet parameter contains valid data only if the method completes successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

DataFunctions Object

IDataFunctions_4_0::get_Locale, put_Locale

IDataFunctions_4_0::ConvertNumberString


IDataFunctions_4_0::Time

Use this method to converts a Date to a string representation of the time.

Definition

HRESULT IDataFunctions_4_0::Time(
DATE dtDate,
VARIANT vtLocale,
VARIANT* pvtRet
);

Parameters

dtDate

[in] A DATE type that contains the time value to convert.

vtLocale

[in] A VARIANT that specifies the locale to use to convert the time value to a string. If this parameter is not specified, the value of the Locale property of the DataFunctions object is used.

pvtRet

[out, retval] A pointer to a VARIANT used to return the string representation of the specified time value.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pvtRet parameter contains valid data only if the method completes successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

DataFunctions Object

IDataFunctions_4_0::get_Locale, put_Locale

IDataFunctions_4_0::ConvertTimeString


IDataFunctions_4_0::ValidateDateTime

Use this method to check whether a string contains a valid date, time, or date and time, and optionally to check against a specified range.

Definition

HRESULT IDataFunctions_4_0::ValidateDateTime(
VARIANT vtDate,
VARIANT vtMin,
VARIANT vtMax,
VARIANT* pvtValid
);

Parameters

vtDate

[in] A VARIANT that contains the value to validate. This value can be a date, a time, or both.

vtMin

[in] A VARIANT that contains a value specifying the low end of the range. The default value for this parameter is NULL, which means that the vtMin parameter is ignored in the range validation.

vtMax

[in] A VARIANT that contains a value specifying the high end of the range. The default value for this parameter is NULL, which means that the vtMax parameter is ignored in the range validation.

pvtValid

[out, retval] A pointer to a VARIANT used to return a Boolean that indicates whether the vtDate parameter is valid. A value of TRUE indicates the vtDate parameter is a valid date, time, or date/time, and that it is within the given range, if any.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pvtValid parameter contains valid data only if the method completes successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

DataFunctions Object

IDataFunctions_4_0::Date

IDataFunctions_4_0::DateTime

IDataFunctions_4_0::Time

IDataFunctions_4_0::ConvertDateString

IDataFunctions_4_0::ConvertDateTimeString

IDataFunctions_4_0::ConvertTimeString


IDataFunctions_4_0::ValidateFloat

Use this method to check whether a string contains a valid floating-point number, and to optionally check the value of the number against a specified range.

Definition

HRESULT IDataFunctions_4_0::ValidateFloat(
VARIANT vtNumber,
VARIANT vtMin,
VARIANT vtMax,
VARIANT* pvtValid
);

Parameters

vtNumber

[in] A VARIANT that contains the floating-point number to validate.

vtMin

[in] A VARIANT that contains a value specifying the low end of the range. The default value for this parameter is NULL, which means that the vtMin parameter is ignored in the range validation.

vtMax

[in] A VARIANT that contains a value specifying the high end of the range. The default value for this parameter is NULL, which means that the vtMax parameter is ignored in the range validation.

pvtValid

[out, retval] A pointer to a VARIANT used to return a Boolean that indicates whether the vtNumber parameter is valid. A value of TRUE indicates the vtNumber parameter is a valid floating-point number, and that it is within the given range, if any.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pvtValid parameter contains valid data only if the method completes successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

DataFunctions Object

IDataFunctions_4_0::Float

IDataFunctions_4_0::ConvertFloatString


IDataFunctions_4_0::ValidateNumber

Use this method to check whether a string representation of a number is valid, and optionally to check the value of the number against a specified range.

Definition

HRESULT IDataFunctions_4_0::ValidateNumber(
VARIANT vtNumber,
VARIANT vtMin,
VARIANT vtMax,
VARIANT* pvtValid
);

Parameters

vtNumber

[in] A VARIANT that contains a string representation of a number to validate.

vtMin

[in] A VARIANT that contains a value specifying the low end of the range. The default value for this parameter is NULL, which means that the vtMin parameter is ignored in the range validation.

vtMax

[in] A VARIANT that contains a value specifying the high end of the range. The default value for the vtMax parameter is NULL, which means that this parameter is ignored in the range validation.

pvtValid

[out, retval] A pointer to a VARIANT used to return a Boolean that indicates whether the vtNumber parameter is valid. A value of TRUE indicates the vtNumber parameter is a valid whole number, and that it is within the given range, if any.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pvtValid parameter contains valid data only if the method completes successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

DataFunctions Object

IDataFunctions_4_0::Number

IDataFunctions_4_0::ConvertNumberString


DBStorage Object

Use this method to map Dictionary and SimpleList objects to and from the database, primarily for the storage of receipt and order information. The DBStorage object is created as needed on each page.

ProgID: | Commerce.DBStorage (Externally creatable)
COM Class Name: | MSCSDBStorage_3_0
COM Interface Name: | IMSCSDBStorage_3_0
Interface ID Constant: | IID_IMSCSDBStorage_3_0
Header File: | mspu_guids.h
Type Library Name: | Commerce 1.0 Type Library
DLL Name: | Commerce.dll
Threading Model: | Both

In C++, use the IMSCSDBStorage_3_0 interface to access the properties and methods of the DBStorage object.

Because this object is primarily intended for use within ASP script, access from C++ will not be common.

The single property of the DBStorage object is shown in the following table.

Property | Type | Description
Mapping | IDispatch | Maps a database column to an entry in the OrderForm or Dictionary object that DBStorage uses to insert and retrieve data. This property is read/write.

The methods of the DBStorage object are shown in the following table.

Method | Description
CommitData | Updates one or more records in the database storage.
DeleteData | Deletes a row from the database storage, based on the data stored in a Dictionary or OrderForm object.
DeleteDataKey | Deletes a row of data from the database storage, based on the specified key.
GetData | Retrieves a row of data from the database storage, based on a specified key value.
InitStorage | Initializes the object. This method must be called prior to calling any other DBStorage method.
InsertData | Inserts the specified data into the database storage.
LookupData | Retrieves a single row from the database storage, based on the specified column names and values.
LookupMultipleData | Retrieves multiple results from the database storage.
ProcessData | Unpacks the data stored in the MarshalColumn column for a given row, and returns the resulting row in a Dictionary object.

Remarks

The DBStorage object serves as an interface between the site database and Dictionary and OrderForm objects. A DBStorage object contains methods for transferring data between the database and the data object.

Using the CreateObject method of the Server object to instantiate a DBStorage object will return an uninitialized instance of the DBStorage object. Use the InitStorage method to initialize the returned object instance. Attempting to call any other DBStorage method prior to calling the InitStorage method results in an error.

When the DBStorage object retrieves data from the database, it creates the appropriate type of data object (an OrderForm or Dictionary object), stores the requested data there, and then returns the data object. When the DBStorage object is used to save data in the database, you pass it the OrderForm or Dictionary object containing the data, and the DBStorage method copies the data from the data object into the database.

See Also

General Purpose Objects


IMSCSDBStorage_3_0::CommitData

Use this method to update the database table based on the contents of the specified Dictionary or OrderForm object.

Definition

HRESULT IMSCSDBStorage_3_0::CommitData(
VARIANT vtReserved,
IDispatch* pdispData
);

Parameters

vtReserved

[in] A VARIANT reserved for future use. The CommitData method ignores the value of this parameter.

pdispData

[in] An IDispatch interface pointer on the OrderForm or Dictionary object that contains the updated data.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The CommitData method does not support database tables containing fields of type TimeStamp. Instead, use the vtChanged parameter to the DBStorage.InitStorage method, which provides the same functionality as using TimeStamp fields.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

DBStorage Object

IMSCSDBStorage_3_0::InitStorage

IMSCSDBStorage_3_0::InsertData


IMSCSDBStorage_3_0::DeleteData

Use this method to delete a row from the data source, based on the data stored in the specified Dictionary or OrderForm object.

Definition

HRESULT IMSCSDBStorage_3_0::DeleteData(
VARIANT vtReserved,
IDispatch* pdispData
);

Parameters

vtReserved

[in] A VARIANT reserved for future use. This parameter is ignored by the DeleteData method.

pdispData

[in] A pointer to the data object to delete. This data object can be either an OrderForm or a Dictionary, but must correspond in type to the object type specified as the ProgID in the initial call to the InitStorage method.

Return Values

This method returns an HRESULT indicating whether it or not completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The DeleteDataKey method differs from the DeleteData method in that the DeleteDataKey requires only the value stored in the key column of the underlying table. This is the column specified as the key to the underlying table through a previous call to the InitStorage method.

Thus, if you specify an IDENTITY field in an SQL table as the key into the data source, you can delete all the columns for a specified row by simply providing the appropriate counter value. Alternatively, you can initialize a Dictionary object to the values stored in one or more columns, and pass this initialized object to the DeleteData method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

DBStorage Object

IMSCSDBStorage_3_0::InitStorage

IMSCSDBStorage_3_0::DeleteDataKey

IMSCSDBStorage_3_0::InsertData


IMSCSDBStorage_3_0::DeleteDataKey

Use this method to delete a row of data, based on the specified key value.

Definition

HRESULT IMSCSDBStorage_3_0::DeleteDataKey(
VARIANT vtReserved,
VARIANT vtKey
);

Parameters

vtReserved

[in] This parameter is reserved for future use and is ignored by the current implementation of the DeleteDataKey method. This parameter is required for compatibility with Site Server 3.0 Commerce Edition, but is not used.

vtKey

[in] A VARIANT that contains the key value for the row to delete. This key corresponds to the column designated as the table key in the initial call to the InitStorage method. Thus, if the call to the InitStorage method specifies column "some_column" as the table key, then the DeleteDataKey method searches "some_column" for the value stored in the vtKey parameter, and deletes the corresponding row of data.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The DeleteDataKey method differs from the DeleteData method in that the DeleteDataKey requires only the value stored in the key column of the underlying table. This is the column specified as the key to the underlying table through a previous call to the InitStorage method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

DBStorage Object

IMSCSDBStorage_3_0::InitStorage

IMSCSDBStorage_3_0::DeleteData

IMSCSDBStorage_3_0::InsertData


IMSCSDBStorage_3_0::GetData

Use this method to retrieve a row of data from the database, based on the specified key value. If the data is found, this method creates and returns an OrderForm or Dictionary object containing the requested data.

Definition

HRESULT IMSCSDBStorage_3_0::GetData(
VARIANT vtReserved,
VARIANT vtKey,
VARIANT* pvtRet
);

Parameters

vtReserved

[in] A VARIANT reserved for future use. The GetData method ignores any value stored in this parameter.

vtKey

[in] A VARIANT that contains the key value on which to base the search. The GetData method searches for this value in the table column specified as the table key in the initial call to the InitStorage method.

pvtRet

[out, retval] A pointer to a VARIANT used to return a Dictionary or OrderForm object used to return the retrieved row.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pvtRet parameter points to valid data only if the method completes successfully.

For performance reasons, the GetData method is preferred over the LookupData method when the column being searched is the key.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

DBStorage Object

IMSCSDBStorage_3_0::InitStorage

IMSCSDBStorage_3_0::LookupData


IMSCSDBStorage_3_0::InitStorage

Use this method to initialize the DBStorage object. You must call this method immediately after object creation and before calling any other object methods. Attempting to call any other method prior to calling the InitStorage method results in an error.

Definition

HRESULT IMSCSDBStorage_3_0::InitStorage(
VARIANT vtDataSourceOrDSN,
BSTR Table,
BSTR bstrKey,
VARIANT vtProgID,
VARIANT vtMarshal,
VARIANT vtChanged
);

Parameters

vtDataSourceOrDSN

[in] A VARIANT which references a valid IDispatch pointer on a DataSource object, or which references a data source name (DSN).

Table

[in] A BSTR that contains the name of the table within the data source in which to maintain the data.

bstrKey

[in] A BSTR that contains the column name that the DBStorage object uses as a key into the database table. This column should be marked to contain unique values.

vtProgID

[in] A VARIANT that contains the ProgID of the object in which data passed to or retrieved by DBStorage methods will be stored. This parameter can be Commerce.Dictionary for storing Dictionary objects or Commerce.OrderForm for storing OrderForm objects. Methods (such as GetData) that return data from the database create an instance of the specified class with the requested data stored within it.

vtMarshal

[in] A VARIANT that contains the text string that, if specified, indicates the name of a column in the database into which the CommitData or InsertData method will store all the data from the specified data object, serialized into an encoded binary format. (Objects in the stored item that have corresponding column names in the database are also stored in those columns in the database.) If this argument is specified, the database must contain a column by that name, or an error will result. If this argument is not specified, then no data from the object is serialized and saved in the database in binary format, and items in the object that do not have corresponding columns in the database are discarded. When using a Microsoft SQL Server database, the maximum size of the data in this column is the same as the maximum size for the SQL Server text/image data type (2,147,483,647 bytes).

vtChanged

[in] A VARIANT that contains the name of a key or attribute in the database into which to write the date when the data is changed. (If you do not specify a column name that exists in the database, the change date will be included in the marshaled data.)

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

DBStorage Object


IMSCSDBStorage_3_0::InsertData

Use this method to insert the contents of the specified Dictionary object into a database row.

Definition

HRESULT IMSCSDBStorage_3_0::InsertData(
VARIANT vtReserved,
IDispatch* pdispData
);

Parameters

vtReserved

[in] A VARIANT reserved for future use. This parameter is ignored by the InsertData method.

pdispData

[in] An IDispatch pointer on the Dictionary object or OrderForm object that contains the data to insert.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

DBStorage Object

IMSCSDBStorage_3_0::InitStorage

IMSCSDBStorage_3_0::CommitData


IMSCSDBStorage_3_0::LookupData

Use this method to retrieve a single row from the data source based upon column names and values that you specify. If the data is found, this method creates and returns an OrderForm or Dictionary object (depending on the vtProgID parameter passed to the InitStorage method) containing the requested data.

Definition

HRESULT IMSCSDBStorage_3_0::LookupData(
VARIANT vtReserved,
VARIANT* pvtKeys,
VARIANT* pvtValues,
VARIANT* pvtRet
);

Parameters

vtReserved

[in] A VARIANT reserved for future use. The LookupData method ignores any value stored in this parameter.

pvtKeys

[in] A pointer to a VARIANT that identifies the columns in which to search for the data. This VARIANT can be either a SimpleList object or a SAFEARRAY.

pvtValues

[in] A pointer to a VARIANT that identifies the values for which to search. This parameter can be either a SimpleList object or a SAFEARRAY.

pvtRet

[out, retval] A pointer to a VARIANT used to return the result of the lookup; this VARIANT references an IDispatch interface pointer on a Dictionary object that contains the row data. If the method call is unsuccessful, this parameter evaluates to NULL.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pvtRet parameter points to valid data only if the method returns successfully.

The pvtKeys and pvtValues parameters are arrays that you pass to the LookupData method share in an index-to-index relationship. This means that they must contain an identical number of members and that the value stored in the pvtValues (N) parameter will be searched for in the column specified by the pvtKeys (N) parameter.

If the arrays contain more than one element, the LookupData method searches for a row in which all of the column/value pairs match.

Because the LookupData method returns only a single row of data, specifying column and value information that would result in the retrieval of more than one row results in an error.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

DBStorage Object

IMSCSDBStorage_3_0::InitStorage

IMSCSDBStorage_3_0::GetData

IMSCSDBStorage_3_0::LookupMultipleData


IMSCSDBStorage_3_0::LookupMultipleData

Use this method to retrieve multiple results from the database table. If the data is found, this method creates a SimpleList object that contains OrderForm or Dictionary objects, depending on the vtProgID parameter passed to the InitStorage method.

Definition

HRESULT IMSCSDBStorage_3_0::LookupMultipleData(
VARIANT vtReserved,
VARIANT* pvtKeys,
VARIANT* pvtValues,
VARIANT* pvtRet
);

Parameters

vtReserved

[in] A VARIANT reserved for future use. The LookupData method ignores any value stored in this parameter.

pvtKeys

[in]A pointer to the VARIANT that identifies the columns in which to search for the data. This VARIANT can be either a SimpleList object or a SAFEARRAY.

pvtValues

[in] A pointer to the VARIANT that identifies the values for which to search. This parameter can be either a SimpleList object or a SAFEARRAY.

pvtRet

[out, retval] A pointer to a VARIANT used to return the result of the lookup. This VARIANT references an IDispatch interface on a SimpleList object that consists of one or more Dictionary objects, one for each row of data returned. If the method fails, this parameter is set to NULL.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pvtRet parameter points to valid data only if the method returns successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

DBStorage Object

IMSCSDBStorage_3_0::InitStorage

IMSCSDBStorage_3_0::GetData

IMSCSDBStorage_3_0::LookupData


IMSCSDBStorage_3_0::get_Mapping, put_Mapping

The Mapping property maps a database column to an entry in the OrderForm or Dictionary object that the DBStorage object uses to insert and retrieve data.

Definition

Get method:

HRESULT IMSCSDBStorage_3_0::get_Mapping(
IDispatch** Mapping
);

Put method:

HRESULT IMSCSDBStorage_3_0::put_Mapping(
IDispatch* Mapping
);

Parameters

Mapping

[in] When putting the property, an IDispatch interface that contains the mapping Dictionary that is set for this DBStorage object instance.
[out, retval] When getting the property, an IDispatch interface used to return the mapping Dictionary for this DBStorage object instance.

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

A mapping Dictionary object makes it possible to map the column names in a database table to one or more names that you choose, usually for display to the site user. Suppose, for example, that your database table contains a column named "shopper_name", but that you want to display the contents of this column as the more human-readable "Shopper Name". Consequently, you initialize a "shopper_name" key in a Dictionary object to "Shopper Name", and pass this Dictionary object to the put_Mapping method. When you call a DBStorage object data retrieval method, such as GetData, to read a row of data into a Dictionary object, the Dictionary key for the "shopper_name" column reads "Shopper Name". This new mapping means that you do not have to translate the column name to a more human-readable name before displaying its values to the site user. You can simply display the keys and values as they appear in the Dictionary object returned by the GetData method.

The Mapping parameter contains valid data only if the property is accessed successfully.

See Also

DBStorage Object

IMSCSDBStorage_3_0::InitStorage


IMSCSDBStorage_3_0::ProcessData

Use this method to unpack the data stored in the MarshalColumn database column for a given row, and returns the resulting row in a Dictionary object.

Definition

HRESULT IMSCSDBStorage_3_0::ProcessData(
IDispatch* pdispData,
IDispatch** ppdispRet
);

Parameters

pdispData

[in] An IDispatch pointer on a Dictionary object that contains the marshaled data.

ppdispRet

[out, retval] The address of an IDispatch pointer on a Dictionary object used to return the unmarshaled data.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The ppdispRet parameter contains valid data only if the method completes successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

DBStorage Object

IMSCSDBStorage_3_0::InitStorage


Dictionary Object

Use this object to support the creation, storage, and retrieval of name/value pairs in memory. Every value in a Dictionary object is a Variant, which means you can create a Dictionary object that consists of almost any kind of value (including other Dictionary objects), and that you can store any combination of Variant types in the same Dictionary object.

ProgID: | Commerce.Dictionary (Externally creatable)
COM Class Name: | CDictionary
COM Interface Name: | IDictionary
Interface ID Constant: | IID_IDictionary
Header File: | commerce.h, mspu_guids.h
Type Library Name: | Microsoft Commerce 2000 Core Components Type Library
DLL Name: | MscsCore.dll
Threading Model: | Both

In C++, use the IDictionary interface to access the properties and methods of the Dictionary object.

The properties of the Dictionary object are shown in the following table.

Property | Type | Description
Count | long | Returns the number of elements in the Dictionary object. This property is read-only.
Prefix | BSTR | Stores the string that acts as a filter when the contents of the Dictionary object are saved (usually to a database). When the name of a name/value pair begins with the specified prefix, that name/value pair is not saved. This property is read/write.
Value | VARIANT | Stores the value of a given Dictionary key. This property is read/write.

Remarks

Because a Dictionary object is designed to be a general-purpose collection, you can use it for almost anything that its internal structure supports.

When you need to create a Dictionary object explicitly (that is, when the object is not created for you by some other Commerce Server 2000 object), use the CreateObject method of the Active Server Pages (ASP) Server object, as follows:

Set dictUser = Server.CreateObject("Commerce.Dictionary")

After creating the object, you can add elements to it, as follows:

dictUser.first_name = "Steve"

In this example, first_name is a Dictionary key, and Steve becomes the assigned value of this key. Each statement actually accomplishes three functions: declaring the Dictionary key, adding that key to the Dictionary object, and setting the key to a value.

You can extract values from a Dictionary object in several ways. You can simply place the object.key identifier on the right side of the assignment statement. Such an assignment returns the value of the referenced key:

my_first_name = dictUser.first_name

Or you can use the Value method to get the value of a given key:

my_first_name = dictUser.Value("first_name")

You can also use the For Each statement in Microsoft Visual Basic Scripting Edition (VBScript) to enumerate through the keys or the values of a Dictionary object as follows (this example assumes that every value in the dictionary contains text):

' Get the key names
For Each element In dictUser
    Response.Write element
Next

' Get the values
For Each element In dictUser
    Response.Write dictUser.Value(element)
Next

The data in a Dictionary object can be saved in a database table by using the DBStorage object.

Commerce Server 2000 sites use implementations of the Dictionary object to store sets of data that are required by various other objects and pipeline components.

Unlike previous versions of the dictionary, the dictionary in Commerce Server 2000 is implemented as a hash of name value pairs. This enables the dictionary to perform fast lookups even when a large number of key/value pairs are stored. It also has the side effect that enumerations of dictionary keys may not be returned in the same order they are stored.

The dictionary object aggregates the Free Threaded Marshaller (FTM) for performance reasons (so that calls to the dictionary will never go through a proxy, no matter what COM apartment it is called from). Because of this, you may not store a reference to an apartment-threaded object in a dictionary. Doing so may result in errors such as RPC_E_WRONGTHREAD when the object pointer is retrieved and used.

The Dictionary object supports the ICloneable and IPersistXML interfaces. Use the ICloneable interface to deep copy all name/value pairs into a new dictionary. Use the IPersistXML interface to convert the Dictionary entries into an XML string and back again.

See Also

General Purpose Objects

IPersistXML Interface

SimpleList Object


IDictionary::get_Count

The Count property is a read-only Long that contains the number of elements in the Dictionary object instance.

Definition

HRESULT IDictionary::get_Count(
long* Count
);

Parameters

Count

[out, retval] A pointer to a long in which the get_Count method stores the number of elements in the Dictionary object.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This property returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The Count parameter points to valid data only if the property is accessed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Dictionary Object


IDictionary::get_Prefix, put_Prefix

The Prefix property is a read/write String that acts as a filter when the contents of the Dictionary object are saved (usually to a database). When the name of a name/value pair begins with the specified prefix, that name/value pair is not saved. By default, the prefix is "_", so that any keywords beginning with an underscore character are excluded.

Definition

Get method:

HRESULT IDictionary::get_Prefix(
BSTR* Prefix
);

Put method:

HRESULT IDictionary::put_Prefix(
BSTR Prefix
);

Parameters

Prefix

[in] When putting the property, a BSTR that contains the prefix.
[out, retval] When getting the property, a pointer to the BSTR that contains the prefix.

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The Prefix parameter contains valid data only if the property is accessed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

By default, the prefix is "_", so that any keywords beginning with an underscore character are excluded.

The pipeline component that saves receipts usually sets the prefix to "_cc_", so that all credit-card information is not saved in the database. The actual string used by the pipeline component is configurable.

See Also

Dictionary Object


IDictionary::get_Value, put_Value

The Value property allows you to get or set a name/value pair in the Dictionary.

Definition

Get method:

HRESULT IDictionary::get_Value(
BSTR bstrName,
VARIANT* Value
);

Put method:

HRESULT IDictionary::put_Value(
BSTR bstrName,
VARIANT Value
);

Putref method:

HRESULT IDictionary::putref_Value(
BSTR bstrName,
VARIANT Value
);

Parameters

bstrName

[in] A BSTR that contains the name of the Dictionary key for which to retrieve a value or put a value.

Value

[in] When putting the property, a VARIANT that contains the value to which the element specified by the key bstrName should be initialized.
[out, retval] When getting the property, a pointer to a VARIANT used to return the value of the key specified by the bstrName parameter.

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details. If successful, this method returns S_OK. Otherwise, it returns an HRESULT indicating failure, and the Value out-value parameter is set to NULL.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

When reading the Value property using the get_Value method, if the key being accessed in the dictionary does not exist, a VARIANT of type VT_NULL is returned. Therefore, to logically delete a key from the dictionary, you can set the value for the key to VT_NULL and then to a client of the dictionary. It is indistinguishable from a key/value pair that does not exist. The Value parameter contains valid data only if the property is accessed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

When putting a value, use the putref method if you are setting an object reference; use the put method if you are setting a scalar value.

See Also

Dictionary Object


DictionaryXMLTransforms Object

Use this object to transform data from a Dictionary object into Extensible Markup Language (XML) and vice-versa, using a specified XML Data Reduced (XDR) schema.

ProgID: | Commerce.DictionaryXMLTransforms (Externally creatable)
COM Class Name: | DictionaryXMLTransforms
COM Interface Name: | _DictionaryXMLTransforms
Interface ID Constant: | None
Header File: | None
Type Library Name: | Microsoft Commerce 2000 DictionaryXMLTransform Type Library
DLL Name: | DictionaryXMLTransforms.dll
Threading Model: | Apartment

Important

  • The DictionaryXMLTransforms object is only capable of processing dictionary keys with names that would be allowable as XML Node names. Allowable characters include A-Z and the underscore "_" character. Disallowed characters include"*", "\", etc., and foreign-language characters.

  • Every dictionary key value must be URL-encoded.

In C++, use the _DictionaryXMLTransforms interface to access the properties and methods of the DictionaryXMLTransforms object.

The methods of the DictionaryXMLTransforms object are shown in the following table.

Method | Description
GenerateSampleXMLInstanceFromDictionary | Produces an XML instance based on the specified Dictionary object.
GenerateXMLForDictionaryUsingSchema | Extracts an XML instance from the specified Dictionary object that conforms to the specified schema.
GetXMLFromFile | Generates an XML Document Object Model (DOM) document from the specified file.
ReconstructDictionaryFromXML | Transforms the specified XML instance (which must comply with the specified schema) into a Dictionary object.

Remarks

The example code that calls this method can be found in the payment.asp and _recvpo.asp files. An example of the use of a XML schema can be found in the POSchema.xml file in the Solution Sites.

See Also

General Purpose Objects

Dictionary Object


_DictionaryXMLTransforms::GenerateSampleXMLInstanceFromDictionary

Use this method to generate an XML Data Reduced (XDR) schema. This method produces an XML instance based on the specified Dictionary object. You can then import this XML instance into a tool (such as the BizTalk Editor) that can construct a schema based on a given instance.

Definition

HRESULT _DictionaryXMLTransforms::GenerateSampleXMLInstanceFromDictionary(
IDictionary* Dictionary,
BSTR ElementName,
VARIANT_BOOL bIgnoreUnderScore,
IXMLDOMNode** RetValue
);

Parameters

Dictionary

[in] A pointer to the IDictionary interface of a Dictionary object that contains the data to convert into XML.

ElementName

[in] A BSTR that contains the element name.

bIgnoreUnderScore

[in] A VARIANT_BOOL that specifies whether to ignore dictionary keys with leading underscores in the dictionary. This value should generally be set to True.

RetValue

[out, retval] The address of the pointer to the IXMLDOMNode interface of the newly created XMLDOMNode object containing the XML instance.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The RetValue parameter contains valid data only if the method completes successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

DictionaryXMLTransforms Object


_DictionaryXMLTransforms::GenerateXMLForDictionaryUsingSchema

Use this method to extract an XML instance from the specified Dictionary object that conforms to the specified schema.

Definition

HRESULT _DictionaryXMLTransforms::GenerateXMLForDictionaryUsingSchema(
IDictionary* Dictionary,
IXMLDOMDocument* xmlSchema,
IXMLDOMNode** RetValue
);

Parameters

Dictionary

[in] A pointer to the IDictionary interface of the Dictionary object to be converted.

xmlSchema

[in] A reference to the IXMLDOMDocument interface of the XMLDOMDocument object that contains the XML schema.

RetValue

[out, retval] A pointer to hold the reference to the returned IXMLDOMNode interface of a XMLDOMNode object, which will contain the XML instance.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The RetValue parameter contains valid data only if the method completes successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

DictionaryXMLTransforms Object


_DictionaryXMLTransforms::GetXMLFromFile

Use this method to generate a XML Document Object Model (DOM) document from the specified file.

Definition

HRESULT _DictionaryXMLTransforms::GetXMLFromFile(
BSTR sFileName,
IXMLDOMDocument** RetValue
);

Parameters

sFileName

[in] A BSTR that contains the name of the file to convert.

RetValue

[out, retval] A pointer to hold the reference to the returned IXMLDOMDocument interface of the XMLDOMDocument object, which will contain the converted file data.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The RetValue parameter contains valid data only if the method completes successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

DictionaryXMLTransforms Object


_DictionaryXMLTransforms::ReconstructDictionaryFromXML

Use this method to transform the specified XML instance (which must comply with the specified schema) into a Dictionary object. This method performs the inverse operation of the GenerateXMLForDictionaryUsingSchema method.

Definition

HRESULT _DictionaryXMLTransforms::ReconstructDictionaryFromXML(
BSTR szDictionaryXML,
IXMLDOMDocument* xmlSchema,
IDictionary** RetValue
);

Parameters

szDictionaryXML

[in] A BSTR that contains the XML instance.

xmlSchema

[in] A reference to the IXMLDOMDocument interface of the XMLDOMDocument object that contains the XML schema used in the conversion.

RetValue

[out, retval] The address of a pointer to receive an IDictionary interface of the reconstructed Dictionary object.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The RetValue parameter contains valid data only if the method completes successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

DictionaryXMLTransforms Object


EuroDisplay Object

Use this object to convert and format currency amounts where multiple currencies must be displayed.

ProgID: | Commerce.EuroDisplay (Externally creatable)
COM Class Name: | EuroDisplay
COM Interface Name: | IEuroDisplay
Interface ID Constant: | None
Header File: | None
Type Library Name: | Microsoft Commerce 2000 Euro Display Component Type Library
DLL Name: | EuroDisp.dll
Threading Model: | Both

In C++, use the IEuroDisplay interface to access the properties and methods of the EuroDisplay object.

Because this object is primarily intended for use within ASP script, access from C++ will not be common.

The methods of the EuroDisplay object are shown in the following table.

Method | Description
ConvertAltStringToCurr | Converts a string representation of a monetary value in the currency specified by the alternate locale identifier to a currency VARIANT.
ConvertBaseStringToCurr | Converts a string representation of a monetary value in the currency specified by the base locale identifier to a currency VARIANT.
ConvertMoney | Converts the specified currency VARIANT (representing a monetary value in the base currency) to a currency VARIANT representing a monetary value in the alternate currency, using the initialized conversion rate.
FormatAltMoney | Creates a string representation of a currency VARIANT, based on the alternate locale identifier and the alternate currency symbol string.
FormatBaseMoney | Creates a string representation of a currency VARIANT, based on the base locale identifier and the base currency symbol string.
Initialize | Initializes the object with the specified alternate currency symbol, base currency symbol, alternate locale identifier, base locale identifier, and conversion rate.

See Also

Display Objects


IEuroDisplay::ConvertAltStringToCurr

Use this method to convert a string representation of a monetary value in the currency specified by the alternate locale identifier to a currency Variant.

Definition

HRESULT IEuroDisplay::ConvertAltStringToCurr(
VARIANT vtMoneyString,
VARIANT* pvarNumber
);

Parameters

vtMoneyString

[in] A VARIANT that contains the currency string to convert.

pvarNumber

[out, retval] A pointer to a currency VARIANT used to return the converted currency information.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pvarNumber parameter points to valid data only if the method returns successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

EuroDisplay Object

IEuroDisplay::ConvertBaseStringToCurr

IEuroDisplay::FormatAltMoney


IEuroDisplay::ConvertBaseStringToCurr

Use this method to convert a string representation of a monetary value in the currency specified by the base locale identifier to a currency Variant.

Definition

HRESULT IEuroDisplay::ConvertBaseStringToCurr(
VARIANT vtMoneyString,
VARIANT* pvarNumber
);

Parameters

vtMoneyString

[in] A VARIANT that contains the currency string to convert.

pvarNumber

[out, retval] A pointer to a currency VARIANT used to return the converted currency information.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pvarNumber parameter points to valid data only if the method returns successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

EuroDisplay Object

IEuroDisplay::ConvertAltStringToCurr

IEuroDisplay::FormatBaseMoney


IEuroDisplay::ConvertMoney

Use this method to convert the specified currency Variant (representing a monetary value in the base currency) to a currency Variant representing a monetary value in the alternate currency, using the initialized conversion rate.

Definition

HRESULT IEuroDisplay::ConvertMoney(
VARIANT vtCurrVal,
VARIANT* pvarConvVal
);

Parameters

vtCurrVal

[in] A currency VARIANT representing a monetary value in the base currency.

pvarConvVal

[out, retval] A pointer to a currency VARIANT representing a monetary value in the alternate currency.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pvarConvVal parameter points to valid data only if the method returns successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

EuroDisplay Object


IEuroDisplay::FormatAltMoney

Use this method to create a string representation of a currency Variant, based on the alternate locale identifier and the alternate currency symbol string.

Definition

HRESULT IEuroDisplay::FormatAltMoney(
VARIANT vtConvMoney,
BSTR* szAltMoney
);

Parameters

vtConvMoney

[in] A currency VARIANT that contains the monetary value to convert.

szAltMoney

[out, retval] A pointer to a BSTR used to return the string representation of the specified currency VARIANT.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The szAltMoney parameter points to valid data only if the method returns successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

EuroDisplay Object

IEuroDisplay::ConvertAltStringToCurr

IEuroDisplay::FormatBaseMoney


IEuroDisplay::FormatBaseMoney

Use this method to create a string representation of a currency Variant, based on the base locale identifier and the base currency symbol string.

Definition

HRESULT IEuroDisplay::FormatBaseMoney(
VARIANT vtConvMoney,
BSTR* szBaseMoney
);

Parameters

vtConvMoney

[in] A currency VARIANT that contains the monetary value to convert.

szBaseMoney

[out, retval] A BSTR used to return the string representation of the specified currency VARIANT.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The szBaseMoney parameter contains valid data only if the method returns successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

EuroDisplay Object

IEuroDisplay::ConvertBaseStringToCurr

IEuroDisplay::FormatAltMoney


IEuroDisplay::Initialize

Use this method to initialize the object with the specified alternate currency symbol, base currency symbol, alternate locale identifier, base locale identifier, and conversion rate.

Definition

HRESULT IEuroDisplay::Initialize(
BSTR szBaseCurr,
long lBaseLCID,
BSTR szAltCurr,
long lAltLCID,
double flEuroConvRate
);

Parameters

szBaseCurr

[in] A BSTR that contains the base currency symbol string.

lBaseLCID

[in] A long that contains the base locale identifier.

szAltCurr

[in] A BSTR that contains the alternate currency symbol string.

lAltLCID

[in] A long that contains the alternate locale identifier.

flEuroConvRate

[in] A double (8-byte floating point number) that contains the rate at which to convert the base currency into the alternate currency. For example, if the base currency is Swiss Francs which are exchanged at a rate of 1 SF = 0.63 Euros, and the alternate currency is Euro, then this parameter will have a value of 0.63.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

EuroDisplay Object


ExpressionEval Object

Use this object to evaluate one or more expressions against a specified context. In addition, use this object to parse and evaluate user-defined expressions written as Extensible Markup Language (XML) fragments.

ProgID: | Commerce.ExpressionEvaluator (Externally creatable)
COM Class Name: | ExpressionEval
COM Interface Name: | IExpressionEval
Interface ID Constant: | IID_IExpressionEval
Header File: | ExprArchDLL.h, exprarch.h, mspu_guids.h
Type Library Name: | Microsoft Commerce 2000 Expression System Type Library
DLL Name: | exprarch.dll
Threading Model: | Both

In C++, the properties and methods of the ExpressionEval object are accessed through the IExpressionEval interface.

The properties of the ExpressionEval object are shown in the following table.

Property | Type | Description
ExprCount | long | Retrieves the number of expressions loaded into the expression cache. This property is read-only.

The methods of the ExpressionEval object are shown in the following table.

Method | Description
Connect | Establishes communication between the ExpressionEval object and an expression store.
CreateEvalContext | Creates a new ExprEvalContext object in the context cache.
Eval | Evaluates an expression.
EvalInContext | Evaluates an expression in a context previously loaded into the context cache.
EvalXML | Evaluates the specified XML text as an expression.
FlushAll | Removes all expressions from the expression cache.
FlushExpr | Removes the specified expression from the expression cache.
LoadAll | Reads all expressions from the expression store and loads them into the expression cache.
LoadExpr | Reads the specified expression from the expression store and loads it into the expression cache.
ParseXML | Parses the specified XML text to determine if it represents a valid expression.

Remarks

Expressions are stored in a database referred to as the Expression Store and accessed through an ExpressionStore object. When it is created, the ExpressionEval object initializes an expression cache and a context cache. Expressions must be compiled and loaded into the expression cache before being evaluated. To improve evaluation performance, use the LoadExpr or LoadAll method to preload expressions into the expression cache.

An expression is evaluated against data contained in a set of profiles. The profiles may be ProfileObject objects, Dictionary objects, or other objects that support property access through the IDispatch interface. The set of profiles is referred to as an evaluation context. If an evaluation context will be used across multiple expressions, create a stored context in the context cache using the CreateEvalContext method to increase efficiency.

The Connect method must be called before loading or evaluating expressions.

See Also

Expression Objects

Expression Recordset

Expression XML Structures

ExpressionStore Object

ProfileObject Object


IExpressionEval::Connect

Use this method to establish communication with an expression store.

Definition

HRESULT IExpressionEval::Connect(
VARIANT vConnectInfo
);

Parameters

vConnectInfo

[in] A VARIANT that describes the expression store connection data. This may be a BSTR containing the connection information or a pointer to an existing ExpressionStore object.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_EXPR_BADCONNECTION | 0x8110001F | Invalid connection
E_EXPR_BADEXPRSTORE | 0x8110001E | Specified database does not contain a valid expression store
E_EXPR_NOCONNECTIONSTRING | 0x8110000D | No connection string specified
E_EXPR_STOREPERMISSIONS | 0x8110000F | Insufficient access permissions on the expression store database

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

If a connection string is passed as the input parameter, the ExpressionEval object creates an ExpressionStore object that uses the connection string to access the expression store. Upon destruction, the ExpressionEval object destroys the ExpressionStore object.

The connection string for the expression store may be obtained through the SiteConfigReadOnly object or through the Commerce Server Manager console from the s_BizDataStoreConnectionString property under the key "Commerce Server Manager\Global Resources\Profiles".

The Connect method must be used before loading or evaluating expressions.

The ParseXML method and the flush methods may be used without connecting to an expression store.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ExpressionEval Object

ExpressionStore Object

IExpressionStore::Connect

SiteConfigReadOnly Object


IExpressionEval::CreateEvalContext

Use this method to create a new ExprEvalContext object and place it into the context cache. This allows evaluation of multiple expressions against the same set of profile objects in the most efficient manner possible.

Definition

HRESULT IExpressionEval::CreateEvalContext(
IDictionary* pDictObjs,
IExprEvalContext** ppContext
);

Parameters

pDictObjs

[in] A pointer to the IDictionary interface of a Dictionary object that contains the set of profiles to be cached.

ppContext

[out, retval] The address of the pointer to the IExprEvalContext interface of the newly created ExprEvalContext object.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The CreateEvalContext method creates an ExprEvalContext object that uniquely identifies a new evaluation context and stores the object in the context cache. Use the EvalInContext method to evaluate multiple expressions within the context defined by the ExprEvalContext object. This process is more efficient than using the Eval method which generates and destroys a new context for each expression evaluated.

A context is a set of profiles containing data to evaluate expressions against. Profiles may be ProfileObject objects, Dictionary objects, or other objects that support property access through the IDispatch interface. Initially only references to the profile objects are held in the context cache. During evaluation, when property values are read from the profiles, the property values may themselves be held in the cache for faster access during subsequent evaluations.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

The ppContext parameter contains valid data only if the method completes successfully.

Caution

  • The state of the profile objects should not be externally changed during the lifetime of the ExprEvalContext object; doing so leads to non-deterministic evaluation results.

See Also

ExpressionEval Object

IExpressionEval::EvalInContext


IExpressionEval::Eval

Use this method to evaluate an expression.

Definition

HRESULT IExpressionEval::Eval(
long nExprID,
IDictionary* pDictObjs,
VARIANT* pvResult
);

Parameters

nExprID

[in] A long that contains the unique identifier for the expression in the expression store.

pDictObjs

[in] A pointer to the IDictionary interface of a Dictionary object that contains a set of profiles.

pvResult

[out, retval] A pointer to a VARIANT indicating the result of evaluating the expression in the given context.

Return Values

This method returns an HRESULT indicating whether the method completed successfully. See the Error Values section for more details. The result of evaluating the expression is contained in the pvResult parameter. The result may be TRUE, FALSE, or NULL. NULL indicates the expression could not be evaluated.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors, and the standard COM errors with special meanings, that this method can return.

Constant | Value | Description
E_EXPR_BADCONNECTION | 0x8110001F | Invalid connection
E_EXPR_BADEXPRID | 0x8110000A | Invalid expression ID specified
E_EXPR_NOCONNECTIONSTRING | 0x8110000D | No connection string specified
E_EXPR_NOTFOUND | 0x81100012 | Could not find the specified expression ID, nExprID, in the expression store

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

Expressions must be pre-compiled and loaded into the expression cache before being evaluated. The Eval method first checks the expression cache for the expression, and if not found, loads the expression from the expression store. Use the LoadExpr or LoadAll method to preload an expression into the expression cache and improve evaluation performance.

An expression is evaluated against data contained in a set of profiles. This set of profiles is referred to as an evaluation context. A new evaluation context is generated by the Eval method using the Dictionary object. The Eval method discards the new context after completing the evaluation. This process is not efficient if many expressions must be evaluated against the same context.

If an evaluation context will be used across multiple expressions, create a context in the context cache using the CreateEvalContext method. Use the EvalInContext method to evaluate expressions in this new common context.

The Connect method must be called before using the Eval method.

The pvResult parameter contains valid data only if the method completes successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ExpressionEval Object

IExpressionEval::Connect

IExpressionEval::CreateEvalContext

IExpressionEval::EvalInContext

IExpressionEval::LoadExpr


IExpressionEval::EvalInContext

Use this method to evaluate an expression against a pre-established context stored in the context cache.

Definition

HRESULT IExpressionEval::EvalInContext(
long nExprID,
IExprEvalContext* pContext,
VARIANT* pvResult
);

Parameters

nExprID

[in] A long that contains the unique identification of the expression in the expression store.

pContext

[in] A pointer to an IExprEvalContext interface of an ExprEvalContext object that identifies the specific context for this evaluation.

pvResult

[out, retval] A pointer to a VARIANT indicating the result of the expression evaluated in the specified context.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details. The result of evaluating the expression is contained in the pvResult parameter. This result may be TRUE, FALSE, or NULL. NULL indicates the expression could not be evaluated.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors, and the standard COM errors with special meanings, that this method can return.

Constant | Value | Description
E_EXPR_BADCONNECTION | 0x8110001F | Invalid connection
E_EXPR_BADEXPRID | 0x8110000A | Invalid expression ID specified
E_EXPR_NOCONNECTIONSTRING | 0x8110000D | No connection string specified
E_EXPR_MISSINGPROP | 0x8110001D | Invalid ExprEvalContext object
E_EXPR_NOTFOUND | 0x81100012 | Could not find the specified expression ID, nExprID, in the expression store

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The Eval method creates and discards an evaluation context for every evaluation. Evaluating against a stored context optimizes performance when multiple expressions need to be evaluated in the same context. Create the context for evaluation using the CreateEvalContext method.

Expression results are also stored in the context cache. If the result of a particular expression is requested multiple times from the same ExprEvalContext object using the EvalInContext method, the result is retrieved from the cache rather than by re-evaluating the expression, further increasing efficiency.

Caution

  • The state of the profile objects that comprise the context should not be externally changed during the lifetime of the ExprEvalContext object; doing so leads to non-deterministic evaluation results.

The Connect method must be called before using the EvalInContext method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

The pvResult parameter contains valid data only if the method completes successfully.

See Also

ExpressionEval Object

IExpressionEval::Connect

IExpressionEval::CreateEvalContext

IExpressionEval::Eval

IExpressionEval::LoadExpr


IExpressionEval::EvalXML

Use this method to evaluate an expression represented as an Extensible Markup Language (XML) fragment.

Definition

HRESULT IExpressionEval::EvalXML(
BSTR bstrXMLExpr,
IDictionary* pDictObjs,
VARIANT* pvResult
);

Parameters

bstrXMLExpr

[in] A BSTR that contains the XML fragment to be evaluated.

pDictObjs

[in] A pointer to the IDictionary interface of a Dictionary object that contains a set of profiles.

pvResult

[out, retval] A pointer to a VARIANT indicating the results of evaluating the expression in the specified context.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details. The result of evaluating the expression is contained in the pvResult parameter. The result may be TRUE, FALSE, or NULL. NULL indicates the expression could not be evaluated.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_EXPR_BADARGTYPE | 0x81100018 | Argument datatype information missing from expression, or unrecognized argument data type encountered in expression
E_EXPR_BADARGVALUE | 0x81100022 | Invalid expression argument value, or impossible conversion
E_EXPR_BADCLAUSE | 0x81100016 | Invalid clause encountered
E_EXPR_BADCONNECTION | 0x8110001F | Invalid connection
E_EXPR_BADOPER | 0x81100017 | Operator missing, unrecognized operator encountered, or type mismatch
E_EXPR_BADTERM | 0x81100015 | Term type missing, or unrecognized term type encountered
E_EXPR_BADXML | 0x81100014 | An unrecognized XML element was encountered
E_EXPR_NOCONNECTIONSTRING | 0x8110000D | No connection string specified
E_EXPR_XMLPARSE | 0x81100013 | XML DOM object parsing error

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The XML is parsed before being evaluated. For information on the XML format, see Expression XML Structures.

Expressions evaluated with the EvalXML method are not persistent; that is, they are not stored in the expression store or loaded into the expression cache. Use the Eval method to evaluate persistent expressions.

A new ExprEvalContext object is created and then discarded for each XML fragment that is evaluated.

The Connect method must be called before using the EvalXML method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

The pvResult parameter contains valid data only if the method completes successfully.

See Also

Expression Recordset

Expression XML Structures

ExpressionEval Object

IExpressionEval::Connect

IExpressionEval::Eval

IExpressionEval::ParseXML


IExpressionEval::get_ExprCount

The ExprCount property is a read-only integer that indicates the number of expressions that correctly pre-compiled and loaded into the expression cache. Expressions that contain syntactic errors will fail to pre-compile correctly.

Definition

HRESULT IExpressionEval::get_ExprCount(
long* pExprCount);

Parameters

pExprCount

[out, retval] A pointer to a long used to return the number of expressions loaded in the expression store.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the following Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

See Also

ExpressionEval Object

IExpressionEval::FlushAll

IExpressionEval::FlushExpr

IExpressionEval::LoadAll

IExpressionEval::LoadExpr


IExpressionEval::FlushAll

Use this method to remove all expressions from the expression cache.

Definition

HRESULT IExpressionEval::FlushAll(
);

Parameters

None.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The FlushAll method removes all expressions from the expression cache and resets the read-only ExprCount property to zero (0).

Use the FlushExpr method to remove a specific expression from the expression cache.

See Also

ExpressionEval Object

IExpressionEval::get_ExprCount

IExpressionEval::FlushExpr

IExpressionEval::LoadAll

IExpressionEval::LoadExpr


IExpressionEval::FlushExpr

Use this method to remove the specified expression from the expression cache.

Definition

HRESULT IExpressionEval::FlushExpr(
long nExprID
);

Parameters

nExprID

[in] A long that contains the identifier of the expression to be removed from the expression cache.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_EXPR_BADEXPRID | 0x8110000A | Invalid expression ID specified

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The FlushExpr method removes the specified expression from the expression cache and decrements the read-only ExprCount property by one (1).

Use the FlushAll method to remove all expressions from the expression cache.

See Also

ExpressionEval Object

IExpressionEval::get_ExprCount

IExpressionEval::FlushAll

IExpressionEval::LoadAll

IExpressionEval::LoadExpr


IExpressionEval::LoadAll

Use this method to pre-compile all expressions in the expression store. Each expression that pre-compiles correctly is loaded into the expression cache.

Definition

HRESULT IExpressionEval::LoadAll(
);

Parameters

None.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_EXPR_BADARGTYPE | 0x81100018 | Argument datatype infomation missing from expression, or unrecognized argument data type encountered in expression
E_EXPR_BADARGVALUE | 0x81100022 | Invalid expression argument value, or impossible conversion
E_EXPR_BADCLAUSE | 0x81100016 | Invalid clause encountered
E_EXPR_BADCONNECTION | 0x8110001F | Invalid connection
E_EXPR_BADOPER | 0x81100017 | Operator missing, unrecognized operator encountered, or type mismatch
E_EXPR_BADTERM | 0x81100015 | Term type missing, or unrecognized term type encountered
E_EXPR_BADXML | 0x81100014 | An unrecognized XML element was encountered
E_EXPR_NOCONNECTIONSTRING | 0x8110000D | No connection string specified
E_EXPR_XMLPARSE | 0x81100013 | XML DOM object parsing error

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

Any expressions in the expression cache at the time of the call are reloaded.

If there are many expressions in the expression store, the LoadAll method may be slow. Use the LoadExpr method to load only specific expressions into the expression cache.

For every expression loaded into the expression cache, the LoadAll method increments the read-only ExprCount property by one (1).

Use the FlushAll method to remove all expressions from the expression cache.

The Connect method must be called before using the LoadAll method.

See Also

ExpressionEval Object

IExpressionEval::Connect

IExpressionEval::get_ExprCount

IExpressionEval::FlushAll

IExpressionEval::FlushExpr

IExpressionEval::LoadExpr


IExpressionEval::LoadExpr

Use this method to pre-compile an expression, and if successful, load the expression into the expression cache.

Definition

HRESULT IExpressionEval::LoadExpr(
long nExprID
);

Parameters

nExprID

[in] A positive long that contains the identifier of the expression to load into the expression cache.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_EXPR_BADARGTYPE | 0x81100018 | Argument datatype info missing from expression, or unrecognized argument data type encountered in expression
E_EXPR_BADARGVALUE | 0x81100022 | Invalid expression argument value, or impossible conversion
E_EXPR_BADCLAUSE | 0x81100016 | Invalid clause encountered
E_EXPR_BADCONNECTION | 0x8110001F | Invalid connection
E_EXPR_BADEXPRID | 0x8110000A | Invalid expression ID specified
E_EXPR_BADOPER | 0x81100017 | Operator missing, unrecognized operator encountered, or type mismatch
E_EXPR_BADTERM | 0x81100015 | Term type missing, or unrecognized term type encountered
E_EXPR_BADXML | 0x81100014 | An unrecognized XML element was encountered
E_EXPR_NOCONNECTIONSTRING | 0x8110000D | No connection string specified
E_EXPR_NOTFOUND | 0x81100012 | Could not find the specified expression ID, nExprID, in the expression store
E_EXPR_XMLPARSE | 0x81100013 | XML DOM object parsing error

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

If the specified expression is already loaded in the expression cache at the time of the call, it will be reloaded.

The LoadExpr method increments the read-only ExprCount property by one when it loads an expression into the expression cache.

With the exception of XML fragments, only expressions that exist in the expression cache may be evaluated. The Eval method loads an expression from the expression store that is not preloaded into the expression cache.

Use the LoadAll method to load all expressions into the expression cache. Use the FlushExpr method to remove an expression from the expression cache.

The Connect method must be called before using the LoadExpr method.

See Also

ExpressionEval Object

IExpressionEval::Connect

IExpressionEval::get_ExprCount

IExpressionEval::FlushAll

IExpressionEval::FlushExpr

IExpressionEval::LoadAll


IExpressionEval::ParseXML

Use this method to check whether an Extensible Markup Language (XML) fragment is a syntactically correct expression.

Definition

HRESULT IExpressionEval::ParseXML(
BSTR bstrXMLExpr,
VARIANT_BOOL* pbValid
);

Parameters

bstrXMLExpr

[in] A BSTR that contains the XML text defining an expression.

pbValid

[out, retval] A pointer to a VARIANT_BOOL indicating the validity of the expression.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_EXPR_BADARGTYPE | 0x81100018 | Argument datatype information missing from expression, or unrecognized argument data type encountered in expression
E_EXPR_BADARGVALUE | 0x81100022 | Invalid expression argument value, or impossible conversion
E_EXPR_BADCLAUSE | 0x81100016 | Invalid clause encountered
E_EXPR_BADOPER | 0x81100017 | Operator missing, unrecognized operator encountered, or type mismatch
E_EXPR_BADTERM | 0x81100015 | Term type missing, or unrecognized term type encountered
E_EXPR_BADXML | 0x81100014 | An unrecognized XML element was encountered
E_EXPR_XMLPARSE | 0x81100013 | XML DOM object parsing error

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

Since this method only checks syntax, the expression may still be invalid even though the method succeeds.

The expression store is not used for XML fragments.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

The pbValid parameter contains valid data only if the method completes successfully.

See Also

Expression Recordset

Expression XML Structures

ExpressionEval Object

IExpressionEval::Eval

IExpressionEval::EvalXML


ExpressionStore Object

Use this object to manipulate expressions contained in an expression store. An expression store is a database of expressions along with information about the expressions. There is one expression store for each commerce site.

ProgID: | Commerce.ExpressionStore (Externally creatable)
COM Class Name: | ExpressionStore
COM Interface Name: | IExpressionStore
Interface ID Constant: | IID_IExpressionStore
Header File: | ExprArchDLL.h, exprarch.h, mspu_guids.h
Type Library Name: | Microsoft Commerce 2000 Expression System Type Library
DLL Name: | exprarch.dll
Threading Model: | Both

In C++, use the IExpressionStore interface to access the methods of the ExpressionStore object.

The methods of the ExpressionStore object are shown in the following table.

Method | Description
Connect | Validates and stores the connection string to the specified expression store.
DeleteExpression | Deletes an expression from the expression store.
Disconnect | Sets the connection string to an empty string.
Export | Exports expressions from the expression store to a file.
GetAllExprs | Retrieves all expressions from the expression store.
GetExpression | Retrieves an expression from the expression store.
GetExprID | Translates an expression name into its corresponding expression ID.
GetExprName | Translates an expression ID into its corresponding expression name.
Import | Imports a set of expressions to the expression store from a file.
NewExpression | Creates a new ADO Recordset object that contains an empty expression.
Query | Queries for a list of expressions based on one or more criteria.
RenameExpression | Renames an existing expression.
SaveExpression | Saves a new or changed expression to the expression store.

Remarks

The connection string to a valid expression store must be stored using the Connect method before calling any other method of the ExpressionStore object.

An ExpressionStore object is internally created when the Connect method of an ExpressionEval object is invoked.

See Also

Expression Objects

Expression Recordset

Expression XML Structures

ExpressionEval Object


IExpressionStore::Connect

Use this method to store the connection string to an expression store.

Definition

HRESULT IExpressionStore::Connect(
BSTR strConnStr
);

Parameters

strConnStr

[in] A BSTR that contains the database connection information for the expression store.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_EXPR_BADCONNECTION | 0x8110001F | Invalid connection
E_EXPR_BADEXPRSTORE | 0x8110001E | Specified database does not contain a valid expression store
E_EXPR_NOCONNECTIONSTRING | 0x8110000D | No connection string specified
E_EXPR_STOREPERMISSIONS | 0x8110000F | Insufficient access permissions on the expression store database

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The ExpressionStore object does not maintain a persistent ADO connection. This method stores the connection string after validating that the connection string points to an actual expression store. The Disconnect method sets the connection string to an empty string.

Each method of the ExpressionStore object creates a connection when needed, and when done with it, closes the connection. This relies on ADO connection pooling and provides higher availability.

The connection string for the expression store may be obtained through the SiteConfigReadOnly object or through the Commerce Server Manager console from the s_BizDataStoreConnectionString property under the key "Commerce Server Manager\Global Resources\Profiles".

The Connect method must be successfully executed before calling any other method of an externally created ExpressionStore object.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ExpressionStore Object

IExpressionStore::Disconnect

SiteConfigReadOnly Object


IExpressionStore::DeleteExpression

Use this method to delete an existing expression from the expression store.

Definition

HRESULT IExpressionStore::DeleteExpression(
long nExprID,
long flags
);

Parameters

nExprID

[in] A long that specifies the expression to be deleted.

flags

[in] A long that contains the optional control flags. This parameter is currently unused and should be set to zero (0).

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_EXPR_BADCONNECTION | 0x8110001F | Invalid connection
E_EXPR_BADEXPRID | 0x8110000A | Invalid expression ID specified, or expression ID not found in store
E_EXPR_EXPRDELFAILED | 0x81100010 | Delete operation failed, possibly due to other expressions having dependencies on this expression
E_EXPR_NOCONNECTIONSTRING | 0x8110000D | No connection string specified

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

If the specified expression has a non-zero reference count, meaning that other expressions depend on the specified expression, the expression is not deleted.

Call the Connect method before calling the DeleteExpression method.

See Also

ExpressionStore Object

IExpressionStore::Connect

IExpressionStore::NewExpression


IExpressionStore::Disconnect

Use this method to set the connection string to the expression store to an empty string.

Definition

HRESULT IExpressionStore::Disconnect(
);

Parameters

None.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about connecting and disconnecting to an expression store, see IExpressionStore::Connect

See Also

ExpressionStore Object


IExpressionStore::Export

Use this method to export the expressions stored in the expression store to a file.

Definition

HRESULT IExpressionStore::Export(
BSTR bstrFileName
);

Parameters

bstrFileName

[in] A BSTR that contains the name of the file used to store the expressions.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_EXPR_BADCONNECTION | 0x8110001F | Invalid connection
E_EXPR_NOCONNECTIONSTRING | 0x8110000D | No connection string specified

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The file being exported to should not exist prior to the call or the method will fail. If an absolute path is not specified, the file is placed in the \WINNT\system32 folder.

After the method successfully completes, the file contains the XML schema for the expression recordset followed by the XML representation of each expression recordset in the expression store.

Use the Import method to copy the expressions in a file to the expression store.

Call the Connect method before calling the Export method.

See Also

Expression Recordset

Expression XML Structures

ExpressionStore Object

IExpressionStore::Import


IExpressionStore::GetAllExprs

Use this method to retrieve an ADO hierarchical Recordset object that contains all the expressions residing in the expression store.

Definition

HRESULT IExpressionStore::GetAllExprs(
_Recordset** ppRSExprs
);

Parameters

ppRSExprs

[out, retval] An address of a pointer to an ADO hierarchical Recordset object that contains all the expressions residing in the expression store.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_EXPR_BADCONNECTION | 0x8110001F | Invalid connection
E_EXPR_NOCONNECTIONSTRING | 0x8110000D | No connection string specified

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The Recordset object contains one record for each expression in the expression store. For information on the format and fields of the Recordset object, see Expression Recordset.

Use the GetExpression method to retrieve a single expression from the expression store.

Call the Connect method before calling the GetAllExprs method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

The ppRSExprs parameter contains valid data only if the method completes successfully.

See Also

ExpressionStore Object

IExpressionStore::Connect

IExpressionStore::GetExpression


IExpressionStore::GetExpression

Use this method to retrieve an ADO hierarchical Recordset object that contains the specified expression.

Definition

HRESULT IExpressionStore::GetExpression(
long nExprID,
_Recordset** ppRSExpr
);

Parameters

nExprID

[in] A long that contains the unique identifier of the expression.

ppRSExpr

[out, retval] An address of a pointer to an ADO hierarchical Recordset object that contains the expression.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details. If the method does not complete successfully, the address of the pointer to the Recordset object is set to NULL.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_EXPR_BADCONNECTION | 0x8110001F | Invalid connection
E_EXPR_BADEXPRID | 0x8110000A | Invalid expression ID specified, or expression ID not found in store
E_EXPR_NOCONNECTIONSTRING | 0x8110000D | No connection string specified

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

To access all expressions in the connected expression store, use the GetAllExprs method.

Call the Connect method before calling the GetExpression method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

The ppRSExps parameter contains valid data only if the method completes successfully.

See Also

Expression Recordset

ExpressionStore Object

IExpressionStore::Connect

IExpressionStore::GetAllExprs

IExpressionStore::NewExpression


IExpressionStore::GetExprID

Use this method to translate the name of an expression into its corresponding expression ID.

Definition

HRESULT IExpressionStore::GetExprID(
BSTR strExprName,
long* pnExprID
);

Parameters

strExprName

[in] A BSTR that contains the expression name.

pnExprID

[out, retval] A pointer to a long that contains the expression ID. On failure, the expression ID is set to EXPRID_INVALID (defined as -1).

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_EXPR_BADCONNECTION | 0x8110001F | Invalid connection
E_EXPR_BADEXPRNAME | 0x81100003 | Invalid expression name, or expression name not found in store
E_EXPR_NOCONNECTIONSTRING | 0x8110000D | No connection string specified

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

Use the GetExprName method to translate the ID of an expression into its corresponding expression name.

Call the Connect method before calling the GetExprID method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

The ppExprID parameter contains valid data only if the method completes successfully.

See Also

ExpressionStore Object

IExpressionStore::Connect

IExpressionStore::GetExpression

IExpressionStore::GetExprName

IExpressionStore::RenameExpression


IExpressionStore::GetExprName

Use this method to translate the ID of an expression into its corresponding expression name.

Definition

HRESULT IExpressionStore::GetExprName(
long nExprID,
BSTR* pstrExprName
);

Parameters

nExprID

[in] A long that contains a unique expression ID.

pstrExprName

[out, retval] A pointer to a BSTR that contains the name of the expression. On failure, the expression name is set to NULL.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_EXPR_BADCONNECTION | 0x8110001F | Invalid connection
E_EXPR_BADEXPRID | 0x8110000A | Invalid expression ID specified, or expression ID not found in store
E_EXPR_NOCONNECTIONSTRING | 0x8110000D | No connection string specified

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

Use the GetExprID method to translate the name of an expression into its corresponding expression ID.

Call the Connect method before calling the GerExprName method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

The pstrExprName parameter contains valid data only if the method completes successfully.

See Also

ExpressionStore Object

IExpressionStore::Connect

IExpressionStore::GetExprID


IExpressionStore::Import

Use this method to import expressions from a file into the expression store.

Definition

HRESULT IExpressionStore::Import(
BSTR bstrFileName
);

Parameters

bstrFileName

[in] A BSTR that contains the path and name of the file from which to import the expressions.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_EXPR_BADCONNECTION | 0x8110001F | Invalid connection
E_EXPR_NOCONNECTIONSTRING | 0x8110000D | No connection string specified
E_EXPR_NONEMPTYSTORE | 0x8110000C | Cannot import to a non-empty store

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The expression store must be empty in order to import expressions.

The import file must contain the XML schema for the expression recordset followed by the XML representation of each expression recordset. Expression recordsets with invalid expression bodies are imported but will cause an error upon evaluation.

Use the Export method to copy the XML schema for the expression recordset and all the expressions from the expression store to a file.

Call the Connect method before calling the Import method.

See Also

Expression Recordset

Expression XML Structures

ExpressionStore Object

IExpressionStore::Export


IExpressionStore::NewExpression

Use this method to return an ADO hierarchical Recordset object that contains an empty expression.

Definition

HRESULT IExpressionStore::NewExpression(
_Recordset** ppRSExpr
);

Parameters

ppRSExpr

[out, retval] An address of a pointer to an ADO hierarchical Recordset object that contains an empty expression.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_EXPR_BADCONNECTION | 0x8110001F | Invalid connection
E_EXPR_NOCONNECTIONSTRING | 0x8110000D | No connection string specified

Remarks

Populate the returned Recordset object with data describing the new expression. For information on the format and required fields of the Recordset object, see Expression Recordset.

Save the newly defined expression to the expression store using the SaveExpression method. The SaveExpression method automatically generates a new, unique expression ID and stores it with the new expression.

Call the Connect method before calling the NewExpression method.

See Also

ExpressionStore Object

IExpressionStore::Connect

IExpressionStore::SaveExpression


IExpressionStore::Query

Use this method to retrieve a Recordset object containing expressions that match the specified query conditions. At least one of the optional arguments must be specified.

Definition

HRESULT IExpressionStore::Query(
VARIANT vName,
VARIANT vCategory,
VARIANT vProfiles,
_Recordset** ppRSExprs
);

Parameters

vName

[in, optional] When specified, a BSTR name to match expressions against. This is used in an SQL LIKE clause that permits wildcards.

vCategory

[in, optional] When specified, a BSTR containing the category or SAFEARRAY of category strings to match expressions against. This is used in an SQL LIKE clause that permits wildcards.

vProfiles

[in, optional] When specified, a BSTR containing the profile name or SAFEARRAY of profile names to match expressions against. Profile names must be specified without wildcards.

ppRSExprs

[out, retval] An address of a pointer to a Recordset object that contains the result set of expressions. On failure, the pointer to the Recordset object will be set to NULL.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_EXPR_BADCONNECTION | 0x8110001F | Invalid connection
E_EXPR_NOCONNECTIONSTRING | 0x8110000D | No connection string specified

Remarks

If a combination of the optional parameters is specified, the retrieved expressions satisfy all constraints (implicit AND applied). For example, if name = "Robert%" and category = "General", only expressions with names starting with "Robert" and with a category of "General" will be returned.

When multiple profile names are specified, the query result includes expressions with profile requirements (dependencies) that include any of the listed profile names (implicit OR applied). Thus, if name = "Robert%" and the profiles "User" and "Context" are specified as profiles, the Query method will return all expressions with names starting with "Robert" and profiles requiring only "User", only "Context", or both "User" and "Context".

For details on the ADO Recordset object that represents the expression, see Expression Recordset.

Call the Connect method before calling the Query method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

The ppRSExprs parameter contains valid data only if the method completes successfully.

See Also

ExpressionStore Object

IExpressionStore::Connect


IExpressionStore::RenameExpression

Use this method to rename an existing expression in the expression store. The new expression name must be unique or the operation will fail.

Definition

HRESULT IExpressionStore::RenameExpression(
long nExprID,
BSTR strNewName
);

Parameters

nExprID

[in] A long that contains the expression ID.

strNewName

[in] A BSTR that contains the new name.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_EXPR_BADCONNECTION | 0x8110001F | Invalid connection
E_EXPR_BADEXPRID | 0x8110000A | Invalid expression ID specified, or expression ID not found in store
E_EXPR_BADEXPRNAME | 0x81100003 | Invalid expression name
E_EXPR_DUPEXPRNAME | 0x81100007 | Duplicate expression name
E_EXPR_INVALIDFIELDSIZE | 0x81100005 | The new name exceeds the maximum size of 30 characters
E_EXPR_NOCONNECTIONSTRING | 0x8110000D | No connection string specified

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

Use the GetExprID method to translate an expression name to its corresponding expression ID.

Call the Connect method before calling the RenameExpression method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ExpressionStore Object

IExpressionStore::Connect

IExpressionStore::GetExprID


IExpressionStore::SaveExpression

Use this method to save a new or modified expression to the expression store. For a new expression, the SaveExpression method automatically generates a unique expression ID and stores it with the expression.

Definition

HRESULT IExpressionStore::SaveExpression(
_Recordset* pRSExpr
);

Parameters

pRSExpr

[in] A pointer to the ADO hierarchical Recordset object that contains the expression.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_EXPR_BADCONNECTION | 0x8110001F | Invalid connection
E_EXPR_BADEXPRBODY | 0x81100004 | Invalid or missing expression body
E_EXPR_BADEXPRCATEGORY | 0x8110000A | Invalid expression category specified
E_EXPR_BADEXPRNAME | 0x81100003 | Invalid expression name
E_EXPR_CYCLEDETECTED | 0x81100006 | A cycle was detected in the expression dependencies of this expression
E_EXPR_DUPEXPRDEPS | 0x81100009 | Duplicate expression dependency
E_EXPR_DUPEXPRNAME | 0x81100007 | Duplicate expression name
E_EXPR_DUPPROFDEPS | 0x81100008 | Duplicate profile dependency
E_EXPR_INVALIDEXPRDEPS | 0x8110000B | One or more of the expression dependencies refers to an expression ID that does not exist
E_EXPR_INVALIDFIELDSIZE | 0x81100005 | The new name exceeds the maximum size of 30 characters
E_EXPR_NOCONNECTIONSTRING | 0x8110000D | No connection string specified
E_EXPR_NOPROFDEPS | 0x81100002 | Expression must have at least one profile-dependency to be saved

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

If the expression being saved is not currently in the expression store, the SaveExpression method generates a unique identifier and populates the ExprID field of the Recordset object. The identifier is a positive integer. For more information about the format and fields of the Recordset object, see Expression Recordset.

The ExpressionStore object performs rudimentary checks for expression dependencies when an expression is saved or deleted. This includes any direct references, a test for cyclic referencing, and any references to non-existent expressions.

Call the Connect method before calling the SaveExpression method.

See Also

ExpressionStore Object

IExpressionStore::Connect

IExpressionStore::GetExpression

IExpressionStore::NewExpression


ExprFltrQueryBldr Object

Use this object to translate an expression in Extensible Markup Language (XML) form into a SQL filter query string. A filter query returns a subset of items from a database based on a combination of attribute values.

ProgID: | Commerce.ExprFltrQueryBldr (Externally creatable)
COM Class Name: | ExprFltrQueryBldr
COM Interface Name: | IExprFltrQueryBldr
Interface ID Constant: | IID_IExprFltrQueryBldr
Header File: | exprfltrbldr.h, mspu_guids.h
Type Library Name: | Microsoft Commerce 2000 Expression Builder Type Library
DLL Name: | exprfltrbldr.dll
Threading Model: | Apartment

In C++, use the IExprFltrQueryBldr interface to access the properties and methods of the ExprFltrQueryBldr object.

Because this object is primarily intended for use within ASP script, access from C++ will not be common.

The methods of the ExprFltrQueryBldr object are shown in the following table.

Method | Description
ConvertExprToSqlFltrStr | Converts an expression in XML form to a SQL filter string.
ConvertExprUsingDict | Converts an expression in XML form that references a Dictionary object into a SQL filter string.

Remarks

The expression in XML form may contain a reference to a Dictionary object.

See Also

Expression XML Structures


IExprFltrQueryBldr::ConvertExprToSqlFltrStr

Use this method to convert an expression in Extensible Markup Language (XML) form to a SQL filter query string.

Definition

HRESULT IExprFltrQueryBldr::ConvertExprToSqlFltrStr(
BSTR pExpression,
BSTR* pFilter
);

Parameters

pExpression

[in] A BSTR that contains the expression in XML form.

pFilter

[out, retval] A pointer to a BSTR used to return the SQL filter string.

Return Values

This method returns an HRESULT indicating the method completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pFilter parameter contains valid data only if the method completes successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ExprFltrQueryBldr Object


IExprFltrQueryBldr::ConvertExprUsingDict

Use this method to convert an expression in Extensible Markup Language (XML) form containing a reference to a Dictionary object into a SQL filter query string.

Definition

HRESULT IExprFltrQueryBldr::ConvertExprUsingDict(
BSTR pExpr,
IDispatch* pDict,
BSTR* pDest
);

Parameters

pExpr

[in] A BSTR that contains the expression in XML form.

pDict

[in] A pointer to the IDispatch interface of a Dictionary object that contains the values referenced by the expression.

pDest

[out, retval] A pointer to a BSTR used to return the SQL filter string.

Return Values

This method returns an HRESULT indicating whether the method completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

In the XML expression, a reference to a Dictionary object is made by preceding the value inside the IMMED-VAL tags with the keyword 'context'. If such a reference is found during conversion of the expression, the reference is replaced with the value read from the Dictionary object.

The pDest parameter contains valid data only if the method completes successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ExprFltrQueryBldr Object


GenID Object

Use this object to generate globally unique identifiers (GUID), or to create and maintain multiple, global sequential counters that are persisted in a database. A global counter is one that can work across multiple computers.

ProgID: | Commerce.GenID (Externally creatable)
COM Class Name: | GenID
COM Interface Name: | IGenID
Interface ID Constant: | IID_IGenID
Header File: | genid.h
Type Library Name: | Microsoft Commerce 2000 GenID Type Library
DLL Name: | GenID.dll
Threading Model: | Both

In C++, use the IGenID interface to access the methods of the GenID object.

The methods of the GenID object are shown in the following table.

Method | Description
GenBase5GUIDString | Generates a base5 GUID string.
GenGUIDString | Generates a GUID string.
GetCounterValue | Retrieves the value of the specified counter and then increments the counter.
Initialize | Connects the GenID object to the database that stores the table of counters.
InitializeCounter | Initializes a new counter or resets an existing counter.


IGenID::GenBase5GUIDString

Use this method to generate a base5 Globally Unique Identifier (GUID) string.

Definition

HRESULT IGenID::GenBase5GUIDString(
BSTR* pbstrBase5GuidString
);

Parameters

pbstrBase5GuidString

[out, retval] A pointer to a BSTR used to return the base5 GUID string.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

A base5 GUID is used to store a slightly more compact version of the traditional GUID. The 128 binary digits are divided into groups of 5 instead of 4 with each group represented by the characters 0-9, and 22 characters of the alphabet. This results in a 26-digit representation for the GUID rather than the customary 32-digit representation.

The pbstrBase5GuidString parameter contains valid data only if the method completes successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

GenID Object


IGenID::GenGUIDString

Use this method to generate a Globally Unique Identifier (GUID) string.

Definition

HRESULT IGenID::GenGUIDString(
BSTR* pbstrGUID
);

Parameters

pbstrGUID

[out, retval] A pointer to a BSTR used to return the GUID.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pbstrGUID parameter contains valid data only if the method completes successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

GenID Object


IGenID::GetCounterValue

Use this method to retrieve and increment the value stored in the specified counter.

Definition

HRESULT IGenID::GetCounterValue(
BSTR bstrCounterName,
long cDigits,
BSTR* pbstrCounterValue
);

Parameters

bstrCounterName

[in] A BSTR that contains the counter name.

cDigits

[in] An long that contains the number of digits to return.

pbstrCounterValue

[out, retval] A pointer to a BSTR used to return the counter value.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

After the current value of the counter is returned, the counter is incremented by one. Use the InitializeCounter method to reset the counter.

If the value of the counter is less than the number of digits requested, the value is left padded with zeroes.

The Initialize method must be called before calling the GetCounterValue method.

The pbstrCounterValue parameter contains valid data only if the method completes successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

GenID Object


IGenID::Initialize

Use this method to connect the GenID object to the database that stores the table of counters.

Definition

HRESULT IGenID::Initialize(
BSTR bstrDBConnectionString,
long cBlockSizeHint
);

Parameters

bstrDBConnectionString

[in] A BSTR that contains the connection information to the database.

cBlockSizeHint

[in, optional, defaultvalue (1)] Not implemented, leave blank.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

This method must be called before calling the GetCounterValue and InitializeCounter methods.

The connection string may be obtained through the SiteConfigReadOnly object or through the Commerce Server Manager console from the connstr_db_Transactions property under Commerce Server Manager\Commerce Sites\<site name>\Site Resources\Transactions.

See Also

GenID Object


IGenID::InitializeCounter

Use this method to create or reset a global, sequential counter.

Definition

HRESULT IGenID::InitializeCounter(
BSTR bstrCounterName,
long dwInitialValue
);

Parameters

bstrCounterName

[in] A BSTR that contains the counter name.

dwInitialValue

[in] An Integer that contains the initial value of the counter.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

Any number of counters may be created. If the counter already exists, its value is reset to the specified initial value.

A global counter will work across multiple computers.

The Initialize method must be called before calling the InitializeCounter method.

The dwInitialValue parameter contains valid data only if the method completes successfully.

See Also

GenID Object


GlobalConfig Object

Use this object to accomplish the following:

  • Create or delete resource configuration information

  • Save any updated global configuration information to the Administration database

  • Add a site

Depending on how you add your own custom resource, you should be able to use this object to access configuration settings from the Administration database.

ProgID: | Commerce.GlobalConfig (Externally creatable)
COM Class Name: | GlobalConfig
COM Interface Name: | _GlobalConfig
Interface ID Constant: | None
Header File: | None
Type Library Name: | Microsoft Commerce 2000 Configuration Type Library
DLL Name: | MSCSCfg.dll
Threading Model: | Apartment

In C++, use the _GlobalConfig interface to access the properties and methods of the GlobalConfig object.

The single property of the GlobalConfig object is shown in the following table.

Property | Type | Description
Fields | Fields | Returns group-level configuration data. This property is read-only.

The methods of the GlobalConfig object are shown in the following table.

Method | Description
CreateServiceConfig | Creates and writes configuration information for the specified resource to the Administration database.
CreateSiteConfig | Creates a site.
DeleteServiceConfig | Deletes configuration information for the specified resource.
DeleteSiteConfig | Deletes the specified configuration for the site and all configurations for the associated resources.
GetIfCollection | Converts values read from the Fields property into appropriate objects such as a SimpleList object or a Variant Array.
GetResourcePropAttrib | Gets a dictionary of key/value pairs that denote the attributes of the specified property of the specified resource.
Initialize | Loads the global configuration data from the Administration database.
MakeArrayFromSimpleList | Converts the specified SimpleList object into an Array.
MakeArrayFromString | Converts values read from the Fields property into an Array.
MakeSimpleListFromArray | Converts an Array into a SimpleList object.
MakeStringFromArray | Converts an Array into an encoded string, which can be written to the Fields property.
MakeStringFromSimpleList | Converts a SimpleList object into an encoded string, which can be written to the Fields property.
SaveConfig | Saves the global configuration settings to the Administration database.
Sites | Returns a list of all of the sites available in the administration data store.

See Also

Integrating Custom Resources

Configuration Objects

SiteConfig Object

SiteConfigReadOnly Object


_GlobalConfig::CreateServiceConfig

Use this method to create an instance of the class specified by the bstrConfigSchemaClass parameter, set the Name property of the instance to the name specified in the bstrServiceName parameter, and load the instance into the site recordset. This method calls the SaveConfig method.

Definition

HRESULT _GlobalConfig::CreateServiceConfig(
BSTR bstrServiceName,
BSTR bstrConfigSchemaClass
);

Parameters

bstrServiceName

[in] A BSTR that contains the new name for the resource configuration object instance.

bstrConfigSchemaClass

[in] A BSTR that contains the resource configuration schema class name.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The Initialize method must be called before this method can be called.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

The following table contains a list of schema classes for this method.

Administration Database Class Name | Resource Name
MSCS_AuthManager | Site CS Authentication
MSCS_DirectMailer | Direct Mailer
MSCS_Predictor | Predictor
MSCS_Datawarehouse_Group | Global Data Warehouse
MSCS_BizDataStore | Profiles

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

GlobalConfig Object

_GlobalConfig::DeleteServiceConfig


_GlobalConfig::CreateSiteConfig

Use this method to create a site using the name specified in the bstrSiteName parameter. This method calls the SaveConfig method. This method is used primarily from Commerce Server Manager or by Commerce Server Site Packager. The correct ACLs are set on the entries in the IIS metabase by the Commerce Server Site Packager, to ensure that the Admin objects can only be operated on by site administrators.

Definition

HRESULT _GlobalConfig::CreateSiteConfig(
BSTR bstrSiteName,
IMSCSSiteConfigAdmin** ppsca
);

Parameters

bstrSiteName

[in] A BSTR that contains the new site name.

ppsca

[out] The address of a pointer to the SiteConfig object used to return the site configuration settings.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The Initialize method must be called before this method can be called.

The ppsca parameter contains valid data only if the method returns successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

GlobalConfig Object

_GlobalConfig::DeleteSiteConfig


_GlobalConfig::DeleteServiceConfig

Use this method to delete the specified resource, and to delete the Administration database association that links this resource to the site instance.

Definition

HRESULT _GlobalConfig::DeleteServiceConfig(
BSTR bstrServiceName
);

Parameters

bstrServiceName

[in] A BSTR that contains the name of the resource configuration object to be deleted.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The Initialize method must be called before this method can be called.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

GlobalConfig Object

_GlobalConfig::CreateServiceConfig


_GlobalConfig::DeleteSiteConfig

Use this method to delete a site configuration object instance for the current site from the Administration database. This method is primarily used by Commerce Server Manager or by Commerce Server Site Packager.

Definition

HRESULT _GlobalConfig::DeleteSiteConfig(
BSTR bstrSiteName
);

Parameters

bstrSiteName

[in] A BSTR that contains the site name.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The Initialize method must be called before this method can be called.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

GlobalConfig Object

_GlobalConfig::CreateSiteConfig


_GlobalConfig::get_Fields

The Fields property is a read-only Fields object. The Fields property contents include recordsets that hold the configuration settings of resources. A Fields object is an ADO disconnected recordset.

Definition

HRESULT _GlobalConfig::get_Fields(
Fields** pFields
);

Parameters

pFields

[out] The address of a pointer to the Fields object used to return resource configuration information.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This property returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The Initialize method must be called before this method can be called.

The pFields parameter contains valid data only if the property is accessed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

GlobalConfig Object


_GlobalConfig::GetIfCollection

Use this method to convert values read from the Fields property into appropriate objects such as a SimpleList object or a Variant Array. If the encoding in the string contained in the Fields property indicates a SimpleList object, then a SimpleList object is returned. If the encoding indicates a Variant Array, then a Variant Array is returned. If no collection object is indicated, then the method returns the original encoded input string.

Definition

HRESULT _GlobalConfig::GetIfCollection(
VARIANT* strList,
VARIANT* retVal
);

Parameters

strList

[in] A pointer to the VARIANT that contains the encoded string to be converted.

retVal

[out, retval] A pointer to a VARIANT used to return the converted data in the appropriate data type.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The retVal parameter contains valid data only if the method completes successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

GlobalConfig Object


_GlobalConfig::GetResourcePropAttrib

Use this method to get a dictionary of key/value pairs that denote the attributes of the specified property of the specified resource.

Definition

HRESULT _GlobalConfig::GetResourcePropAttrib(
BSTR strResourceName,
BSTR strPropName,
IDictionary** idictResPropAttrib
);

Parameters

strResourceName

[in] A BSTR that contains the resource name.

strPropName

[in] A BSTR that contains the resource property name.

idictResPropAttrib

[out, retval] The address of a pointer to receive an IDictionary interface, which is used to return the key/value pairs that denote the attributes of the specified property of the specified resource.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The Initialize method must be called before this method can be called.

The idictResPropAttrib parameter contains valid data only if the method completes successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

GlobalConfig Object


_GlobalConfig::Initialize

Use this method to load the global configuration from the Administration database.

Definition

HRESULT _GlobalConfig::Initialize(
BSTR bstrGroupName
);

Parameters

bstrGroupName

[in, optional] A BSTR reserved for future use. This method ignores the value placed in this parameter.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

GlobalConfig Object


_GlobalConfig::MakeArrayFromSimpleList

Use this method to convert the specified SimpleList object into an Array.

Definition

HRESULT _GlobalConfig::MakeArrayFromSimpleList(
IDispatch** list,
VARIANT* vtArray
);

Parameters

list

[in] An IDispatch interface pointer to the SimpleList object that you wish to convert into an Array.

vtArray

[out, retval] A pointer to a VARIANT containing the converted Array.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The vtArray parameter contains valid data only if the method completes successfully.

Important

  • There is a special group of methods used with multivalued arrays. These methods are the only approved and recommended way of storing and retrieving multivalued arrays in the Administration database. You must use the following methods with any property that has the structure of a multivalued array:
    • MakeArrayFromSimpleList

    • MakeSimpleListFromArray

    • MakeArrayFromString

    • MakeStringFromArray

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

GlobalConfig Object


_GlobalConfig::MakeArrayFromString

Use this method to convert an encoded string read from the Fields property into an Array. If the encoded string does not indicate Array properties, then the method returns the original string that was passed into it.

Definition

HRESULT _GlobalConfig::MakeArrayFromString(
VARIANT strList,
VARIANT* vtArray
);

Parameters

strList

[in] A VARIANT that contains the encoded string.

vtArray

[out, retval] A pointer to a VARIANT used to return the converted Array or unconverted String.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The vtArray parameter contains valid data only if the method completes successfully.

Important

  • There is a special group of methods used with multivalued arrays. These methods are the only approved and recommended way of storing and retrieving multivalued arrays in the Administration database. You must use the following methods with any property that has the structure of a multivalued array:
    • MakeArrayFromSimpleList

    • MakeSimpleListFromArray

    • MakeArrayFromString

    • MakeStringFromArray

Note

  • This method can only be used on values exposed by the Fields object. The client-side disconnected ADO recordset has no support for Variants, Arrays, or objects as Fields columns. Therefore, the GlobalConfig object resorts to storing data in an encoded string format.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

GlobalConfig Object


_GlobalConfig::MakeSimpleListFromArray

Use this method to convert an Array into a SimpleList object.

Definition

HRESULT _GlobalConfig::MakeSimpleListFromArray(
VARIANT* varArray,
IDispatch** iSimpleList
);

Parameters

varArray

[in] A pointer to the VARIANT that contains the Array to convert.

iSimpleList

[out, retval] The address of an IDispatch pointer used to return the converted SimpleList object.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The iSimpleList parameter contains valid data only if the method completes successfully.

Important

  • There is a special group of methods used with multivalued arrays. These methods are the only approved and recommended way of storing and retrieving multivalued arrays in the Administration database. You must use the following methods with any property that has the structure of a multivalued array:
    • MakeArrayFromSimpleList

    • MakeSimpleListFromArray

    • MakeArrayFromString

    • MakeStringFromArray

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

GlobalConfig Object


_GlobalConfig::MakeStringFromArray

Use this method to convert an Array object into an encoded string, which can be written to the Fields property.

Definition

HRESULT _GlobalConfig::MakeStringFromArray(
VARIANT* varArray,
VARIANT* vtEncodedString
);

Parameters

varArray

[in] A pointer to the VARIANT that contains the Array to encode.

vtEncodedString

[out, retval] A pointer to a VARIANT used to return the encoded string.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The Initialize method must be called before this method can be called.

The vtEncodedString parameter contains valid data only if the method completes successfully.

Important

  • There is a special group of methods used with multivalued arrays. These methods are the only approved and recommended way of storing and retrieving multivalued arrays in the Administration database. You must use the following methods with any property that has the structure of a multivalued array:
    • MakeArrayFromSimpleList

    • MakeSimpleListFromArray

    • MakeArrayFromString

    • MakeStringFromArray

Note

  • This method can only be used when updating values exposed by the Fields object. The client-side disconnected ADO recordset has no support for Variants, Arrays, or objects as Fields columns. Therefore, the GlobalConfig object resorts to storing data in an encoded string format.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

GlobalConfig Object


_GlobalConfig::MakeStringFromSimpleList

Use this method to convert a SimpleList object into an encoded string, which can be written to the Fields property.

Definition

HRESULT _GlobalConfig::MakeStringFromSimpleList(
IDispatch** slist,
BSTR* strEncodedString
);

Parameters

slist

[in] An IDispatch interface pointer to the SimpleList object that you wish to convert into an encoded string.

strEncodedString

[out, retval] A pointer to a String used to return the encoded string.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The Initialize method must be called before this method can be called.

The strEncodedString parameter contains valid data only if the method completes successfully.

Important

  • There is a special group of methods used with multivalued arrays. These methods are the only approved and recommended way of storing and retrieving multivalued arrays in the Administration database. You must use the following methods with any property that has the structure of a multivalued array:
    • MakeArrayFromSimpleList

    • MakeSimpleListFromArray

    • MakeArrayFromString

    • MakeStringFromArray

Note

  • This method can only be used when updating values exposed by the Fields object. The client-side disconnected ADO recordset has no support for Variants, Arrays, SimpleLists, or objects as Fields columns. Therefore, the GlobalConfig object resorts to storing data in an encoded string format.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

GlobalConfig Object


_GlobalConfig::SaveConfig

Use this method to save the global configuration settings to the Administration database.

Definition

HRESULT _GlobalConfig::SaveConfig(
);

Parameters

None.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The Initialize method must be called before this method can be called.

See Also

GlobalConfig Object


_GlobalConfig::Sites

Use this method to retrieve a list of all the sites available in the Administration database.This method returns a Recordset object that contains a single record; the number of fields in the Fields collection is equal to the number of sites in the Commerce Server 2000 installation. Each Fields collection contains the name of one of the sites.

Definition

HRESULT _GlobalConfig::Sites (

_Recordset** rsRecordSet
);

Parameters

rsRecordSet

[out, retval] The address of a pointer to a Recordset object used to return the list of all sites available in the Administration data store.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The Initialize method must be called before this method can be called.

The rsRecordSet parameter contains valid data only if the method completes successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

GlobalConfig Object


ListManager Object

Use this object to create and manage lists of users for the User Profile Management system, lists of e-mail addresses for the Direct Mailer, lists of segment members for the Predictor resource, lists generated from Analysis reports, and lists created from files and SQL queries.

ProgID: | Commerce.ListManager (Externally creatable)
COM Class Name: | ListManager
COM Interface Name: | IListManager
Interface ID Constant: | None
Header File: | None
Type Library Name: | Microsoft Commerce 2000 ListManager Type Library
EXE Name: | listmanager.exe
Threading Model: | Both

The properties of the ListManager object are shown in the following table.

Property | Type | Description
ConnectionString | BSTR | Stores the connection string to the database used by the ListManager object to store lists. This value is set when passing the ConnectionString parameter to the Initialize method. This property is read-only.
Status | long | Stores the current status of the ListManager object. This property is read-only.

The methods of the ListManager object are shown in the following table.

Method | Description
AddUserToMailingList | Adds a user to a mailing list.
CancelOperation | Cancels a currently running asynchronous operation.
Copy | Makes a copy of a list.
CreateEmpty | Creates an empty list for subsequent operations.
CreateFromDWCalc | Creates a list from an Analysis report.
CreateFromFile | Creates a list from a file.
CreateFromSegment | Creates a list from a Predictor resource segment.
CreateFromSql | Creates a list from an SQL query.
Delete | Deletes a list.
ExportToFile | Exports a list to a file.
ExportToSql | Exports a list to a database table.
ExtractMailingList | Creates a new mailing list from a generic list that contains an rcp_email column.
GetListFlags | Retrieves the Flags bitmask for a list.
GetListId | Retrieves the list ID.
GetListName | Retrieves the list name.
GetListProperty | Retrieves a list property.
GetLists | Enumerates all known lists at the time of the call.
GetListUserFlags | Retrieves the UserFlags bitmask for a list.
GetOperationInfo | Retrieves information on a list operation.
GetOperations | Enumerates all operations running at the time of the call.
Initialize | Initializes the ListManager object.
RemoveUserFromMailingList | Removes a user from a mailing list.
Rename | Renames a list.
SetDesc | Assigns a description to a list.
SetListProperty | Sets a list property.
Subtract | Subtracts one list from another list, and stores the results in a third list.
Union | Produces a union of two lists (combines the lists and eliminates duplicates), and stores the results in a third list.
WaitOnOperation | Waits for an operation to complete or a timeout to occur, then returns.

Remarks

List Manager has functionality to manipulate two types of lists, Generic and Mailing. Each type may also have User and Mailable attributes. Lists are designated as static or dynamic depending on when the data is imported.

A Generic list may have any set of column names and types - it essentially maps to a SQL table.

A Mailing list is a list for use with Direct Mailer. It contains a list of recipients to receive mail or a list of recipients who should be opted out of a mailing. Each mailing list has its own table.

The following table describes the columns of a Mailing list table.

Field | Type | Description
rcp_email | NVARCHAR [256] | E-mail address of the recipient.
rcp_guid | NVARCHAR [64] | (Optional) User ID. Usually a GUID which is a key to the profile of the user.
rcp_fmt | smallint | (Optional) Message format flag. Legal values are: 1 - TEXT 2 - MIME 3 - MHTML
rcp_locale | NVARCHAR[20] | (Optional) Preferred character set of the recipient. See DirectMailer specifications for details.
rcp_url | NVARCHAR[2084] | (Optional) URL used for retrieving personalized content for the user.

A Mailable list is any list with an rcp_email column.

A User list is any list with an rcp_guid column.

In a static list, records are imported at the time the list is created.

A dynamic list imports records on demand when referenced by another operation.

List Manager can import lists from the following sources:

  • An SQL query run against an ODBC data source

  • An Analysis report run from the Business Desk

  • A Predictor Resource segment

  • A text file (CSV format)

List Manager can export lists to the following destinations:

  • A SQL Server 2000 table in an external database

  • A text file (CSV format)

List Manager allows time consuming operations to run in an asynchronous manner wherein the operation returns immediately after the process has started and assigns an operation ID that can be used to access the operation.

List Manager stores information about lists and operations in the lm_master and lm_master_operations tables, respectively.

See Also

List Management Objects


IListManager::AddUserToMailingList

Use this method to add a user record to a mailing list.

Definition

HRESULT IListManager::AddUserToMailingList(
VARIANT listID,
VARIANT UserEmail,
VARIANT UserGUID,
VARIANT UserFmt,
VARIANT UserLocale,
VARIANT UserUrl
);

Parameters

listID

[in] A VARIANT that contains the ID or name of the list.

UserEmail

[in] A VARIANT that contains the e-mail address of the user.

UserGUID

[in, optional] A VARIANT that contains the ID of the user (usually a GUID).

UserFmt

[in, optional] A VARIANT that contains the message format flag. See the Remarks section for more information.

UserLocale

[in, optional] A VARIANT that contains the preferred character set of the user.

UserUrl

[in, optional] A VARIANT that contains a URL used for retrieving personalized content for the user.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_LM_LIST_BUSY | 0x8C400008 | The specified list is currently busy with another operation.
E_LM_LIST_IN_FAILED_STATE | 0x8C40001D | The specified list is in a FAILED state and may not be used for the operation.
E_LM_LIST_NOT_FOUND | 0x8C400006 | The specified list does not exist.
E_LM_MAILABLE_LIST_NO_EMAILS | 0x8C40000D | The list is designated as a Mailable list but does not contain an rcp_email column.
E_LM_MUST_BE_STATIC | 0x8C400019 | The operation requires a static list and the specified list is dynamic.
E_LM_NOT_MAILING_LIST | 0x8C400018 | The operation requires a Mailing list and the specified list is not a mailing list.
E_LM_SQLERROR | 0x8C400003 | Error while executing SQL/ADO operation.
E_LM_USER_LIST_NO_GUIDS | 0x8C40000E | The list is designated as a User list but does not contain an rcp_guid column.
OLE_E_BLANK | 0x80040007 | The ListManager object has not been properly initialized.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The UserFmt parameter specifies the format of a message used by the Direct Mailer. The possible values are: text (1), MIME (2), and MHTML (3).

To specify that one or more of the fields should be inserted as NULL, pass VT_NULL, VT_EMPTY, or VT_ERROR as the optional parameter(s).

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ListManager Object


IListManager::CancelOperation

Use this method to cancel the specified ListManager operation.

Definition

HRESULT IListManager::CancelOperation(
VARIANT varOpID
);

Parameters

varOpID

[in] A VARIANT that specifies the Operation ID of the operation to be cancelled.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors, and the standard COM errors with special meanings, that this method can return.

Constant | Value | Description
E_LM_OPERATION_NOT_FOUND | 0x8C400004 | The operation ID does not represent a currently running operation.
E_LM_SQLERROR | 0x8C400003 | Error while executing SQL/ADO operation.
OLE_E_BLANK | 0x80040007 | The ListManager object has not been properly initialized.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The Operation ID passed to this method in the varOpID parameter can be obtained from any of the following calls when they are executed asynchronously:

  • Copy

  • CreateFromDWCalc

  • CreateFromFile

  • CreateFromSql

  • ExportToFile

  • ExportToSql

  • Subtract

  • Union

In addition, the Operation IDs of all currently active operations can be retrieved using the GetOperations method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ListManager Object


IListManager::get_ConnectionString

The ConnectionString property is a read-only string that contains the database connection string the List Manager uses to store lists. This property is set by the Initialize method.

Definition

Get method:

HRESULT IListManager::get_ConnectionString(
BSTR* ConnectionString
);

Parameters

ConnectionString

[out, retval] A pointer to a BSTR used to return the connection string.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

See Also

ListManager Object


IListManager::Copy

Use this method to copy an existing list over another existing list.

Definition

HRESULT IListManager::Copy(
VARIANT srcList,
VARIANT resList,
BOOL bAsync,
VARIANT* pvarOpID
);

Parameters

srcList

[in] A VARIANT that contains the ID or name of the source list.

resList

[in] A VARIANT that contains the ID or name of the result list.

bAsync

[in] A BOOL that specifies whether the copy operation is performed synchronously or asynchronously. A value of True indicates asynchronous processing.

pvarOpID

[out, optional] A pointer to a VARIANT used to return an Operation ID.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_LM_COPY_LIST_OVER_SELF | 0x8C40001C | Cannot copy a list over itself.
E_LM_LIST_BUSY | 0x8C400008 | The specified list is currently busy with another operation.
E_LM_LIST_IN_FAILED_STATE | 0x8C40001D | The specified list is in a FAILED state and may not be used for the operation.
E_LM_LIST_NOT_FOUND | 0x8C400006 | The specified list does not exist.
E_LM_OPER_CANCELED | 0x8C40000B | The operation was canceled.
E_LM_SQLERROR | 0x8C400003 | Error while executing SQL/ADO operation.
OLE_E_BLANK | 0x80040007 | The ListManager object has not been properly initialized.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The result list must exist prior to calling the method; however, any data in the list will be overwritten.

The flags attribute of the destination list is replaced with the flags attribute of the source list. The UserFlags attribute is not changed.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ListManager Object


IListManager::CreateEmpty

Use this method to create an empty list for subsequent operations.

Definition

HRESULT IListManager::CreateEmpty(
BSTR listName,
BSTR listDesc,
long flags,
long userFlags,
VARIANT* pvarID
);

Parameters

listName

[in] A BSTR that provides the name for the new list.

listDesc

[in] A BSTR that provides a description for the new list.

flags

[in] A long that specifies the bitmask flags that control the type of list created.

userFlags

[in] A long that contains application specific user flags. Not used by the ListManager object.

pvarID

[out, retval] A pointer to a VARIANT used to return the ID of the new list.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_LM_INVALID_FLAGS | 0x8C400005 | Invalid flags value.
E_LM_LIST_ALREADY_EXISTS | 0x8C400007 | The specified list has already been created.
E_LM_SQLERROR | 0x8C400003 | Error while executing SQL/ADO operation.
OLE_E_BLANK | 0x80040007 | The ListManager object has not been properly initialized.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

This method is useful for creating an empty list for use as the result list of a copy, subtract, or union operation.

For a list of possible values for the flags parameter, see the GetListFlags method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ListManager Object


IListManager::CreateFromDWCalc

Use this method to create a list from an Analysis report.

Definition

HRESULT IListManager::CreateFromDWCalc(
BSTR listName,
BSTR listDesc,
long lFlags,
long userFlags,
BSTR DWConnStr,
BSTR OLAPConnStr,
BSTR ReportStatusId,
BOOL bAsync,
VARIANT* pvarOpID,
VARIANT* pvarID
);

Parameters

listName

[in] A BSTR that provides the name for the new list.

listDesc

[in] A BSTR that provides a description for the new list.

lFlags

[in] A long that specifies the bitmask flags that control the type of list created.

userFlags

[in] A long that contains application specific user flags. Not used by the ListManager object.

DWConnStr

[in] A BSTR that contains the connection string for the Data Warehouse.

OLAPConnStr

[in] A BSTR that contains the OLAP connection string.

ReportStatusId

[in] A BSTR that contains the ReportStatusID of the report to be imported.

bAsync

[in] A BOOL that specifies whether the creation operation is performed synchronously or asynchronously. A value of True indicates asynchronous processing.

pvarOpID

[out, optional] A pointer to a VARIANT used to return an Operation ID.

pvarID

[out, retval] A pointer to a VARIANT used to return the ID of the new list.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_LM_CONNECTIONFAILED | 0x8C400001 | Failed to establish database connection.
E_LM_CREATE_OBJECT | 0x8C400017 | Unable to create the object.
E_LM_INVALID_FLAGS | 0x8C400005 | Invalid flags value.
E_LM_LIST_ALREADY_EXISTS | 0x8C400007 | The specified list has already been created.
E_LM_MAILABLE_LIST_NO_EMAILS | 0x8C40000D | The list is designated as a Mailable list but does not contain an rcp_email column.
E_LM_OPER_CANCELED | 0x8C40000B | The operation was canceled.
E_LM_REPORTRENDERERFAILED | 0x8C40001A | The report rendering object failed during Analysis report export to ListManager. See the Application event log message logged by that object describing the problem.
E_LM_SQLERROR | 0x8C400003 | Error while executing SQL/ADO operation.
E_LM_USER_LIST_NO_GUIDS | 0x8C40000E | The list is designated as a User list but does not contain an rcp_guid column.
OLE_E_BLANK | 0x80040007 | The ListManager object has not been properly initialized.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

This method calls into the ReportRender object, passing it the DWConnStr, OLAPConnStr, and the ReportStatusId parameters along with a connection string to the database used by the ListManager object, and the table name that it should create.

For a list of possible values for the lflags parameter, see the GetListFlags method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ListManager Object


IListManager::CreateFromFile

Use this method to create a list from a text file.

Definition

HRESULT IListManager::CreateFromFile(
BSTR listName,
BSTR listDesc,
long lFlags,
long userFlags,
BSTR fileName,
long errLimit,
BOOL bAsync,
VARIANT* pvarOpID,
VARIANT* pvarID
);

Parameters

listName

[in] A BSTR that provides the name for the new list.

listDesc

[in] A BSTR that provides a description for the new list.

lFlags

[in] A long that specifies the bitmask flags that control the type of list created.

userFlags

[in] A long that contains application specific user flags. Not used by the ListManager object.

fileName

[in] A BSTR that contains the name of the file from which to create the new list.

errLimit

[in] A long that specifies the maximum number of errors allowed before the operation is terminated. To specify no limit, set the errLimit parameter to zero (0).

bAsync

[in] A BOOL that specifies whether the creation operation is performed synchronously or asynchronously. A value of True indicates asynchronous processing.

pvarOpID

[out, optional] A pointer to a VARIANT used to return an Operation ID.

pvarID

[out, retval] A pointer to a VARIANT used to return the ID of the new list.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors, and the standard COM errors with special meanings, that this method can return.

Constant | Value | Description
E_LM_BAD_FILE_PATH | 0x8C40000A | The specified file path is not valid.
E_LM_FILE_ACCESS_DENIED | 0x8C400009 | The ListManager service does not have permission to open the specified file.Check the permissions for the ListManager service account against the permissions for the file.
E_LM_FILE_NOT_FOUND | 0x8C400015 | The specified file does not exist.
E_LM_FILESHARE_NOT_FOUND | 0x8C400016 | The network share does not exist and a full path was not specified for the file.
E_LM_INVALID_FLAGS | 0x8C400005 | Invalid flags value.
E_LM_LIST_ALREADY_EXISTS | 0x8C400007 | The specified list has already been created.
E_LM_LISTPARSE_NO_GOOD_ROWS | 0x8C40001B | All rows in the file contained parse errors. List import failed.
E_LM_NO_GENERIC_FROM_FILE | 0x8C400014 | Generic lists may not be imported from files.
E_LM_OPER_CANCELED | 0x8C40000B | The operation was canceled.
E_LM_SQLERROR | 0x8C400003 | Error while executing SQL/ADO operation.
OLE_E_BLANK | 0x80040007 | The ListManager object has not been properly initialized.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

If a list with the same name as the listName parameter already exists, the method fails. Lists imported from text files may not be generic lists; they are always mailing lists.

The user account that the List Manager is configured to run under must have permission to access the file. For example, if the file is on a network share, the service must be running under a domain account or must otherwise have permission to access the share.

If an absolute file path and name is not specified, List Manager will look for the file relative to a root folder named CommerceLists on the local computer running the List Manager service. If the folder does not exist, an error is returned.

List Manager recognizes the following input text file format:

   <Mail-to address>,<User ID>,<Message Format>,<Locale>,
   <Source URL><cr><lf>

Mail-to address is the only required field. The Message Format field should be one of the following: 1 = text, 2 = mime, or 3 = mhtml. The Message Format, Locale, and Source fields are provided for use with Direct Mailer.

Any of the fields may be enclosed in double quotation marks. This is required if the value in the field contains any comma or double quotation mark characters. Two double quotation marks together within a quoted field can be used to denote a double quotation mark. A trailing comma will produce an error.

For a list of possible values for the lflags parameter, see the GetListFlags method.

Rows with duplicate e-mail addresses in the file are ignored.

The parameter, pvarOpID, contains valid data only if the creation operation is performed asynchronously.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ListManager Object

IListManager::GetListFlags


IListManager::CreateFromSegment

Use this method to create a list from a Predictor resource segment.

Definition

HRESULT IListManager::CreateFromSegment(
BSTR listName,
BSTR listDesc,
long lFlags,
long userFlags,
BSTR modelName,
BSTR segmentName,
BSTR predHostName,
BSTR DWConnStr,
double fpMinProbability,
BOOL bAsync,
VARIANT* pvarOpID,
VARIANT* pvarID
);

Parameters

listName

[in] A BSTR that provides the name for the list.

listDesc

[in] A BSTR that contains the list description.

lFlags

[in] A long that specifies the bitmask flags that control the type of list created.

userFlags

[in] A long that contains application specific user flags. Not used by the ListManager object.

modelName

[in] A BSTR that contains the name of the Predictor segment model to use.

segmentName

[in] A BSTR that contains the name of the segment to import.

predHostName

[in] A BSTR that contains the name of the Predictor host server.

DWConnStr

[in] A BSTR that contains the Data Warehouse connection string.

fpMinProbability

[in] A double that contains the minimum probability associated with a given segment member for that member to be included in the list.

bAsync

[in] A BOOL that specifies whether the creation operation is performed synchronously or asynchronously. A value of True indicates asynchronous processing.

pvarOpID

[out, optional] A pointer to a VARIANT used to return an Operation ID.

pvarID

[out, retval] A pointer to a VARIANT used to return the new list ID.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_LM_CONNECTIONFAILED | 0x8C400001 | Failed to establish database connection.
E_LM_CREATE_OBJECT | 0x8C400017 | Unable to create the object.
E_LM_INVALID_FLAGS | 0x8C400005 | Invalid flags value.
E_LM_LIST_ALREADY_EXISTS | 0x8C400007 | The specified list has already been created.
E_LM_MAILABLE_LIST_NO_EMAILS | 0x8C40000D | The list is designated as a Mailable list but does not contain an rcp_email column.
E_LM_OPER_CANCELED | 0x8C40000B | The operation was canceled.
E_LM_SQLERROR | 0x8C400003 | Error while executing SQL/ADO operation.
E_LM_USER_LIST_NO_GUIDS | 0x8C40000E | The list is designated as a User list but does not contain an rcp_guid column.
OLE_E_BLANK | 0x80040007 | The ListManager object has not been properly initialized.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

This method calls into the PredictorServiceSiteAdmin object, passing it the modelName, segmentName, and fpMinProbability parameters along with a connection string to the database used by the ListManager object, and the table name that it should create.

For a list of possible values for the lflags parameter, see the GetListFlags method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ListManager Object

IListManager::GetListFlags


IListManager::CreateFromSql

Use this method to create a list from a SQL query.

Definition

HRESULT IListManager::CreateFromSql(
BSTR listName,
BSTR listDesc,
long lFlags,
long userFlags,
BSTR connStr,
BSTR queryStr,
long errLimit,
BOOL bAsync,
VARIANT* pvarOpID,
VARIANT* pvarID
);

Parameters

listName

[in] A BSTR that provides the name for the list.

listDesc

[in] A BSTR that provides a description for the list.

lFlags

[in] A long that specifies the bitmask flags that control the type of list created.

userFlags

[in] A long that contains application specific user flags. Not used by the ListManager object.

connStr

[in] A BSTR that contains the connection string for the SQL Server database.

queryStr

[in] A BSTR that contains the SQL query for retrieving the contents of the new list.

errLimit

[in] A long that is not used.

bAsync

[in] A BOOL that specifies whether the creation operation is performed synchronously or asynchronously. A value of True indicates asynchronous processing.

pvarOpID

[out, optional] A pointer to a VARIANT used to return an Operation ID.

pvarID

[out, retval] A pointer to a VARIANT used to return the ID of the new list.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_LM_CONNECTIONFAILED | 0x8C400001 | Failed to establish database connection.
E_LM_INVALID_FLAGS | 0x8C400005 | Invalid flags value.
E_LM_LIST_ALREADY_EXISTS | 0x8C400007 | The specified list has already been created.
E_LM_MAILABLE_LIST_NO_EMAILS | 0x8C40000D | The list is designated as a Mailable list but does not contain an rcp_email column.
E_LM_OPER_CANCELED | 0x8C40000B | The operation was canceled.
E_LM_SQLERROR | 0x8C400003 | Error while executing SQL/ADO operation.
E_LM_USER_LIST_NO_GUIDS | 0x8C40000E | The list is designated as a User list but does not contain an rcp_guid column.
OLE_E_BLANK | 0x80040007 | The ListManager object has not been properly initialized.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

It is recommended to use the MSDASQL (ODBC) OLEDB provider with this method.

The CreateFromSQL method uses the T-SQL OpenRowset command to run the query against the database. Therefore, any ODBC data source may be specified with the following restriction:

If the SQLOLEDB provider is used, any object names used in the query must be fully qualified. For example, on SQL Server 7.0 databases, use "SELECT * FROM database.dbo.tablename" instead of "SELECT * FROM tablename".

For a list of possible values for the lflags parameter, see the GetListFlags method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ListManager Object

IListManager::GetListFlags


IListManager::Delete

Use this method to delete a list.

Definition

HRESULT IListManager::Delete(
VARIANT listID
);

Parameters

listID

[in] A VARIANT that specifies the ID or name of the list to be deleted.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_LM_LIST_BUSY | 0x8C400008 | The specified list is currently busy with another operation.
E_LM_LIST_NOT_FOUND | 0x8C400006 | The specified list does not exist.
E_LM_SQLERROR | 0x8C400003 | Error while executing SQL/ADO operation.
OLE_E_BLANK | 0x80040007 | The ListManager object has not been properly initialized.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

To be deleted, a list cannot be busy with any operation.

The list data is also deleted.

See Also

ListManager Object


IListManager::ExportToFile

Use this method to export a Mailing list to a text file.

Definition

HRESULT IListManager::ExportToFile(
VARIANT listID,
BSTR fileName,
BOOL bUnicode,
BOOL bOverwrite,
BOOL bAsync,
VARIANT* pvarOpID
);

Parameters

listID

[in] A VARIANT that contains the ID or name of the list to be exported.

fileName

[in] A BSTR that contains the name of the file.

bUnicode

[in] A BOOL that specifies the character format of the export file. A value of True indicates that Unicode characters should be used. A value of False indicates that the current system codepage character set should be used.

bOverwrite

[in] A BOOL that specifies whether to overwrite the data in the export file, if it exists. A value of True indicates that the data should be overwritten. A value of False causes the method to fail if the file exists.

bAsync

[in] A BOOL that specifies whether the creation operation is performed synchronously or asynchronously. A value of True indicates asynchronous processing.

pvarOpID

[out, optional] A pointer to a VARIANT used to return an Operation ID.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_LM_BAD_FILE_PATH | 0x8C40000A | The specified file path is not valid.
E_LM_FILE_ACCESS_DENIED | 0x8C400009 | The ListManager service does not have permission to open the specified file.Check the permissions for the ListManager service account against the permissions for the file.
E_LM_FILE_ALREADY_EXISTS | 0x8C400010 | The specified file cannot be created because it already exists.
E_LM_FILESHARE_NOT_FOUND | 0x8C400016 | The network share does not exist and a full path was not specified for the file.
E_LM_LIST_BUSY | 0x8C400008 | The specified list is currently busy with another operation.
E_LM_LIST_IN_FAILED_STATE | 0x8C40001D | The specified list is in a FAILED state and may not be used for the operation.
E_LM_LIST_NOT_FOUND | 0x8C400006 | The specified list does not exist.
E_LM_MAILABLE_REQUIRED | 0x8C400011 | The operation requires a mailable list and the specified list is not a mailable list.
E_LM_OPER_CANCELED | 0x8C40000B | The operation was canceled.
E_LM_SQLERROR | 0x8C400003 | Error while executing SQL/ADO operation.
OLE_E_BLANK | 0x80040007 | The ListManager object has not been properly initialized.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

If the list is a Mailable list but not a Mailing list, a temporary Mailing list is created and then exported.

If an absolute file path and name are not specified, ListManager exports the file relative to a root folder named CommerceLists on the local computer running the ListManager resource. If the folder does not exist, an error is returned.

ListManager exports the file in the following format. The is Message Format field is an integer, all other fields are strings and enclosed in double quotation marks.

   <Mail-to address>,<User ID>,<Message Format>,<Locale>,
   <Source URL><cr><lf>

The parameter pvarOpID contains valid data only if the export operation is performed asynchronously.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ListManager Object


IListManager::ExportToSql

Use this method to export a list to the specified table in a Microsoft SQL Server database. This operation can be performed synchronously or asynchronously.

Definition

HRESULT IListManager::ExportToSql(
VARIANT listID,
BSTR connStr,
BSTR resTable,
BOOL bOverwrite,
long lOptions,
BOOL bAsync,
VARIANT* pvarOpID
);

Parameters

listID

[in] A VARIANT that contains the ID or name of the list to be exported.

connStr

[in] A BSTR that contains the connection string for the SQL Server database.

resTable

[in] A BSTR that contains the name of the table into which the list will be exported.

bOverwrite

[in] A BOOL that specifies whether to overwrite the data if the table already exists. A value of True indicates that the data should be overwritten. A value of False produces an error if the tables already exist.

lOptions

[in] A long that specifies the export options for use by the Direct Mail resource. Other applications should generally pass the value zero (0). A value of one (1) causes special action to be taken. See the Remarks section below.

bAsync

[in] A BOOL that specifies whether the creation operation is performed synchronously or asynchronously. A value of True indicates asynchronous processing. A value of False indicates synchronous processing.

pvarOpID

[out, optional] A pointer to a VARIANT used to return an Operation ID. This Operation ID is used in subsequent processing concerning this operation.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_LM_CONNECTIONFAILED | 0x8C400001 | Failed to establish database connection.
E_LM_LIST_BUSY | 0x8C400008 | The specified list is currently busy with another operation.
E_LM_LIST_IN_FAILED_STATE | 0x8C40001D | The specified list is in a FAILED state and may not be used for the operation.
E_LM_LIST_NOT_FOUND | 0x8C400006 | The specified list does not exist.
E_LM_OPER_CANCELED | 0x8C40000B | The operation was canceled.
E_LM_SQLERROR | 0x8C400003 | Error while executing SQL/ADO operation.
E_LM_TABLE_ALREADY_EXISTS | 0x8C40000F | The specified table cannot be created because it already exists.
OLE_E_BLANK | 0x80040007 | The ListManager object has not been properly initialized.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

An existing table is expected to have the same format as the exported list. If the table does not exist, it will be created.

The ExportToSQL method works by opening a connection on the destination SQL Server database and executing the T-SQL OpenRowset command to select data from the List Manager database. Because of this, some special caveats apply:

  • The destination database must have the Bulk Copy/Select Into option selected.

  • If the List Manager was initialized with a connection string containing a DSN then the SQL server computer hosting the destination database must also have the DSN configured.

  • Unlike the CreateFromSQL command, ODBC data sources other than SQL Server 7.0 or greater are not supported.

The parameter pvarOpID contains valid data only if the export operation is performed asynchronously.

The lOptions parameter specifies whether the exported list is intended for use with Direct Mailer, controlling how it is processed during the export. The following table shows the legal values of the IOptions parameter.

lOptions value | Description
0 | Do not do any special processing for Direct Mailer.
1 | Export the list for use with Direct Mailer. The list must be a Mailable list or an error is returned. If the list is not a mailing list, it is converted to one.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ListManager Object

IListManager::ExtractMailingList


IListManager::ExtractMailingList

Use this method to create a new mailing list from a generic list.

Definition

HRESULT IListManager::ExtractMailingList(
VARIANT srcList,
BSTR reslistName,
BSTR reslistDesc,
long userFlags,
BOOL bAsync,
VARIANT* pvarOpID,
VARIANT* pvarID
);

Parameters

srcList

[in] A VARIANT that contains the ID or name of the generic source list.

reslistName

[in] A BSTR that contains the new mailing list name.

reslistDesc

[in] A BSTR that contains the description of the new mailing list.

userFlags

[in] A long that contains application specific user flags. Not used by the ListManager object.

bAsync

[in] A BOOL that specifies whether the export operation is performed synchronously or asynchronously. A value of True indicates asynchronous processing.

pvarOpID

[out, optional] A pointer to a VARIANT used to return an Operation ID.

pvarID

[out, retval] A pointer to a VARIANT used to return the ID of the new list.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_LM_LIST_ALREADY_EXISTS | 0x8C400007 | The specified list has already been created.
E_LM_LIST_BUSY | 0x8C400008 | The specified list is currently busy with another operation.
E_LM_LIST_IN_FAILED_STATE | 0x8C40001D | The specified list is in a FAILED state and may not be used for the operation.
E_LM_LIST_NOT_FOUND | 0x8C400006 | The specified list does not exist.
E_LM_MAILABLE_LIST_NO_EMAILS | 0x8C40000D | The list is designated as a Mailable list but does not contain an rcp_email column.
E_LM_MAILABLE_REQUIRED | 0x8C400011 | The operation requires a mailable list and the specified list is not a mailable list.
E_LM_OPER_CANCELED | 0x8C40000B | The operation was canceled.
E_LM_SQLERROR | 0x8C400003 | Error while executing SQL/ADO operation.
E_LM_USER_LIST_NO_GUIDS | 0x8C40000E | The list is designated as a User list but does not contain an rcp_guid column.
OLE_E_BLANK | 0x80040007 | The ListManager object has not been properly initialized.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The source list must be a Mailable list (contains an rcp_email column). Any duplicate e-mail addresses are removed in the result list.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ListManager Object


IListManager::GetListFlags

Use this method to retrieve the flags attribute for a list.

Definition

HRESULT IListManager::GetListFlags(
VARIANT listID,
long* plFlags
);

Parameters

listID

[in] A VARIANT that contains the ID or name of the list.

plFlags

[out, retval] A pointer to a long used to return the flags attribute.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_LM_LIST_NOT_FOUND | 0x8C400006 | The specified list does not exist.
E_LM_SQLERROR | 0x8C400003 | Error while executing SQL/ADO operation.
OLE_E_BLANK | 0x80040007 | The ListManager object has not been properly initialized.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The following table lists the possible flag parameter values used to determine the type of list created. Values may be OR'ed together to specify more than one flag.

Type | Value | Description
DEFAULT | 0x0 | A Mailing list
HIDDEN | 0x1 | The list should not be exposed in the user interface
DYNAMIC | 0x2 | A dynamic list
USER | 0x4 | A User list (contains an rcp_guid column)
GENERIC | 0x8 | A Generic list
MAILABLE | 0x10 | A Mailable list (contains an rcp_email column)

See Also

ListManager Object


IListManager::GetListId

Use this method to retrieve the ID of a list given the list name.

Definition

HRESULT IListManager::GetListId(
BSTR listName,
VARIANT* pvarID
);

Parameters

listName

[in] A BSTR that contains the list name.

pvarID

[out, retval] A pointer to a VARIANT used to return the ID (a GUID) of the list.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_LM_LIST_NOT_FOUND | 0x8C400006 | The specified list does not exist.
E_LM_SQLERROR | 0x8C400003 | Error while executing SQL/ADO operation.
OLE_E_BLANK | 0x80040007 | The ListManager object has not been properly initialized.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ListManager Object


IListManager::GetListName

Use this method to retrieve the name of a list given the list ID.

Definition

HRESULT IListManager::GetListName(
VARIANT listID,
BSTR* plistName
);

Parameters

listID

[in] A VARIANT that contains the list ID.

plistName

[out, retval] A pointer to a BSTR used to return the name of the list.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_LM_LIST_NOT_FOUND | 0x8C400006 | The specified list does not exist.
E_LM_SQLERROR | 0x8C400003 | Error while executing SQL/ADO operation.
OLE_E_BLANK | 0x80040007 | The ListManager object has not been properly initialized.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ListManager Object


IListManager::GetListProperty

Use this method to retrieve a property of a list.

Definition

HRESULT IListManager::GetListProperty(
VARIANT listID,
BSTR listPropertyName,
VARIANT* pvarListProp
);

Parameters

listID

[in] A VARIANT that contains the ID or name of the list.

listPropertyName

[in] A BSTR that contains the property name (column of the lm_master table).

pvarListProp

[out, retval] A pointer to a VARIANT used to return the value of the property.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_LM_LIST_NOT_FOUND | 0x8C400006 | The specified list does not exist.
E_LM_SQLERROR | 0x8C400003 | Error while executing SQL/ADO operation.
OLE_E_BLANK | 0x80040007 | The ListManager object has not been properly initialized.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For information about the available list properties, see IListManager::GetLists.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ListManager Object


IListManager::GetLists

Use this method to enumerate all lists known to the ListManager object.

Definition

HRESULT IListManager::GetLists(
IDispatch** ppRecSet
);

Parameters

ppRecSet

[out, retval] The address of a pointer to the IDispatch interface of an ADO Recordset object used to return the details of the lists known to this instance of the ListManager object.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

This method returns an instance of a read-only ADO Recordset object that contains a record for each list in the ListManager object database. The Recordset object does not contain any lists that are not completely created at the time this method is invoked.

If there are not any lists completely created at the time this method is invoked, the method returns successfully, but the Recordset object is empty.

The following table describes the fields returned in the Recordset object.

Field | Type | Description
list_id | uniqueidentifier | Identification number of the list.
list_name | NVARCHAR [64] | Name of the list.
list_created | datetime | Date/time the list record was created.
list_creation_type | smallint | Method used to create the list. Legal values are: 1 - CreateFromFile 2 - CreateFromSQL 3 - CreateFromDWCalc 4 - CreateFromSegment 5 - Other (subtraction, union, extraction, etc.)
list_description | NVARCHAR [256] | List description.
list_err_limit | long | The error threshold for the list.
list_flags | int | Bit flags for the list. Can bitwise OR together to specify more than one flag. Legal values are: 0x0 - DEFAULT 0x1 - HIDDEN 0x2 - DYNAMIC 0x4 - USER 0x8 - GENERIC 0x10 - MAILABLE
list_location | NVARCHAR [256] | Location (table name) where the list data is stored.
list_query | NVARCHAR [1024] | Query used to create the list.
list_recent_operid | NVARCHAR [128] | ID of the most recent list operation. May be Null if the list is a new list created by the CreateEmpty method.
list_size | int | Number of rows in the list (-1 for dynamic lists).
list_source | NVARCHAR [512] | Name of the file, connection string, or filename used to create the list.
list_status | int | Status of the list. Legal values are: 1 - ready for processing 2 - being processed; other operations are not permitted 3 - failed
list_unique_emails | int | Number of unique rcp_email values in the list (-1 for dynamic lists).
list_unique_guids | int | Number of unique rcp_guid values in the list (-1 for dynamic lists).
list_userflags | int | Application specific. Not used by the ListManager object.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ListManager Object


IListManager::GetListUserFlags

Use this method to retrieve the UserFlags attribute for a list.

Definition

HRESULT IListManager::GetListUserFlags(
VARIANT listID,
long* plUserFlags
);

Parameters

listID

[in] A VARIANT that contains the ID or name of the list.

plUserFlags

[out, retval] A pointer to a long used to return the UserFlags attribute.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_LM_LIST_NOT_FOUND | 0x8C400006 | The specified list does not exist.
E_LM_SQLERROR | 0x8C400003 | Error while executing SQL/ADO operation.
OLE_E_BLANK | 0x80040007 | The ListManager object has not been properly initialized.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The UserFlags attributes are for use by applications external to the List Manager. The List Manager merely stores the flags that were passed in at the time a list was created and does not interpret the UserFlags attributes value in any way.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ListManager Object


IListManager::GetOperationInfo

Use this method to retrieve a Recordset object containing columns describing the specified list operation.

Definition

HRESULT IListManager::GetOperationInfo(
VARIANT varOpID,
IDispatch** ppRecSet
);

Parameters

varOpID

[in] A VARIANT that contains the Operation ID.

ppRecSet

[out, retval] The address of a pointer to an IDispatch interface of a Recordset object used to return the operation information.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about the returned Recordset object, see IListManager::GetOperations.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ListManager Object


IListManager::GetOperations

Use this method to enumerate all operations known to the ListManager object.

Definition

HRESULT IListManager::GetOperations(
IDispatch** ppRecSet
);

Parameters

ppRecSet

[out, retval] The address of a pointer used to return the IDispatch interface of an ADO Recordset object used to return information about the operations known to this instance of the ListManager object.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

This method returns an instance of a read-only ADO Recordset object that contains a record for each operation in the ListManager object database. There is a record for every operation that has ever been run on lists currently in the database. When a list is deleted, all operations associated with that list are also deleted.

The following table describes the fields returned in the Recordset object.

Field | Type | Description
op_id | NVARCHAR[128] | A "token" that identifies the operation and can be passed to the CancelOperation method to terminate the operation.
op_desc | NVCHAR[256] | A user-friendly operation description.
op_error_code | int | HRESULT of last failure associated with the list.
op_error_desc | NVARCHAR[1024] | Description of the last failure associated with the list.
op_list_destination | Nvarchar(256) | List destination (Export type operations only).
op_list_id | uniqueidentifier | The list ID on which this operation is taking place.
op_list_id_a | uniqueidentifier | Additional column if the operation has multiple lists involved.
op_list_id_b | uniqueidentifier | Additional column if the operation has multiple lists involved.
op_list_param1 | int | Additional column which stores any extra parameters involved in the operation.
op_list_param2 | int | Additional column which stores any extra parameters involved in the operation.
op_list_table | nvarchar(256) | Tablename (ExportToSql type operations only).
op_progress | int | Unused.
op_status | smallint | Status of the operation. Legal values are: 0 - complete 1 - executing -1 - failed
op_time_end | datetime | Date/time the operation completed or was aborted.
op_time_start | datetime | Date/time the operation started.
op_type | int | The type of operation. Legal values are: 1 - CreateFromFile 2 - CreateFromSQL 3 - ExportToFile 4 - ExportToSQL 5 - Copy 6 - Subtract 7 - Union 8 - CreateFromDWCalc. 9 - CreateFromSegment 10 - ExtractMailingList 11 - Other (unclassified or temporary)

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ListManager Object

IListManager::CancelOperation


IListManager::Initialize

Use this method to initialize the ListManager object.

Definition

HRESULT IListManager::Initialize(
BSTR bstrConnStr,
);

Parameters

bstrConnStr

[in] A BSTR that contains the connection string for the database to which the List Manager will connect.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_LM_ALREADYINITIALIZED | 0x8C400002 | The ListManager object has already been initialized and may not be re-initialized.
E_LM_CONNECTIONFAILED | 0x8C400001 | Failed to establish database connection.
E_LM_SQLERROR | 0x8C400003 | Error while executing SQL/ADO operation.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

Initialize the ListManager object before calling any other ListManager object method or property.

Initializing connects the ListManager object to a database. If the database does not contain the tables and procedures required by the ListManager object, they are created.

A ListManager object can be connected to only one database. To connect to a different database, instantiate a new ListManager object.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ListManager Object

IListManager::ExportToSQL


IListManager::RemoveUserFromMailingList

Use this method to remove a user from a mailing list

Definition

HRESULT IListManager::RemoveUserFromMailingList(
VARIANT listID,
BSTR UserEmail
);

Parameters

listID

[in] A VARIANT that contains the ID or name of the list.

UserEmail

[in] A BSTR that contains the e-mail address of the user.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_LM_LIST_BUSY | 0x8C400008 | The specified list is currently busy with another operation.
E_LM_LIST_IN_FAILED_STATE | 0x8C40001D | The specified list is in a FAILED state and may not be used for the operation.
E_LM_LIST_NOT_FOUND | 0x8C400006 | The specified list does not exist.
E_LM_MAILABLE_LIST_NO_EMAILS | 0x8C40000D | The list is designated as a Mailable list but does not contain an rcp_email column.
E_LM_MUST_BE_STATIC | 0x8C400019 | The operation requires a static list and the specified list is dynamic.
E_LM_NOT_MAILING_LIST | 0x8C400018 | The operation requires a Mailing list and the specified list is not a mailing list.
E_LM_SQLERROR | 0x8C400003 | Error while executing SQL/ADO operation.
E_LM_USER_LIST_NO_GUIDS | 0x8C40000E | The list is designated as a User list but does not contain an rcp_guid column.
OLE_E_BLANK | 0x80040007 | The ListManager object has not been properly initialized.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ListManager Object


IListManager::Rename

Use this method to rename a list.

Definition

HRESULT IListManager::Rename(
VARIANT listID,
BSTR newListName
);

Parameters

listID

[in] A VARIANT that specifies the ID or name of the list to be renamed.

newListName

[in] A BSTR that contains the new name for the list.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_LM_LIST_ALREADY_EXISTS | 0x8C400007 | The specified list has already been created
E_LM_LIST_BUSY | 0x8C400008 | The specified list is currently busy with another operation.
E_LM_LIST_IN_FAILED_STATE | 0x8C40001D | The specified list is in a FAILED state and may not be used for the operation.
E_LM_LIST_NOT_FOUND | 0x8C400006 | The specified list does not exist.
E_LM_SQLERROR | 0x8C400003 | Error while executing SQL/ADO operation.
OLE_E_BLANK | 0x80040007 | The ListManager object has not been properly initialized.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The new name must not be the same as any existing list name.

See Also

ListManager Object


IListManager::SetDesc

Use this method to provide a new description for a list.

Definition

HRESULT IListManager::SetDesc(
VARIANT listID,
BSTR newListDesc
);

Parameters

listID

[in] A VARIANT that specifies the ID or name of the list.

newListDesc

[in] A BSTR that contains the description to be associated with the list.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_LM_LIST_BUSY | 0x8C400008 | The specified list is currently busy with another operation.
E_LM_LIST_IN_FAILED_STATE | 0x8C40001D | The specified list is in a FAILED state and may not be used for the operation.
E_LM_LIST_NOT_FOUND | 0x8C400006 | The specified list does not exist.
E_LM_SQLERROR | 0x8C400003 | Error while executing SQL/ADO operation.
OLE_E_BLANK | 0x80040007 | The ListManager object has not been properly initialized.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

See Also

ListManager Object


IListManager::SetListProperty

Use this method to set a property of a list.

Definition

HRESULT IListManager::SetListProperty(
VARIANT listID,
BSTR listPropertyName,
VARIANT ListProp
);

Parameters

listID

[in] A VARIANT that contains the ID or name of the list.

listPropertyName

[in] A BSTR that contains the property name (column of the lm_master table).

ListProp

[in] A VARIANT that contains the value to set the property.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_LM_LIST_BUSY | 0x8C400008 | The specified list is currently busy with another operation.
E_LM_LIST_IN_FAILED_STATE | 0x8C40001D | The specified list is in a FAILED state and may not be used for the operation.
E_LM_LIST_MUST_BE_DYNAMIC | 0x8C400012 | The operation requires a dynamic list and the specified list is not a dynamic list.
E_LM_LIST_NOT_FOUND | 0x8C400006 | The specified list does not exist.
E_LM_LISTPROP_NOT_UPDATEABLE | 0x8C400013 | The specified list property cannot be changed after the list has been created.
E_LM_SQLERROR | 0x8C400003 | Error while executing SQL/ADO operation.
OLE_E_BLANK | 0x80040007 | The ListManager object has not been properly initialized.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

This method is usually used to change properties of a dynamic list, such as the table name, connection string, or SQL query from which a dynamic list is created.

The following properties may be set by this method:

  • list_name

  • list_description

  • list_userflags

  • list_err_limit (dynamic lists only)

  • list_query (dynamic lists only)

  • list_source (dynamic lists only)

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ListManager Object


IListManager::get_Status

The Status property is a read-only Long that contains the ListManager object status.

Definition

Get method:

HRESULT IListManager::get_Status(
long* Status
);

Parameters

Status

[out, retval] A pointer to a long is used to return the ListManager object status.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The following table shows the valid status codes and their descriptions.

Status | Value | Description
LMSTATUS_NEW | 0 | The ListManager object has been created but is not yet initialized.
LMSTATUS_READY | 1 | The ListManager object has been created and successfully initialized.
LMSTATUS_ERROR | -1 | The ListManager object failed to initialize.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ListManager Object


IListManager::Subtract

Use this method to subtract one mailing list from another mailing list, placing the result in a third list.

Definition

HRESULT IListManager::Subtract(
VARIANT srcList,
VARIANT lessList,
VARIANT resList,
long errLimit,
BOOL bAsync,
VARIANT* pvarOpID
);

Parameters

srcList

[in] A VARIANT that contains the ID or name of the list from which elements will be subtracted.

lessList

[in] A VARIANT that contains the ID or name of the less list.

resList

[in] A VARIANT that contains the ID or name of the list into which the results of the subtraction operation will be placed.

errLimit

[in] A long that is not used.

bAsync

[in] A BOOL that specifies whether the copy operation is performed synchronously or asynchronously. A value of True indicates asynchronous processing. A value of False indicates synchronous processing.

pvarOpID

[out, optional] A pointer to a VARIANT used to return an Operation ID. This Operation ID is used in subsequent processing concerning this operation.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_LM_LIST_BUSY | 0x8C400008 | The specified list is currently busy with another operation.
E_LM_LIST_IN_FAILED_STATE | 0x8C40001D | The specified list is in a FAILED state and may not be used for the operation.
E_LM_LIST_NOT_FOUND | 0x8C400006 | The specified list does not exist.
E_LM_MAILABLE_REQUIRED | 0x8C400011 | The operation requires a mailable list and the specified list is not a mailable list.
E_LM_OPER_CANCELED | 0x8C40000B | The operation was canceled.
E_LM_SQLERROR | 0x8C400003 | Error while executing SQL/ADO operation.
OLE_E_BLANK | 0x80040007 | The ListManager object has not been properly initialized.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The result list must exist prior to calling the method, however, any data in the list will be overwritten.

This method keys on the rcp_email column and thus, both the source (srcList parameter) and less (lessList parameter) lists must be Mailable lists (LISTFLAG_MAILABLE set to True). Records from the source list that do not have duplicate e-mail addresses (rcp_email) in the less list are copied to the result (resList parameter) list. Any existing data in the result list is deleted.

The parameter pvarOpID contains valid data only if the subtraction operation is performed asynchronously.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ListManager Object


IListManager::Union

Use this method to produce a union of two mailing lists, placing the result in a third mailing list. A union is a combination of the two lists with any duplicates eliminated.

Definition

HRESULT IListManager::Union(
VARIANT srcList,
VARIANT addList,
VARIANT resList,
long errLimit,
BOOL bAsync,
VARIANT* pvarOpID
);

Parameters

srcList

[in] A VARIANT that contains the ID or name of the source list.

addList

[in] A VARIANT that contains the ID or name of the add list.

resList

[in] A VARIANT that contains the ID or name of the list into which the results of the union operation will be placed.

errLimit

[in] A long that is not used.

bAsync

[in] A BOOL that specifies whether the copy operation is performed synchronously or asynchronously. A value of True indicates asynchronous processing. A value of False indicates synchronous processing.

pvarOpID

[out, optional] A pointer to a VARIANT used to return an Operation ID. This Operation ID is used in subsequent processing concerning this operation.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_LM_LIST_BUSY | 0x8C400008 | The specified list is currently busy with another operation.
E_LM_LIST_IN_FAILED_STATE | 0x8C40001D | The specified list is in a FAILED state and may not be used for the operation.
E_LM_LIST_NOT_FOUND | 0x8C400006 | The specified list does not exist.
E_LM_MAILABLE_REQUIRED | 0x8C400011 | The operation requires a mailable list and the specified list is not a mailable list.
E_LM_OPER_CANCELED | 0x8C40000B | The operation was canceled.
E_LM_SQLERROR | 0x8C400003 | Error while executing SQL/ADO operation.
OLE_E_BLANK | 0x80040007 | The ListManager object has not been properly initialized.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The result list must exist prior to calling the method, however, any data in the list will be overwritten.

This method keys on the rcp_email column and thus, both the source (srcList parameter) and add (addList parameter) lists must be Mailable lists (LISTFLAG_MAILABLE set to True). All the records from the source list are copied to the result (resList parameter) list. All records from the add list that do not have duplicate e-mail addresses (rcp_email) in the source list are also copied to the result list. Any existing data in the result list is deleted.

The parameter pvarOpID contains valid data only if the union operation is performed asynchronously.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ListManager Object


IListManager::WaitOnOperation

Use this method to wait until an operation is complete or a specified time period has elapsed.

Definition

HRESULT IListManager::WaitOnOperation(
VARIANT varOpID,
unsigned long timeout
);

Parameters

varOpID

[in] A VARIANT that specifies the ID of the operation upon which to wait. For more information about where to obtain Operation IDs, see the Remarks section.

timeout

[in, optional] An unsigned long hat specifies a timeout. This method returns when either the specified operation completes, or when the number of seconds specified by the timeout parameter have elapsed, whichever happens first. A value of zero (the default) specifies an infinite time to wait for the operation to complete.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_LM_OPERATION_NOT_FOUND | 0x8C400004 | The operation ID does not represent a currently running operation.
E_LM_SQLERROR | 0x8C400003 | Error while executing SQL/ADO operation.
OLE_E_BLANK | 0x80040007 | The ListManager object has not been properly initialized.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

This method cannot be called from a scripting language such as VBScript or JScript on an ASP page. ASP pages must use alternative techniques when dealing with asynchronous operations and should never wait on them explicitly.

The Operation ID passed to this method in the varOpID parameter can be obtained from any of the following calls when they are executed asynchronously:

  • Copy

  • CreateFromDWCalc

  • CreateFromFile

  • CreateFromSql

  • ExportToFile

  • ExportToSql

  • Subtract

  • Union

In addition, the Operation IDs of all known operations can be retrieved using the GetOperations method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ListManager Object


LRUCache Object

Use this object to support the creation, storage, and retrieval of name/value pairs, referred to as elements, from a cache in memory. The LRUCache object functions similarly to the Dictionary object, except that it only stores a limited number of elements, and internally ranks them according to use. When the cache is full and a new element needs to be added, the least recently used element is removed from the cache to make room for the new element.

ProgID: | Commerce.LRUCache (Externally creatable)
COM Class Name: | LRUCache
COM Interface Name: | ILRUCache
Interface ID Constant: | IID_ILRUCache
Header File: | cacheint.h, mspu_guids.h
Type Library Name: | Microsoft Commerce 2000 Cache Manager Type Library
DLL Name: | mscscache.dll
Threading Model: | Both

In C++, use the ILRUCache interface to access the methods of the LRUCache object.

Because this object is primarily intended for use within ASP script, access from C++ will not be common.

The methods of the LRUCache object are shown in the following table.

Method | Description
Flush | Removes an element from the cache.
FlushAll | Removes all elements from the cache.
Insert | Inserts an element into the cache.
Lookup | Returns the value of an element in the cache when given the name of the element.
LookupObject | Returns an object in the cache when given the name of the object.
SetSize | Sets the maximum size of the cache.


ILRUCache::Flush

Use this method to remove the specified element from the cache.

Definition

HRESULT ILRUCache::Flush(
BSTR bstrKey
);

Parameters

bstrKey

[in, optional] A BSTR that contains the name of the element to be removed from the cache.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

If no element is specified, all elements are removed.

See Also

CacheManager Object

LRUCache Object


ILRUCache::FlushAll

Use this method to remove all elements from the cache.

Definition

HRESULT ILRUCache::FlushAll(
);

Parameters

None.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

See Also

CacheManager Object

LRUCache Object


ILRUCache::Insert

Use this method to add an element to the cache.

Definition

HRESULT ILRUCache::Insert(
BSTR bstrKey,
VARIANT* pvarValue
);

Parameters

bstrKey

[in] A BSTR that contains the name of the element to be added to the cache.

pvarValue

[in] A pointer to the VARIANT that contains the value of the element.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CacheManager Object

LRUCache Object


ILRUCache::Lookup

Use this method to retrieve the value of an element from the cache.

Definition

HRESULT ILRUCache::Lookup(
BSTR bstrKey,
VARIANT* pvarValue
);

Parameters

bstrKey

[in] A BSTR that contains the name of the element to be retrieved.

pvarValue

[out,retval] A pointer to a VARIANT used to return the value.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pvarValue parameter contains valid data only if the property was accessed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CacheManager Object

LRUCache Object


ILRUCache::LookupObject

Use this method to retrieve an object from the cache.

Definition

HRESULT ILRUCache::LookupObject(
BSTR bstrKey,
IDispatch** ppLRUCache
);

Parameters

bstrKey

[in] A BSTR that contains the name of the object to be retrieved.

ppLRUCache

[out,retval] The address of a pointer to the IDispatch interface of an object.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The ppLRUCache parameter contains valid data only if the property was accessed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

CacheManager Object

LRUCache Object


ILRUCache::SetSize

Use this method to set the maximum size of the cache.

Definition

HRESULT ILRUCache::SetSize(
long lSize
);

Parameters

lSize

[in] A long that specifies the size of the cache.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

See Also

CacheManager Object

LRUCache Object


MessageManager Object

Use this object to store error messages in multiple languages that the Order Processing pipeline (OPP) components use to describe error conditions generated during order processing.

ProgID: | Commerce.MessageManager (Externally creatable)
COM Class Name: | MSCSMessageManager_3_0
COM Interface Name: | IMSCSMessageManager_3_0
Interface ID Constant: | IID_IMSCSMessageManager_3_0
Header File: | commerce.h, mspu_guids.h
Type Library Name: | Commerce -- MSCSAspHelp Type Library
DLL Name: | MSCSAspHelp.dll
Threading Model: | Both

In C++, use the IMSCSMessageManager_3_0 interface to access the properties and methods of the MessageManager object.

Because this object is primarily intended for use within ASP script, access from C++ will not be common.

The single property of the MessageManager object is shown in the following table.

Property | Type | Description
defaultLanguage | BSTR | Specifies the default message set for the MessageManager. This property is read/write.

The methods of the MessageManager object are shown in the following table.

Method | Description
AddLanguage | Adds a new message set to the MessageManager object and associates that message set with a locale.
AddMessage | Adds a new message to the MessageManager object.
GetLocale | Returns the locale for the specified message set.
GetMessage | Returns the message associated with the specified message name constant.

See Also

Display Objects


IMSCSMessageManager_3_0::AddLanguage

Use this method to add a message set to the MessageManager, and associate that message set with a locale. In subsequent calls to MessageManager object methods, the caller needs to identify the message set name, not the locale.

Any number of message sets can be associated with a single locale.

Definition

HRESULT IMSCSMessageManager_3_0::AddLanguage(
BSTR bstrLanguage,
long Locale
);

Parameters

bstrLanguage

[in] A BSTR that contains the name for the message set to add to the MessageManager object.

Locale

[in] A long that uniquely identifies the locale to associate with the added message set.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

MessageManager Object

IMSCSMessageManager_3_0::get_DefaultLanguage, put_DefaultLanguage

IDataFunctions_4_0::get_Locale, put_Locale

IMSCSMessageManager_3_0::GetMessage


IMSCSMessageManager_3_0::AddMessage

Use this method to add a message to the MessageManager object.

Definition

HRESULT IMSCSMessageManager_3_0::AddMessage(
BSTR bstrName,
BSTR bstrMessage,
VARIANT vtLanguage
);

Parameters

bstrName

[in] A BSTR that contains the message name constant, which is a string that identifies the message to add. For a list of common messages and their constant names, see the Remarks section.

bstrMessage

[in] A BSTR that contains the text of the message to add.

vtLanguage

[in] A VARIANT that contains the language name with which to associate the message. This value, if specified, must be a language name added through a previous call to the AddLanguage method. If this parameter is not supplied, or is NULL, the language specified in the DefaultLanguage property of the MessageManager object is used.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The following table lists the messages that are used by the default implementation of the OPP, showing the message name constant expected by the Order Processing pipeline (OOP) components that use these messages.

Message name constant | Used by OPP component | Added to this collection under this condition
pur_badplacedprice | RequiredItemAdjustPrice | _Basket_Errors when the price of an item does not correspond to the price contained in the OrderForm.
pur_badhandling | RequiredHandling | _Purchase_Errors when the handling cost for an order cannot be computed
pur_badpayment | RequiredPayment | _Purchase_Errors when authentication code (_payment_auth_code) is not set
pur_badshipping | RequiredShipping | _Purchase_Errors when the shipping for an order cannot be computed
pur_badsku | RequiredProdInfo | _Basket_Errors when a stockkeeping unit (SKU) in the OrderForm references an item that is not contained in the inventory for the site
pur_badtax | RequiredTax | _Purchase_Errors when the tax on a purchase cannot be computed
pur_badverify | RequiredTotal | _Purchase_Errors when the data stored by the ProcessVerifyWith method does not match the original data in the order form
pur_noitems | RequiredOrderCheck | _Purchase_Errors when there are no items in the OrderForm.
pur_out_of_stock | FlagInventory, LocalInventory | _Purchase_Errors when an item referenced in the OrderForm is out of stock.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

MessageManager Object

IMSCSMessageManager_3_0::get_DefaultLanguage, put_DefaultLanguage

IMSCSMessageManager_3_0::GetMessage


IMSCSMessageManager_3_0::get_DefaultLanguage, put_DefaultLanguage

Use the DefaultLanguage property to specify the default message set for the MessageManager. When you use the GetMessage method, or use the AddMessage method to add messages to the MessageManager, without specifying a message set for those messages, then the messages are associated with the message set specified in this property.

Definition

Get method:

HRESULT IMSCSMessageManager_3_0::get_defaultLanguage(
BSTR* defaultLanguage
);

Put method:

HRESULT IMSCSMessageManager_3_0::put_defaultLanguage(
BSTR defaultLanguage
);

Parameters

defaultLanguage

[in] When putting the property, a BSTR that contains the default language.
[out, retval] When getting the property, a BSTR used to return the default language.

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The defaultLanguage parameter contains valid data only if the property is accessed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

MessageManager Object

IMSCSMessageManager_3_0::GetLocale


IMSCSMessageManager_3_0::GetLocale

Use this method to return a number that identifies the locale for the specified message set.

Definition

HRESULT IMSCSMessageManager_3_0::GetLocale(
VARIANT vtLanguage,
long* pLocale
);

Parameters

vtLanguage

[in] A VARIANT that contains the name of the message set for which you want to retrieve the locale. This message set must have been added to the MessageManager object through a previous call to the AddLanguage method.

pLocale

[out, retval] A pointer to a long used to identify the locale for the specified message set.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This property returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pLocale parameter points to valid data only if the method returns successfully.

Like the GetMessage method, the GetLocale method is usually not called from within a site. Instead, it is used by the pipeline component to retrieve the locale for a message that describes an error that the component has encountered.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

MessageManager Object

IMSCSMessageManager_3_0::GetMessage

IMSCSMessageManager_3_0::AddLanguage


IMSCSMessageManager_3_0::GetMessage

Use this method to return the text of the specified message.

Definition

HRESULT IMSCSMessageManager_3_0::GetMessage(
BSTR bstrName,
VARIANT vtLanguage,
BSTR* Message
);

Parameters

bstrName

[in] A BSTR that contains the message constant name of the message to return. This is the name associated with this message when it was added to the MessageManager object through a call to the AddMessage method.

vtLanguage

[in] A VARIANT that specifies the name of the message set to which the message text belongs. This string specifies a message set that was added to the MessageManager object through a previous call to the AddLanguage method. If this parameter is not specified, or is NULL, the message is returned for the message set identified by the DefaultLanguage property of the MessageManager object.

Message

[out, retval] A pointer to a BSTR used to return the text of the specified message.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The Message parameter points to valid data only if the method returns successfully.

The GetMessage method is seldom called from within a site. Instead, it is used by pipeline components to retrieve messages that describe errors that have occurred.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

MessageManager Object

IMSCSMessageManager_3_0::AddLanguage

IMSCSMessageManager_3_0::GetLocale


MicroPipe Object

Use this object to run a single pipeline component from an Active Server Page (ASP) file without using a pipeline configuration file (.pcf).

ProgID: | Commerce.MicroPipe (Externally creatable)
COM Class Name: | CMicroPipeline
COM Interface Name: | IMicroPipeline
Interface ID Constant: | None
Header File: | None
Type Library Name: | Microsoft Commerce 2000 MicroPipe Type Library
DLL Name: | micropipe.dll
Threading Model: | Both

In C++, use the IMicroPipeline interface to access the properties and methods of the MicroPipe object.

Because this object is primarily intended for use within ASP script, access from C++ will not be common.

The methods of the MicroPipe object are shown in the following table.

Method | Description
Execute | Runs the component indicated in the SetComponent method.
SetComponent | Indicates the pipeline component to load and execute.
SetLogFile | Identifies the file in which to log pipeline events.

Remarks

The MicroPipe object does not explicitly use Microsoft Transaction Server (MTS). To use transactions, mark the page as transacted or use the standard MtsTxPipline object. Distributed transactions have no meaning in the MicroPipe object because the object contains a single component.

Many pipeline components use configuration information in addition to the Context and Order dictionaries. Two common ways of passing this information to the component are:

  • To create a dictionary and pass the dictionary to the component.

  • To set individual or multiple properties directly.

The first method applies only to pipeline components that implement the IPipelineComponentAdmin interface. The second is common for components written in Microsoft Visual Basic, which usually do not implement the IPipelineComponentAdmin interface.

See Also

Pipeline Objects


IMicroPipeline::Execute

Use this method to run the pipeline component specified by the SetComponent method.

Definition

HRESULT IMicroPipeline::Execute(
IDispatch* pdispOrder,
IDispatch* pdispContext,
long lFlags,
long* pErrorLevel
);

Parameters

pdispOrder

[in] A pointer to the IDispatch interface of a Dictionary object. The Dictionary object is the Order dictionary that the pipeline component will run.

pdispContext

[in] A pointer to the IDispatch interface of a Dictionary object. The Context dictionary for the pipeline component to be run.

lFlags

[in] A long integer. Reserved for future use. Must be set to zero (0).

pErrorLevel

[out,retval] A pointer to a long that returns the error level.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns the message S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

In addition, the pErrorLevel parameter is set to one of the following three values:

Value | Description
1 | The pipeline component ran successfully.
2 | The pipeline component raised a warning. Generally, these are basket or user errors that would be reported to the user through the ASP page.
3 | The pipeline component failed to run.

Remarks

The pErrorLevel parameter points to valid data only if the method completes successfully.

Be sure to release the IMicroPipeline interface when finished.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

MicroPipe Object

IMicroPipeline::SetComponent

IMicroPipeline::SetLogFile


IMicroPipeline::SetComponent

Use this method to specify the pipeline component to run.

Definition

HRESULT IMicroPipeline::SetComponent(
IDispatch* pdispComponent
);

Parameters

pdispComponent

[in] A pointer to the IDispatch interface of the pipeline component to be run.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

A single MicroPipe object can be used to execute multiple components. Calling the SetComponent method on the MicroPipe object after setting and executing a different component earlier is permitted. In this case, the MicroPipe object releases the earlier component and sets up the new component in its place.

For more information about programming with pipeline objects, including code samples, see Pipeline Objects.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

MicroPipe Object

IMicroPipeline::Execute

IMicroPipeline::SetLogFile


IMicroPipeline::SetLogFile

Use this method to identify the file in which to log the operations of the pipeline component.

Definition

HRESULT IMicroPipeline::SetLogFile(
BSTR bstrFileName
);

Parameters

bstrFileName

[in] A BSTR containing the file name for logging.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

With logging, the MicroPipe object logs all of the read and write operations of the Dictionary and SimpleList objects. Errors are also recorded in the log. Because of the overhead involved, logging should be used only for debugging and should not be used in a production site.

The SetLogFile method should be called immediately before executing a pipeline. The SetLogFile method is exposed on the OrderGroup object as the LogFile property and should be called again before calling the RunPipe method.

For more information about programming with pipeline objects, including code samples, see Pipeline Objects.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

MicroPipe Object

IMicroPipeline::Execute

IMicroPipeline::SetComponent


MtsPipeline Object

Use this object to execute a non-transacted Microsoft Commerce Server 2000 pipeline. The pipeline may be an Order Processing pipeline (OPP).

ProgID: | Commerce.MtsPipeline (Externally creatable)
COM Class Name: | CMtsPipeline
COM Interface Name: | IPipeline
Interface ID Constant: | IID_IPipeline
Header File: | pipeline.h, mspu_guids.h
Type Library Name: | Microsoft Commerce 2000 Order Pipeline Type Library
DLL Name: | pipeline.dll
Threading Model: | Apartment

In C++, use the IPipeline interface to access the properties and methods of the MtsPipeline object.

Because this object is primarily intended for use within ASP script, access from C++ will not be common.

The methods of the MtsPipeline object are shown in the following table.

Method | Description
Execute | Runs the components in the pipeline.
LoadPipe | Loads a pipeline configuration file (.pcf) into the pipeline.
SetLogFile | Identifies the file in which to log pipeline events.

Remarks

The MtsPipeline object is registered under Microsoft Transaction Server (MTS) as "transactions not supported." Use this pipeline where transactions are not needed. For more information about transactions and pipelines, see Pipeline Basics.

The MtsPipeline is usually created on each page in which it is used.

The MtsPipeline is not a pooled pipeline. For more information about pooled pipelines, see About Pooled Pipelines.


IPipeline::Execute

Use this method to run the stages in the pipeline configuration file, which was previously specified by the LoadPipe method.

Definition

HRESULT IPipeline::Execute(
long lMode,
IDispatch* pdispOrder,
IDispatch* pdispContext,
long lFlags,
long* pErrorLevel
);

Parameters

lMode

[in] A long integer indicating the mode in which to run the pipeline. This parameter is provided only for backward compatibility with Site Server 3.0 Commerce Edition sites. In Site Server 3.0 Commerce Edition and later, the mode is set by loading an appropriately configured pipeline with the LoadPipe method. Use a value of one (1). A value of zero (0) prevents any stages from running.

pdispOrder

[in] A pointer to the IDispatch interface of a Dictionary object, usually an OrderForm object. The Order dictionary that will be used by the pipeline.

pdispContext

[in] A pointer to the IDispatch interface of a Dictionary object. The Context dictionary that will be used by the pipeline.

lFlags

[in] An unused long integer parameter. Must be set to zero (0).

pErrorLevel

[out,retval] A pointer to a long that returns the error level.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

In addition, the pErrorLevel parameter is set to one of the following three values:

Value | Description
1 | The pipeline ran successfully.
2 | A pipeline component raised a warning. Generally, these are basket or user errors that would be reported to the user through the ASP page.
3 | A pipeline component failed to run.

Remarks

The pErrorLevel parameter points to valid data only if the method completes successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

MtsPipeline Object

IPipeline::LoadPipe

IPipeline::SetLogFile

PooledPipeline Object


IPipeline::LoadPipe

Use this method to load a pipeline configuration file (.pcf) into the pipeline.

Definition

HRESULT IPipeline::LoadPipe(
BSTR pszFileName
);

Parameters

pszFileName

[in] A BSTR containing the pipeline configuration file name.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The LoadPipe method must be called to initialize all pipelines.

The LoadPipe method fails if you attempt to load a pipeline configuration file designated for transactions (for use in the MtsTxPipeline object).

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

MtsPipeline Object

IPipeline::Execute

IPipeline::SetLogFile

PooledPipeline Object


IPipeline::SetLogFile

Use this method to identify the file in which to log the operations of the pipeline component.

Note

  • This method is for use by developers who want to analyze pipeline configuration file information. Logging should never be used in a production environment: it degrades performance and may compromise the security of credit card numbers in non-set transactions.

Definition

HRESULT IPipeline::SetLogFile(
BSTR pszFileName
);

Parameters

pszFileName

[in] A BSTR containing the name of the file in which to log events.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

When logging is set, the pipeline logs the pipeline components that are called and the error values each component returns. The pipeline also logs all Dictionary and SimpleList object read and write operations.

Calling the method with an empty string turns off logging.

The SetLogFile method should be called immediately before executing a pipeline. The SetLogFile method is exposed on the OrderGroup object as the LogFile property and should be set before calling the RunPipe method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

MtsPipeline Object

IPipeline::Execute

IPipeline::LoadPipe

PooledPipeline Object


MtsTxPipeline Object

Use this object to execute a transacted Microsoft Commerce Server 2000 pipeline configuration. The pipeline may be an Order Processing pipeline (OPP).

ProgID: | Commerce.MtsTxPipeline (Externally creatable)
COM Class Name: | CTxPipeline
COM Interface Name: | IPipeline
Interface ID Constant: | IID_IPipeline
Header File: | pipeline.h, mspu_guids.h
Type Library Name: | Microsoft Commerce 2000 Order Pipeline Type Library
DLL Name: | pipeline.dll
Threading Model: | Apartment

In C++, use the IPipeline interface to access the properties and methods of the MtsTxPipeline object.

Because this object is primarily intended for use within ASP script, access from C++ will not be common.

The methods of the MtsTxPipeline object are shown in the following table.

Method | Description
Execute | Runs the components in the pipeline.
LoadPipe | Loads a pipeline configuration file (.pcf) into the pipeline.
SetLogFile | Identifies the file in which to log pipeline events.

Remarks

The MtsTxPipeline is usually created on each page in which it is used.

The MtsTxPipeline object is registered under Microsoft Transaction Server (MTS) as "transactions required." This object holds a transaction that spans all components in the pipeline configuration. For more information about transactions and pipelines, see Pipeline Basics.

When used with a database, the MtsTxPipeline object requires an ODBC-compliant database that supports MTS.

The Microsoft Distributed Transaction Coordinator (MSDTC) service must be running in order to use the MtsTxPipeline object.

To verify that the Distributed Transaction Coordinator service is running

  1. Click Start, point to Programs, point to Administrative Tools, and then click Services.

  2. Scroll to Distributed Transaction Coordinator and verify that the Status is Started.


IPipeline::Execute

Use this method to run the stages in the pipeline configuration file, which was previously specified by the LoadPipe method.

Definition

HRESULT IPipeline::Execute(
long lMode,
IDispatch* pdispOrder,
IDispatch* pdispContext,
long lFlags,
long* pErrorLevel
);

Parameters

lMode

[in] A long integer indicating the mode in which to run the pipeline. This parameter is provided only for backward compatibility with Site Server 3.0 Commerce Edition sites. In Site Server 3.0 Commerce Edition and later, the mode is set by loading an appropriately configured pipeline with LoadPipe. Use a value of one (1). A value of zero (0) prevents any stages from running.

pdispOrder

[in] A pointer to the IDispatch interface of a Dictionary object. The Order dictionary that will be used by the pipeline, usually an OrderForm object.

pdispContext

[in] A pointer to the IDispatch interface of a Dictionary object. The Context dictionary that will be used by the pipeline.

lFlags

[in] An unused long integer parameter. Must be set to zero (0).

pErrorLevel

[out,retval] A pointer to a long that returns the error level.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. For more details, see the Error Values section.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

In addition, the pErrorLevel parameter is set to one of the following three values:

Value | Description
1 | The pipeline ran successfully.
2 | A pipeline component raised a warning. Generally, these are basket or user errors that would be reported to the user through the ASP page.
3 | A pipeline component failed to run.

Remarks

The pErrorLevel parameter points to valid data only if the method completed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

MtsTxPipeline Object

IPipeline::LoadPipe

IPipeline::SetLogFile


IPipeline::LoadPipe

Use this method to load a pipeline configuration file (.pcf) into the pipeline.

Definition

HRESULT IPipeline::LoadPipe(
BSTR pszFileName
);

Parameters

pszFileName

[in] A BSTR containing the pipeline configuration file (.pcf) name.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The LoadPipe method must be called to initialize all pipelines.

The LoadPipe method fails if you attempt to load a configuration file designated for non-transacted pipelines.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

MtsTxPipeline Object

IPipeline::Execute

IPipeline::SetLogFile


IPipeline::SetLogFile

Use this method to identify the file in which to log the operations of the pipeline component.

Note

  • This method is for use by developers who want to analyze pipeline configuration file information. Logging should never be used in a production environment: it degrades performance and may compromise the security of credit card numbers in non-set transactions.

Definition

HRESULT IPipeline::SetLogFile(
BSTR pszFileName
);

Parameters

pszFileName

[in] A BSTR containing the name of the file in which to log events.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

When logging is set, the pipeline logs the pipeline components that are called and the error values each component returns. The pipeline also logs all Dictionary and SimpleList object read and write operations.

Calling this method with an empty string turns off logging.

The SetLogFile method should be called immediately before executing a pipeline. The SetLogFile method is also exposed on the OrderGroup object as the LogFile property and should be called before calling its RunPipe method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

MtsTxPipeline Object

IPipeline::LoadPipe

IPipeline::Execute


OrderForm Object

The OrderForm object provides for the in-memory storage of user and purchase information. Commerce Server 2000 sites use the OrderForm object to store the items that a user has chosen to purchase, and to store receipt information that reflects the purchase history for a given user.

ProgID: | Commerce.OrderForm (Externally creatable)
COM Class Name: | COrderForm
COM Interface Name: | IOrderForm
Interface ID Constant: | IID_IOrderForm
Header File: | commerce.h, mspu_guids.h
Type Library Name: | Microsoft Commerce 2000 Core Components Type Library
DLL Name: | MscsCore.dll
Threading Model: | Both

In C++, use the IOrderForm interface to access the properties and methods of the OrderForm object.

The methods of the OrderForm object are shown in the following table.

Method | Description
AddItem | Adds the specified item to the items collection of the object.
ClearItems | Clears the items collection of the object.
ClearOrderForm | Clears the entire OrderForm object.

Remarks

The OrderForm object is defined internally as a structured group of SimpleList and Dictionary objects, and includes the methods required to add items, clear items, and clear the entire OrderForm object itself.

The base of the OrderForm object is a Dictionary object, which contains information that describes the entire order. This includes user information, such as the shopper ID, name, and address, as well as order cost information, such as purchase subtotal, tax, shipping, and total.

The OrderForm object does not directly support storage of its data on disk. The DBStorage and OrderGroupManager objects enable persistent storage of OrderForm object data.

A number of the elements in the base Dictionary object of the OrderForm object include underscore (_) characters. The appearance of an underscore character in an element name indicates that these items are not saved to the OrderForm storage for the site. These elements are saved instead to the receipt storage of the site when the purchase is finalized.

See Also

Business Process Objects

OrderGroup Object

OrderGroupManager Object

SimpleFindSearchInfo Object

SimpleFindResultInfo Object


IOrderForm::AddItem

Use this method to add the specified item to the items collection of an OrderForm object. The items collection is a SimpleList object containing Dictionary objects.

Definition

HRESULT IOrderForm::AddItem(
VARIANT varSKU,
long lCount,
long lPlacedPrice,
IDispatch** ppdispItem
);

Parameters

varSKU

[in] A VARIANT that contains the stockkeeping unit (SKU) of the item to add.

lCount

[in] A long that contains the item count.

lPlacedPrice

[in] A long that contains the placed price of the item.

ppdispItem

[out, retval] The address of a pointer to receive an IDispatch interface to the Dictionary object used to return the added item; if the method does not complete successfully, this parameter will be NULL.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The ppdispItem parameter contains valid data only if the method returns successfully; otherwise, it returns NULL.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

OrderForm Object

IOrderForm::ClearItems

IOrderForm::ClearOrderForm


IOrderForm::ClearItems

Use this method to clear the items collection of the OrderForm object.

Definition

HRESULT IOrderForm::ClearItems(
);

Parameters

None.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This property returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

A site uses the ClearItems method to respond to a user choosing to cancel a purchase. This method affects only the information in the items collection. Other OrderForm object information, such as _oadjust_subtotal and _total_total, is modified only if you run the Order Processing Pipeline (OPP) on this OrderForm object.

To empty the entire contents of the OrderForm object, call the ClearOrderForm method.

See Also

OrderForm Object

IOrderForm::AddItem

IOrderForm::ClearOrderForm


IOrderForm::ClearOrderForm

Use this method to clear the entire OrderForm object.

Definition

HRESULT IOrderForm::ClearOrderForm(
);

Parameters

None.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

See Also

OrderForm Object

IOrderForm::AddItem

IOrderForm::ClearItems


OrderGroup Object

The OrderGroup object is used in Commerce Server 2000 to store, access, and compute basket and order information for a site. The OrderGroupManager object works in conjunction with the OrderGroup object, providing search and other management operations for orders.

ProgID: | Commerce.OrderGroup (Externally creatable)
COM Class Name: | OrderGroup
COM Interface Name: | _OrderGroup
Interface ID Constant: | None
Header File: | None
Type Library Name: | Microsoft Commerce 2000 OrderGroup Type Library
DLL Name: | requisition.dll
Threading Model: | Apartment

The properties of the OrderGroup object are shown in the following table.

Property | Type | Description
LogFile | BSTR | Log file name for pipeline runs. Allows pipeline logging when set to a non-empty string. This property is read/write.
SavePrefix | BSTR | Specifies a key prefix that will prevent a dictionary entry from being saved to the database.
Value | VARIANT | Returns the OrderGroup object attributes.This property is read-only.

The methods of the OrderGroup object are shown in the following table.

Method | Description
AddItem | Adds an item to the specified OrderForm object.
AddItemsFromTemplate | Adds the line items associated with an on-disk OrderGroup template to the current OrderGroup object.
AddOrderform | Adds an OrderForm object with all of its contents to the OrderGroup object.
AddXMLAsOrderForm | Converts an XML string to an OrderForm object and adds it to the OrderGroup object.
AggregateOrderFormValues | Iterates across all OrderForm objects, computes a total of the specified key, then stores the total at the OrderGroup level.
Clear | Clears the OrderGroup object of all OrderForm objects.
GetAddress | Gets the specified address dictionary object.
GetItemInfo | Gets a reference to the line item dictionary from the specified OrderForm at the specified index.
GetOrderFormAsXML | Converts an OrderForm object into an XML string.
GetOrderFormValue | Gets the OrderForm value specified by the supplied OrderForm key.
Initialize | Initializes the OrderGroup object.
LoadBasket | Loads the basket for the current user from the database.
LoadOrder | Loads the specified OrderGroup from the database.
LoadTemplate | Loads the specified template from the database.
PurgeUnreferencedAddresses | Removes all addresses in the OrderGroup object that are not being referenced by any line item shipping address.
PutItemValue | Puts the specified values into the specified keys of the line item.
PutOrderFormValue | Puts the specified values into the specified keys of the OrderForm object.
RemoveItem | Removes a line item from the specified OrderForm object. The item index specified indicates which line item to remove.
RemoveOrderForm | Removes the specified OrderForm object from the OrderGroup object.
RunPipe | Runs the Pipeline Component File on each OrderForm object in the OrderGroup object.
SaveAsBasket | Saves the OrderGroup object to the database with a basket status.
SaveAsOrder | Saves the OrderGroup object to the database with an order status.
SaveAsTemplate | Saves the OrderGroup object to the database with a template status.
SetAddress | Sets the OrderGroup object address dictionary values as specified by the address dictionary object supplied.
SetAddressFromFields | Sets the OrderGroup object address dictionary values as specified by the fields object supplied.
SetShippingAddress | Sets the shipping address to that referenced by the database address ID supplied.

See Also

Business Process Objects

OrderGroupManager Object

OrderForm Object

SimpleFindSearchInfo Object

SimpleFindResultInfo Object


_OrderGroup::AddItem

Use this method to add a line item to the specified OrderForm object.

This method adds a line-item dictionary to the given OrderForm (the strOrderFormName parameter). If the strOrderFormName is not supplied, the parameter strOrderFormName defaults to "default"; if "default" does not exist, it is created. This method also increments the aggregated quantity total at the OrderGroup and OrderForm level.

Definition

HRESULT _OrderGroup::AddItem(
IDictionary* dictItem,
VARIANT strOrderFormName,
long* lpRetVal
);

Parameters

dictItem

[in] A pointer to the IDictionary interface that contains the line item information.

strOrderFormName

[in, optional] A VARIANT that specifies the name of the OrderForm to add the item to. Depending on how a site is structured, you may choose to specify the vendor name of the item as the strOrderFormName. (This will result in items from different vendors being added to different OrderForms.)

lpRetVal

[out, retval] A pointer to a long used to return the index at which the item was added.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The lpRetVal parameter points to valid data only if the method completed successfully.

Note

  • Each line item that is added should contain a quantity.

  • If you are using the QueryCatalogInfo component in your pipeline, you will also need:
    • product_catalog

    • product_id

    • product_variant_id (if this is a product variant)

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

OrderGroup Object

_OrderGroup::RemoveItem


_OrderGroup::AddItemsFromTemplate

Use this method to add the line items associated with an on-disk OrderGroup to the current OrderGroup object.

This method iterates across all the OrderForms in the specified template and adds them to the current OrderGroup. If the OrderForms being added already exist, the line items on the template OrderGroup are simply added. When non-existing OrderForms are encountered, the method will add the OrderForm in its entirety to the OrderGroup including OrderForm-level dictionary values.

The OrderGroup keeps a counter of total line items at OrderForm and OrderGroup levels. For the OrderGroup level, it keeps track of the number of line items in all the OrderForms. This value is held under the key "total_lineitems".

Definition

HRESULT _OrderGroup::AddItemsFromTemplate(
BSTR OrderGroupID
);

Parameters

OrderGroupID

[in] A BSTR that specifies the OrderGroup ID for the template.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

Note

  • It is the responsibility of the application to implement security. This method does not check that the user ID of the template is the same as the user ID specified in the initialization call.

This method also works on previously submitted orders and baskets, as well as OrderGroups with Template (Saved Order) status.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

OrderGroup Object


_OrderGroup::AddOrderform

Use this method to add an OrderForm with all of its contents to the OrderGroup object.

If the strOrderFormName is not supplied, it defaults to "default".

Definition

HRESULT _OrderGroup::AddOrderform(
IDictionary* orderform,
VARIANT strOrderFormName
);

Parameters

orderform

[in] A pointer to the IDictionary interface that contains the OrderForm object that will be added.

strOrderFormName

[in, optional] A VARIANT that specifies the OrderForm name.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

OrderGroup Object


_OrderGroup::AddXMLAsOrderForm

Use this method to add items previously saved as XML (by using the GetOrderformAsXML method) back into an OrderGroup.

Definition

HRESULT _OrderGroup::AddXMLAsOrderForm(
BSTR strXML,
long nXMLLocale,
VARIANT strOrderFormName
);

Parameters

strXML

[in] A BSTR that specifies the XML string containing the line items to add.

nXMLLocale

[in] A long that specifies the locale to use in the XML string conversion.

strOrderFormName

[in, optional] A VARIANT that specifies the OrderForm name to add.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

Note

  • Use of the DictionaryXMLTransforms object is recommended when exchanging XML via BizTalk Server. DictionaryXMLTransforms allows you to write out XML to a well-defined schema.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

OrderGroup Object

_OrderGroup::GetOrderFormAsXML


_OrderGroup::AggregateOrderFormValues

Use this method to iterate across all OrderForms, compute a total of the specified key, and store the total at the OrderGroup level.

Definition

HRESULT _OrderGroup::AggregateOrderFormValues(
BSTR strOrderFormKey,
BSTR strOrderGroupKey
);

Parameters

strOrderFormKey

[in] A BSTR that specifies the OrderForm key of the value to be aggregated.

strOrderGroupKey

[in] A BSTR that specifies the OrderGroup key of the value to which the aggregated total will be written.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

OrderGroup Object


_OrderGroup::Clear

Use this method to clear the OrderGroup object of all OrderForm objects and Address dictionaries.

Definition

HRESULT _OrderGroup::Clear(
);

Parameters

None.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

See Also

OrderGroup Object


_OrderGroup::GetAddress

Use this method to get the specified address Dictionary object.

Definition

HRESULT _OrderGroup::GetAddress(
BSTR strAddressId,
IDictionary** ppRetVal
);

Parameters

strAddressId

[in] A BSTR that specifies the address ID.

ppRetVal

[out, retval] The address of a pointer to receive an IDictionary interface, used to return the address dictionary. The return value will be set to NULL if the specified strAddressId is not found.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

If the specified address is found, this method returns a reference to that dictionary, otherwise it returns a Nothing object.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The ppRetVal parameter contains valid data only if the method completed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

OrderGroup Object


_OrderGroup::GetItemInfo

Use this method to get a reference to the line-item dictionary from the specified OrderForm at the specified index. If the strOrderFormName parameter is not supplied, it defaults to "default".

Definition

HRESULT _OrderGroup::GetItemInfo(
long nItemIndex,
VARIANT strOrderFormName,
IDictionary** ppRetVal
);

Parameters

nItemIndex

[in] A long that specifies the line-item index.

strOrderFormName

[in, optional] A VARIANT that specifies the OrderForm name.

ppRetVal

[out, retval] The address of a pointer to receive an IDictionary interface, used to return the line item information.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The ppRetVal parameter contains valid data only if the method completed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

OrderGroup Object


_OrderGroup::GetOrderFormAsXML

Use this method to convert an OrderForm object into an XML string.

Definition

HRESULT _OrderGroup::GetOrderFormAsXML(
BSTR nXMLLocale,
VARIANT strOrderFormName,
BSTR* pbstrRetVal
);

Parameters

nXMLLocale

[in] A BSTR that specifies the locale used in the XML string conversion.

strOrderFormName

[in, optional] A VARIANT that specifies the OrderForm.

pbstrRetVal

[out, retval] A pointer to a BSTR used to return the XML string.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pbstrRetVal parameter points to valid data only if the method completed successfully.

Note: Use of the DictionaryXMLTransforms object is recommended when exchanging XML via BizTalk Server. The DictionaryXMLTransforms object allows you to write out XML to a well-defined schema.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

OrderGroup Object

_OrderGroup::AddXMLAsOrderForm


_OrderGroup::GetOrderFormValue

Use this method to get an attribute from an OrderForm, based on a specified key.

Definition

HRESULT _OrderGroup::GetOrderFormValue(
BSTR strKey,
VARIANT strOrderFormName,
VARIANT* pvtRetVal
);

Parameters

strKey

[in] A BSTR that contains the key that specifies the attribute to get.

strOrderFormName

[in, optional] A VARIANT that specifies the OrderForm name.

pvtRetVal

[out, retval] A pointer to a VARIANT used to return the attribute.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pvtRetVal parameter points to valid data only if the method completed successfully.

If the strOrderformName parameter is not supplied, the strOrderFormName parameter defaults to "default".

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

OrderGroup Object


_OrderGroup::Initialize

Use this method to initialize the OrderGroup object.

Definition

HRESULT _OrderGroup::Initialize(
BSTR strConnectionString,
BSTR strUser ID
);

Parameters

strConnectionString

[in] A BSTR that contains the database connection string.

strUser ID

[in] A BSTR that specifies the user ID. All Commerce Server 2000 user ID values are GUIDs.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

Use this method to specify the connection string that the OrderGroup uses for its database operations. You also specify a user_id that the object will use as an OrderGroup_id when performing basket operations. This same user_id value will be stored in the g_User IDChangedBy field.

Note

  • If you are loading an OrderGroup on behalf of another user (for example as an administrator), you should specify the administrator user ID (or a placeholder user ID GUID which signifies administrative authority) so that g_UserDChangedBy is updated with the appropriate value when the OrderGroup is saved back to the database. If you wish to load an OrderGroup with a Basket status in the role of an administrator, you must specify strUser ID as the user ID of the user whose basket you wish to load. In this case g_User IDChangedBy will not be updated with an administrator user ID.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

OrderGroup Object


_OrderGroup::LoadBasket

Use this method to load the basket for the current user from the database. If the basket for the user id specified in the Initialize method cannot be found, this method initializes an empty in-memory basket.

Definition

HRESULT _OrderGroup::LoadBasket(
);

Parameters

None.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

See Also

OrderGroup Object

_OrderGroup::LoadOrder

_OrderGroup::LoadTemplate

_OrderGroup::SaveAsBasket


_OrderGroup::LoadOrder

Use this method to load an OrderGroup from disk. This method returns an error if the OrderGroup cannot be found.

Definition

HRESULT _OrderGroup::LoadOrder(
BSTR strOrderGroupID
);

Parameters

strOrderGroupID

[in] A BSTR that specifies the OrderGroupID of the OrderGroup to be loaded.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The LoadOrder method can be used to load any OrderGroup whose status does not equal basket or template.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

OrderGroup Object

_OrderGroup::LoadBasket

_OrderGroup::LoadTemplate

_OrderGroup::Initialize

_OrderGroup::SaveAsOrder


_OrderGroup::LoadTemplate

Use this method to load the specified template from the database.

Definition

HRESULT _OrderGroup::LoadTemplate(
BSTR strOrderGroupID
);

Parameters

strOrderGroupID

[in] A BSTR that specifies the OrderGroupID of the template to be loaded.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

See Also

OrderGroup Object

_OrderGroup::LoadOrder

_OrderGroup::LoadBasket

_OrderGroup::SaveAsTemplate


_OrderGroup::get_LogFile, put_LogFile

The LogFile property is a read/write String that specifies the file name used for pipeline logging during the execution of the RunPipe method.

Definition

Get method:

HRESULT _OrderGroup::get_LogFile(
BSTR* LogFile
);

Put method:

HRESULT _OrderGroup::put_LogFile(
BSTR LogFile
);

Parameters

LogFile

[in] When putting the property, a BSTR that contains the log file.
[out, retval] When getting the property, a pointer to a BSTR used to return the log file.

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The LogFile parameter contains valid data only if the property is accessed successfully.

Set the LogFile parameter to an empty string ("") to disable logging.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

OrderGroup Object


_OrderGroup::PurgeUnreferencedAddresses

Use this method to remove all addresses in the OrderGroup object that are not being referenced by any line-item shipping_address_id or OrderForm billing_address_id.

Definition

HRESULT _OrderGroup::PurgeUnreferencedAddresses(
);

Parameters

None.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

See Also

OrderGroup Object


_OrderGroup::PutItemValue

Use this method to put the specified values into the specified keys of the line item.

Definition

HRESULT _OrderGroup::PutItemValue(
BSTR strKey,
VARIANT vtValue,
VARIANT_BOOL bOverWrite,
VARIANT nItemIndex,
VARIANT strOrderFormName
);

Parameters

strKey

[in] A BSTR that specifies the key whose attribute will store the value specified by the vtValue parameter.

vtValue

[in] A VARIANT that specifies the value to store in the attribute of the key specified by the strKey parameter.

bOverWrite

[in, optional, defaultvalue (-1)] A VARIANT_BOOL that indicates whether to overwrite the existing attribute of the key specified by the strKey parameter. A value of True indicates that the attribute will be overwritten. A value of False indicates that the attribute will not be overwritten if one already exists.

nItemIndex

[in, optional] A VARIANT that specifies the line-item index.

strOrderFormName

[in, optional] A VARIANT that specifies the OrderForm name.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

If the line-item index is specified, this method sets the name value pair for the specified line item on the OrderForm specified in the strOrderFormName parameter. (The strOrderFormName parameter defaults to "default" if unspecified.)

If the line item index is not specified, this method sets the name value pair for all line items for the specified OrderForm. If no OrderForm name is specified, this method sets the name value pair for all line items in the OrderGroup.

If there is no OrderForm for the strOrderFormName specified in the strOrderFormName parameter, one is created.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

OrderGroup Object


_OrderGroup::PutOrderFormValue

Use this method to set an attribute on an OrderForm. If the strOrderFormName parameter is supplied, and the OrderForm does not exist in the OrderGroup, then a new OrderForm with the supplied name is created.

If strOrderFormName is not supplied, the parameter defaults to "default".

Definition

HRESULT _OrderGroup::PutOrderFormValue(
BSTR strKey,
VARIANT vtValue,
VARIANT strOrderFormName
);

Parameters

strKey

[in] A BSTR that specifies the key whose attribute will store the value specified by the vtValue parameter.

vtValue

[in] A VARIANT that specifies the value to store in the attribute of the key specified by the strKey parameter.

strOrderFormName

[in, optional] A VARIANT that specifies the OrderForm name.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

OrderGroup Object


_OrderGroup::RemoveItem

Use this method to remove a line item from the specified OrderForm object. The item index specified indicates which line item to remove.

If the the strOrderFormName parameter is not supplied, the strOrderFormName parameter defaults to "default".

Definition

HRESULT _OrderGroup::RemoveItem(
VARIANT nItemIndex,
VARIANT strOrderFormName
);

Parameters

nItemIndex

[in, optional] A VARIANT that specifies the line item index.

strOrderFormName

[in, optional] A VARIANT that specifies the OrderForm name.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

OrderGroup Object

_OrderGroup::AddItem


_OrderGroup::RemoveOrderForm

Use this method to remove the specified OrderForm from the OrderGroup object.

Definition

HRESULT _OrderGroup::RemoveOrderForm(
BSTR strOrderFormName
);

Parameters

strOrderFormName

[in] A BSTR that specifies the OrderForm to remove.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

OrderGroup Object

_OrderGroup::AddOrderform


_OrderGroup::RunPipe

Use this method to run the Pipeline Component File on each OrderForm in the OrderGroup object.

Definition

HRESULT _OrderGroup::RunPipe(
BSTR strPCF,
BSTR strPipelineProgID,
IDispatch* oContext,
long* lpRetVal
);

Parameters

strPCF

[in] A BSTR that specifies the Pipeline Component File file path (for example, c:\SampleDir\SampleFile.pcf).

strPipelineProgID

[in] A BSTR that specifies the pipeline ProgID.

oContext

[in] A pointer to the IDispatch interface that specifies the pipeline context.

lpRetVal

[out, retval] A pointer to a long used to return the maximum error level encountered by the pipeline runs.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

When OrderGroup.RunPipe is called, the OrderGroup object instantiates and runs the pipeline for each of its contained OrderForms. The pipeline objects themselves continue to be passed a regular OrderForm, as if they were run in a stand-alone pipeline. In fact, a pipeline component has no way of knowing whether it is running on an OrderForm within an OrderGroup, or on a stand-alone OrderForm.

There are cases where you want the pipeline component to know about all items in the OrderGroup, regardless of whether those items are from differing vendors (ie a discount component). If this is the case, you should not use the multiple-OrderForm feature of the OrderGroup object (adding all items to the same OrderForm). In these cases, you can use the Splitter pipeline component to produce views of items from different vendors on your OrderForm.

When calling OrderGroup.RunPipe, you can rely on the aggregation features of the OrderGroup to produce grand totals across all OrderForms. OrderGroup.RunPipe automatically aggregates many common fields. If you wish to aggregate additional fields, use OrderGroup.AggregateOrderformValues.

Additionally, this method computes grand totals across each OrderForm for each of the following properties:

Orderform Value | Grand Total on the OrderGroup
_cy_oadjust_subtotal | saved_cy_oadjust_subtotal
_cy_total_total | saved_cy_total_total
_cy_shipping_total | saved_cy_shipping_total
_cy_handling_total | saved_cy_handling_total
_cy_tax_total | saved_cy_tax_total
_cy_tax_included | saved_cy_tax_included

Many pipeline keys are prefixed by "_", which by default means they will not be persisted to the database. Occasionally, you may want to take snapshots of these keys, and by convention, the prefix "saved_" is used in this situation. By using the "saved_" prefix they can be referred to later and can be searched via SQL statements or the OrderGroupManager object. Copied keys should not necessarily be trusted as being up-to-date. Also, they should not be used by pipeline components directly.

The OrderGroup object has a LogFile property that can be used to set the log file for the RunPipe method.

The lpRetVal parameter points to valid data only if the method completes successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Pipeline Basics

OrderGroup Object

_OrderGroup::get_LogFile, put_LogFile


_OrderGroup::SaveAsBasket

Use this method to save the OrderGroup object to the database with a basket status.

Definition

HRESULT _OrderGroup::SaveAsBasket(
VARIANT* pvtRetVal
);

Parameters

pvtRetVal

[out, retval] A pointer to a VARIANT used to return the OrderGroupID.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pvtRetVal parameter points to valid data only if the method completed successfully.

This method sets the OrderGroup status to "basket", and sets the OrderGroupID equal to the user ID.

If the OrderGroup object was not loaded from a basket, this method deletes any existing on-disk basket before inserting into the data storage.

If the OrderGroup object was loaded from a basket, this method performs an update or insert depending on whether the OrderGroup was found on-disk on the load call. If you load a template or order and call the SaveAsBasket method, the template or order which was originally loaded remains unchanged on disk.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

OrderGroup Object

_OrderGroup::LoadBasket

_OrderGroup::SaveAsOrder

_OrderGroup::SaveAsTemplate


_OrderGroup::SaveAsOrder

Use this method to save the OrderGroup to the database with an order status.

Definition

HRESULT _OrderGroup::SaveAsOrder(
VARIANT* vtOutTrackingNumber,
VARIANT* pvtRetVal
);

Parameters

vtOutTrackingNumber

[in] A pointer to the VARIANT used to return the tracking number. If specified, this VARIANT will contain the tracking number when the method returns.

pvtRetval

[out, retval] A pointer to a VARIANT used to return the OrderGroupID.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pvtRetVal parameter points to valid data only if the method completed successfully.

This method sets the OrderGroup status to "order" if the current status is Template, Basket, or undefined. (All other states are left alone; this allows orders to be in many states, such as pending approval, rejected, and so on.) You can set the state to any value except basket or template before calling the SaveAsOrder method; this method will not overwrite the state.

If this is the first time the order is saved, a special field will be written that records the order creation date. If an OrderTrackingNumber already exists on the OrderForm (under the key order_number) before the save, a new one will not be generated. This feature allows for ERP-based tracking numbers.

If the OrderGroup was loaded from a template, or from a basket, this method will generate a new OrderGroupID and tracking number, and perform a database insert. If the OrderGroup does not yet exist on disk, this method will generate an OrderGroupID and tracking number and perform a database insert. If the OrderGroup was loaded from any other state, this method will perform a database update.

If you load a basket or template and call the SaveAsOrder method, the basket or template remains unchanged on disk. For this reason,a call to the SaveAsOrder method is typically followed by a call to OrderGroupManager.DeleteOrderGroupFromDisk.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

OrderGroup Object

_OrderGroup::SaveAsBasket

_OrderGroup::SaveAsTemplate


_OrderGroup::SaveAsTemplate

Use this method to save the OrderGroup to the database with a template status.

Definition

HRESULT _OrderGroup::SaveAsTemplate(
VARIANT strTemplateName,
VARIANT* pvtRetVal
);

Parameters

strTemplateName

[in, optional] A VARIANT that specifies the template name.

pvtRetVal

[out, retval] A pointer to a VARIANT used to return the OrderGroupID of the template.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pvtRetVal parameter points to valid data only if the method completed successfully.

This method updates the OrderGroup template name field if the strTemplateName parameter is supplied.

If you originally loaded the OrderGroup from another state (ie a basket) and call SaveAsTemplate method, the original OrderGroup remains on disk unchanged.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

OrderGroup Object

_OrderGroup::SaveAsBasket

_OrderGroup::SaveAsOrder


_OrderGroup::get_SavePrefix, put_SavePrefix

Specifies a key prefix that will prevent a dictionary entry from being saved to the database.

Definition

Get method:

HRESULT _OrderGroup::get_SavePrefix(
BSTR* SavePrefix
);

Put method:

HRESULT _OrderGroup::put_SavePrefix(
BSTR SavePrefix
);

Parameters

SavePrefix

[in] When putting the property, a BSTR that contains the save prefix.
[out, retval] When getting the property, a pointer to a BSTR used to return the save prefix.

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

These properties return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The Value parameter contains valid data only if the property is accessed successfully.

No dictionary entry that has a key name that begins with the value of the SavePrefix property will be saved to the database. Assuming that the SavePrefix property is set to the underscore character ("_"), if the value of _adjusted_price is $ 200 and the value of total_price is $ 400, then $ 200 will not be persisted, but $ 400 will be persisted.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

OrderGroup Object


_OrderGroup::SetAddress

Use this method to add a specified address dictionary to the OrderGroup Addresses collection of the OrderGroup.

Definition

HRESULT _OrderGroup::SetAddress(
BSTR strAddressId,
IDictionary* oAddressDict
);

Parameters

strAddressId

[in] A BSTR that specifies the address ID of the address to be added.

oAddressDict

[in] A pointer to the IDictionary interface that contains the address dictionary to be added.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

OrderGroup Object

_OrderGroup::SetAddressFromFields


_OrderGroup::SetAddressFromFields

Use this method to set the OrderGroup address dictionary values as specified by the supplied Fields object. The column names in the field object will be mapped to dictionary keys names in the resultant address dictionary.

Definition

HRESULT _OrderGroup::SetAddressFromFields(
BSTR strAddressId,
Fields* flds
);

Parameters

strAddressId

[in] A BSTR that specifies the address ID of the address dictionary to be added.

flds

[in] A reference to a Fields object that contains the address information to be added.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

OrderGroup Object

_OrderGroup::SetAddress


_OrderGroup::SetShippingAddress

Use this method to set the shipping address id for the specified line items.

Definition

HRESULT _OrderGroup::SetShippingAddress(
BSTR address_id,
VARIANT_BOOL bOverWrite,
VARIANT nItemIndex,
VARIANT strOrderFormName
);

Parameters

address_id

[in] A BSTR that specifies the address ID to designate as the shipping address.

bOverWrite

[in, optional, defaultvalue (-1)] A VARIANT_BOOL that indicates whether to overwrite the shipping_address_id, if it already exists. A value of VT_TRUE indicates that an overwrite should occur. A value of VT_FALSE indicates that an overwrite should not occur.

nItemIndex

[in, optional] A VARIANT that specifies the line item index where the shipping_address_id will be set. If not specified, all line items will be set.

strOrderFormName

[in, optional] A VARIANT that specifies the OrderForm on which to perform the operation. If not specified, all OrderForms will be used if nItemIndex is unspecified; otherwise, the "default" OrderForm will be used.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The bOverWrite, nItemIndex, and strOrderFormName parameters work in a way similar to the same parameters in the PutItemValue method. Before performing the set operations, this method first ensures that the address id exists.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

OrderGroup Object


_OrderGroup::get_Value

The Value property is a read-only Variant that contains the OrderGroup-level attributes as a dictionary.

Definition

HRESULT _OrderGroup::get_Value(
VARIANT* Value
);

Parameters

Value

[out, retval] A pointer to a VARIANT used to return the Value dictionary.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The Value parameter contains valid data only if the property is accessed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

OrderGroup Object


OrderGroupManager Object

Use this object to manage OrderGroups and their contents. This object allows you to search for orders or baskets without having to use SQL queries. It also allows for OrderGroup deletions.

ProgID: | Commerce.OrderGroupManager (Externally creatable)
COM Class Name: | OrderGroupManager
COM Interface Name: | _OrderGroupManager
Interface ID Constant: | None
Header File: | None
Type Library Name: | Microsoft Commerce 2000 OrderGroup Type Library
DLL Name: | requisition.dll
Threading Model: | Apartment

In C++, use the _OrderGroupManager interface to access the properties and methods of the OrderGroupManager object.

Because this object is primarily intended for use within ASP script, access from C++ will not be common.

The properties of the OrderGroupManager object are shown in the following table.

Property | Type | Description
OrderFormHeaderColumns | VARIANT | Returns a string of comma-separated OrderFormHeader table column names. This property is read-only.
OrderFormLineItemsColumns | VARIANT | Returns a string of comma-separated OrderFormLineItems table column names. This property is read-only.
OrderGroupColumns | VARIANT | Returns a string of comma-separated OrderGroup table column names. This property is read-only.

The methods of the OrderGroupManager object are shown in the following table.

Method | Description
DeleteOrderGroupFromDisk | Checks whether a connection to the database has been established for the specified OrderGroup then deletes the OrderGroup and all objects contained within it from the database.
Find | Performs a SQL search based on the specified SQL clause fragments.
FindTemplatesForUser | Builds and returns an ADO recordset of OrderGroup templates for the specified user.
Initialize | Creates a connection to the specified database.
SimpleDelete | Deletes all entries that meet the search criteria as specified by the supplied SimpleFindSearchInfo and SimpleFindResultInfo objects.
SimpleFind | Returns an ADO recordset of OrderGroup items based on the specified SimpleFindSearchInfo values and SimpleFindResultInfo values. These object values contain the search criteria.

See Also

Business Process Objects

OrderGroup Object

OrderForm Object

SimpleFindSearchInfo Object

SimpleFindResultInfo Object


_OrderGroupManager::DeleteOrderGroupFromDisk

Use this method to check whether a connection to the database has been established for the specified OrderGroup, then delete the OrderGroup and all objects contained within it from the database.

Definition

HRESULT _OrderGroupManager::DeleteOrderGroupFromDisk(
BSTR OrderGroupID
);

Parameters

OrderGroupID

[in] A BSTR that contains the OrderGroup ID.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

OrderGroupManager Object


_OrderGroupManager::Find

Use this method to perform a SQL search based on the specified SQL clause fragments.

Definition

HRESULT _OrderGroupManager::Find(
VARIANT OrderGroupCriteriaArray,
VARIANT OrderFormCriteriaArray,
VARIANT LineItemCriteriaArray,
VARIANT SearchDateTimeColumn,
VARIANT SearchDateTimeStart,
VARIANT SearchDateTimeEnd,
long StatusFilter,
VARIANT_BOOL JoinOrderFormInfo,
VARIANT_BOOL JoinLineItemInfo,
VARIANT Columns,
VARIANT OrderGroupSortColumn,
VARIANT SortDirection,
long PageSize,
long PageNumber,
VARIANT* outTotalRecordsFound,
VARIANT* vtResults
);

Parameters

OrderGroupCriteriaArray

[in] A VARIANT that contains the SQL clause used to search for a specific set of OrderGroups.

OrderFormCriteriaArray

[in] A VARIANT that contains the SQL clause used to search for a specific set of orderforms.

LineItemCriteriaArray

[in] A VARIANT that contains the SQL clause used to search for a specific set of line items.

SearchDateTimeColumn

[in, optional] A VARIANT that specifies the DateTime column name to search for; if left null, the DateTime column name does not become part of the search criteria.

SearchDateTimeStart

[in, optional] A VARIANT that specifies the DateTime start value to search for; if left null, the DateTime start value does not become part of the search criteria.

SearchDateTimeEnd

[in, optional] A VARIANT that specifies the DateTime end value to search for; if left null, the DateTime end value does not become part of the search criteria.

StatusFilter

[in, optional, defaultvalue (0)] A long that stores the OrderGroup status.

JoinOrderFormInfo

[in, optional, defaultvalue (0)] A VARIANT_BOOL indicating whether to include the OrderFormHeader table in the results.

JoinLineItemInfo

[in, optional, defaultvalue (0)] A VARIANT_BOOL indicating whether to include the OrderFormLineItems table in the results.

Columns

[in, optional] A VARIANT that contains the names of the columns to return in addition to the default columns.

OrderGroupSortColumn

[in, optional] A VARIANT that contains the OrderGroup column name to sort on.

SortDirection

[in, optional] A VARIANT that contains the sort direction. This parameter is optional; possible values for this parameter are the SQL strings "ASC" or "DESC".

PageSize

[in, optional, defaultvalue (20)] With this method, you can implement a paging mechanism that allows you to page through your orders. (These could be viewed in a list sheet, for example.) The PageSize parameter is a long that contains the number of line items per page. This parameter setting must be coordinated with the PageNumber parameter.

PageNumber

[in, optional, defaultvalue (1)] With this method, you can implement a paging mechanism that allows you to page through your orders. (These could be viewed in a list sheet, for example.) The PageNumber parameter is a long that contains the page number to jump to. This parameter setting must be coordinated with the PageSize parameter.

outTotalRecordsFound

[out] A pointer to a VARIANT that specifies the total number of records found.

vtResults

[out, retval] A pointer to a VARIANT used to return the recordset containing the result set that meets the search criteria.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The vtResults parameter points to valid data only if the method completes successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

OrderGroupManager Object

_OrderGroupManager::SimpleFind


_OrderGroupManager::FindTemplatesForUser

Use this method to build and return an ADO recordset of OrderGroup templates for the specified user.

Definition

HRESULT _OrderGroupManager::FindTemplatesForUser(
BSTR UserId,
VARIANT SearchDateTimeColumn,
VARIANT SearchDateTimeStart,
VARIANT SearchDateTimeEnd,
VARIANT_BOOL JoinOrderFormInfo,
VARIANT_BOOL JoinLineItemInfo,
VARIANT Columns,
VARIANT OrderGroupSortColumn,
VARIANT SortDirection,
long PageSize,
long PageNumber,
VARIANT* outTotalRecordsFound,
VARIANT* pvtRetVal
);

Parameters

UserId

[in] A BSTR that contains the User ID GUID.

SearchDateTimeColumn

[in, optional] A VARIANT that contains the DateTime column name to use in the search.

SearchDateTimeStart

[in, optional] A VARIANT that contains the search DateTime start value.

SearchDateTimeEnd

[in, optional] A VARIANT that contains the search DateTime end value.

JoinOrderFormInfo

[in, optional, defaultvalue (0)] A VARIANT_BOOL that indicates whether the OrderFormHeader table is included in the search. A value of True indicates that the table is included. A value of False indicates that the table is not included.

JoinLineItemInfo

[in, optional, defaultvalue (0)] A VARIANT_BOOL that indicates whether the OrderFormLineItem table is included in the search. A value of True indicates that the table is included. A value of False indicates that the table is not included.

Columns

[in, optional] A VARIANT that contains the names of columns that you want returned in addition to the default columns.

OrderGroupSortColumn

[in, optional] A VARIANT that contains the OrderGroup sort column.

SortDirection

[in, optional] A VARIANT that contains the sort direction.

PageSize

[in, optional, defaultvalue (20)] A long that contains the page size.

PageNumber

[in, optional, defaultvalue (1)] A long that contains the page number.

outTotalRecordsFound

[out, optional] A pointer to the VARIANT that contains the total number of records found.

pvtRetVal

[out, retval] A pointer to a VARIANT used to return an ADO recordset of the search results.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pvtRetVal and outTotalRecordsFound parameters point to valid data only if the method returns successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

OrderGroupManager Object

Business Process Objects


_OrderGroupManager::Initialize

Use this method to create a connection to the specified database.

Definition

HRESULT _OrderGroupManager::Initialize(
VARIANT* ConnectionString
);

Parameters

ConnectionString

[in] A pointer to a VARIANT that contains the database connection string.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The ConnectionString parameter points to valid data only if the method completes successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

OrderGroupManager Object


_OrderGroupManager::get_OrderFormHeaderColumns

The OrderFormHeaderColumns property is a read-only Variant that contains a collection of OrderFormHeader table column names.

Definition

HRESULT _OrderGroupManager::get_OrderFormHeaderColumns(
VARIANT* OrderFormHeaderColumns
);

Parameters

OrderFormHeaderColumns

[out, retval] A pointer to a VARIANT used to return a collection of OrderForm header table column names.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This property returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The OrderFormHeaderColumns parameter contains valid data only if the method completes successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

OrderGroupManager Object


_OrderGroupManager::get_OrderFormLineItemsColumns

The OrderFormLineItemsColumns property is a read-only Variant that contains a collection of OrderFormLineItems table column names.

Definition

HRESULT _OrderGroupManager::get_OrderFormLineItemsColumns(
VARIANT* OrderFormLineItemsColumns
);

Parameters

OrderFormLineItemsColumns

[out, retval] A pointer to a VARIANT used to return a collection of LineItem table column names.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This property returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The OrderFormLineItemsColumns parameter contains valid data only if the property is accessed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

OrderGroupManager Object


_OrderGroupManager::get_OrderGroupColumns

The OrderGroupColumns property is a read-only Variant that contains a collection of OrderGroup table column names.

Definition

HRESULT _OrderGroupManager::get_OrderGroupColumns(
VARIANT* OrderGroupColumns
);

Parameters

OrderGroupColumns

[out, retval] A pointer to a VARIANT used to return the collection of OrderGroup column names.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This property returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The OrderGroupColumns parameter contains valid data only if the property is accessed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

OrderGroupManager Object


_OrderGroupManager::SimpleDelete

Use this method to delete all entries that meet the search criteria as specified by the supplied SimpleFindSearchInfo and SimpleFindResultInfo objects.

Definition

HRESULT _OrderGroupManager::SimpleDelete(
_SimpleFindSearchInfo* sfSearchInfo,
_SimpleFindResultInfo* sfResultInfo,
);

Parameters

sfSearchInfo

[in] A reference to a _SimpleFindSearchInfo object that contains the search criteria.

sfResultInfo

[in] A reference to a _SimpleFindResultInfo object that contains the search criteria.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pvtRetVal parameter points to valid data only if the method returns successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

OrderGroupManager Object


_OrderGroupManager::SimpleFind

Use this method to retrieve an ADO recordset of OrderGroup items based on the specified SimpleFindSearchInfo and SimpleFindResultInfo object values. These object values contain the search criteria.

Definition

HRESULT _OrderGroupManager::SimpleFind(
_SimpleFindSearchInfo* sfSearchInfo,
_SimpleFindResultInfo* sfResultInfo,
VARIANT* outTotalRecordsFound,
VARIANT* pvtRetVal
);

Parameters

sfSearchInfo

[in] A pointer to the _SimpleFindSearchInfo interface of a SimpleFindSearchInfo object that contains the search criteria.

sfResultInfo

[in] A pointer to the _SimpleFindResultInfo interface of a SimpleFindResultInfo object that contains the search criteria.

outTotalRecordsFound

[out] A pointer to a VARIANT that contains the total number of records found.

pvtRetVal

[out, retval] A pointer to a VARIANT used to return the search result recordset of OrderGroup items.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pvtRetVal and outTotalRecordsFound parameters point to valid data only if the method returns successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Business Process Objects

OrderGroupManager Object


OrderPipeline Object

Use this object to execute a Microsoft Commerce Server 2000 Content Selection pipeline. Order Processing pipelines (OPP) should generally use a PooledPipeline, PooledTxPipeline, MtxPipeline, or MtsTxPipeline object.

ProgID: | Commerce.OrderPipeline (Externally creatable)
COM Class Name: | COrderPipeline
COM Interface Name: | IOrderPipeline
Interface ID Constant: | IID_IOrderPipeline
Header File: | pipeline.h, mspu_guids.h
Type Library Name: | Microsoft Commerce 2000 Order Pipeline Type Library
DLL Name: | pipeline.dll
Threading Model: | Both

Note

  • The OrderPipeline should be used in Content Selection pipelines because Content Selection pipelines do not require transactions and because the OrderPipeline is fully re-entrant by multiple threads. Other objects, such as MtsPipeline and MtsTxPipeline, must be used once, destroyed and recreated by each thread due to the rules of COM+ transactions.

In C++, use the IOrderPipeline interface to access the properties and methods of the OrderPipeline object.

The methods of the OrderPipeline object are shown in the following table.

Method | Description
LoadPipe | Loads a pipeline configuration file (.pcf) into the pipeline.
OrderExecute | Runs the components in the pipeline.
SetLogFile | Identifies the file in which to log pipeline events.

Remarks

The OrderPipeline object creates and executes an Order Processing pipeline (OPP). The OrderPipeline object is not registered under Microsoft Transaction Server (MTS).

The OrderPipeline is usually created in the Global.asa and put into an application collection.


IOrderPipeline::LoadPipe

Use this method to load a pipeline configuration file (.pcf) into the pipeline.

Definition

HRESULT IOrderPipeline::LoadPipe(
BSTR pszFileName
);

Parameters

pszFileName

[in] A BSTR containing the pipeline configuration file name.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The LoadPipe method must be called to initialize all pipelines.

The LoadPipe method fails if you attempt to load a pipeline configuration file designated for transactions (for use with the MtsTxPipeline or PooledTxPipeline objects).

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

OrderPipeline Object

IOrderPipeline::OrderExecute

IOrderPipeline::SetLogFile


IOrderPipeline::OrderExecute

Use this method to run the stages in the pipeline configuration file, which was previously specified by the LoadPipe method.

Definition

HRESULT IOrderPipeline::OrderExecute(
long lMode,
IDispatch* pdispOrder,
IDispatch* pdispContext,
long lFlags,
long* pErrorLevel
);

Parameters

lMode

[in] A long integer indicating the mode in which to run the pipeline. This parameter is provided only for backward compatibility with Site Server 3.0 Commerce Edition sites. Commerce Server 2000 sites should set this parameter to one (1).

pdispOrder

[in] A pointer to the IDispatch interface of a Dictionary object, usually an OrderForm object. The Order dictionary that will be used by the pipeline.

pdispContext

[in] A pointer to the IDispatch interface of a Dictionary object. The Context dictionary that will be used by the pipeline.

lFlags

[in] An unused long integer parameter. Must be set to zero (0).

pErrorLevel

[out,retval] A pointer to an integer that returns the error level.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

In addition, the pErrorLevel parameter is set to one of the following three values:

Value | Description
1 | The pipeline ran successfully.
2 | A pipeline component raised a warning. Generally, these are basket or user errors that would be reported to the user through the ASP page.
3 | A pipeline component failed to run.

Remarks

The pErrorLevel parameter points to valid data only if the method completes successfully.

The lMode parameter is included only for backward compatibility with sites created in Site Server 2.0. In Site Server 3.0 Commerce Edition and later, the selection of pipeline stages is made by loading an appropriate pipeline configuration file with the LoadPipe method. Commerce Server 2000 applications should use the value one (1) for this parameter; zero (0) will cause no stages to run.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

OrderPipeline Object

IOrderPipeline::LoadPipe

IOrderPipeline::SetLogFile


IOrderPipeline::SetLogFile

Use this method to identify the file in which to log the operations of the pipeline component.

Note

  • This method is for use by developers who want to analyze pipeline configuration file information. Logging should never be used in a production environment: it degrades performance and may compromise the security of credit card numbers in non-set transactions.

Definition

HRESULT IOrderPipeline::SetLogFile(
BSTR pszFileName
);

Parameters

pszFileName

[in] A BSTR containing the name of the file in which to log events.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

When logging is set, the pipeline logs the pipeline components that are called and the error values each component returns. The pipeline also logs all Dictionary and SimpleList object read and write operations.

Calling this method with an empty string turns off logging.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

OrderPipeline Object

IOrderPipeline::LoadPipe

IOrderPipeline::OrderExecute


Page Object

Use this object to simplify forms processing in Active Server Pages (ASP).

ProgID: | Commerce.Page (Externally creatable)
COM Class Name: | MSCSPage_3_0
COM Interface Name: | IMSCSPage_3_0
Interface ID Constant: | IID_IMSCSPage_3_0
Header File: | commerce.h, mspu_guids.h
Type Library Name: | Commerce -- MSCSAspHelp Type Library
DLL Name: | MSCSAspHelp.dll
Threading Model: | Both

Important

  • This object is included for backward compatibility with Site Server 3.0 Commerce Edition. For more information, see the AuthManager and AppFrameWork objects, which provide similar functionality to many of the methods in this object.

The Page object methods fall into the following categories:

  • Formatting methods. These methods include Encode, Option, and Check. These methods make it possible for you to easily format HTML page items, and where applicable, to determine HTML item values based upon a run-time evaluation of other variables used in your page.

  • Validation methods. These methods begin with Request. They are used to retrieve values from a URL query string, convert the values to given data types based on a locale value, and validate these values against a specified range.

In C++, use the IMSCSPage_3_0 interface to access the properties and methods of the Page object.

The single property of the Page object is shown in the following table.

Property | Type | Description
Context | IDispatch | A value that contains the Microsoft Internet Information Services (IIS) scripting context. This property is read-only.

The methods of the Page object are shown in the following table.

Method | Description
Check | Generates the word CHECKED for use in an HTML page based upon a supplied value.
Encode | Encodes text in HTML.
GetShopperId | Returns the unique shopper ID for the current shopper.
HTMLEncode | Encodes text in HTML.
Option | Generates an option button on a page.
ProcessVerifyWith | Copies the contents of hidden fields created using the VerifyWith method into an OrderForm object's _verify_with Dictionary object.
PutShopperId | Writes the specified shopper ID for use in a URL or a secure URL (or as a cookie).
RequestDate | Retrieves a value from a URL query string or form post variable and converts it to a date value (Date Variant), based on the specified or default locale.
RequestDateTime | Retrieves a value from a URL query string or form post variable and converts it to a date/time value (Date Variant), based on the specified or default locale.
RequestDefault | Retrieves a value from a URL query string or form post variable and returns the value as a string.
RequestFloat | Retrieves a value from a URL query string or form post variable and converts it to a floating-point value, based on the specified or default locale. It then checks the value against a specified range and validates the value, based on the specified locale.
RequestMoneyAsNumber | Retrieves a value from a URL query string or form post variable and converts it to a number in the base monetary units of the specified or default locale.
RequestNumber | Retrieves a value from a URL query string or form post variable and converts it to a number, based on the specified or default locale.
RequestString | Retrieves a value from a URL query string or form post variable and performs string processing on it, based on the specified locale.
RequestTime | Retrieves a value from a URL query string or form post variable and converts the string to a Date Variant, based on the specified or default locale.
SiteRoot | Returns the physical directory that contains the Commerce Server site.
SURL | Generates a secure URL based on the local path to a file. This URL includes the shopper ID, where applicable.
SURLPrefix | Returns the secure root domain, which can be used as the prefix of a complete URL.
URL | Generates a full URL based on the local path to a file. This URL can include arguments and the shopper ID, where applicable.
URLArgs | Generates a series of query string arguments appropriate for passing in a URL.
URLEncode | Applies URL encoding rules to a specified string.
URLPrefix | Returns the non-secure root domain, which can be used as the prefix to a complete URL.
URLShopperArgs | Generates a series of query string arguments appropriate for passing in a URL. It also includes in the arguments the shopper ID if the StandardSManager has been initialized to URL mode.
VerifyWith | Sends outputs to the page hidden fields that contain verification values.
VirtualDirectory | Return the name of the virtual directory for the site.

See Also

Backward Compatibility Objects

AppFrameWork Object

AuthManager Object


IMSCSPage_3_0::Check

Use this method to generate the word CHECKED into a page if the value specified in the vtCheck parameter is a nonzero value. CHECKED is a parameter to an HTML <INPUT> tag, which sets a check box or radio button to selected when the form first loads.

Important

  • This method is included for backwards compatibility with Site Server 3.0 Commerce Edition.

Definition

HRESULT IMSCSPage_3_0::Check(
VARIANT vtCheck,
BSTR* pbstrRet
);

Parameters

vtCheck

[in] A VARIANT that contains the expression that is evaluated to determine whether the word CHECKED should be inserted at the location on a page where the call to Check appears.

pbstrRet

[out, retval] A pointer to a BSTR used to return the string "CHECKED" or "".

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pbstrRet parameter points to valid data only if the method completes successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Page Object

IMSCSPage_3_0::Option


IMSCSPage_3_0::get_Context

The Context property is a read-only property that contains the ASP scripting context.

Normally, the contents of the Context property do not need to be retrieved. The Context property is used only as a parameter to other Commerce Server methods that need access to the ASP scripting context.

Important

  • This method is included for backwards compatibility with Site Server 3.0 Commerce Edition.

Definition

HRESULT IMSCSPage_3_0::get_Context(
IDispatch** Context
);

Parameters

Context

[out, retval] An IDispatch interface used to return the ASP scripting context.

Return Values

This property returns an HRESULT indicating whether completed successfully. See the Error Values section for more details.

Error Values

This property returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The Context parameter contains valid data only if the property is accessed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Page Object


IMSCSPage_3_0::Encode

Use this method to apply HTML encoding to the specified text string.

This method is identical to the HTMLEncode method, which is the preferred name for this function. The Encode method applies HTML encoding to the specified text string. Characters in the string, such as "<" and "&" that have special meanings in HTML, are converted into their HTML equivalents, such as &lt; and &amp; so that they will be displayed correctly by the client browser.

Important

  • This method is included for backwards compatibility with Site Server 3.0 Commerce Edition.

Definition

HRESULT IMSCSPage_3_0::Encode(
VARIANT vtValue,
BSTR* pbstrRet
);

Parameters

vtValue

[in] A VARIANT that contains the text string to encode.

pbstrRet

[out, retval] A pointer to a BSTR used to return the encoded HTML text.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pbstrRet parameter points to valid data only if the method completed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Page Object

IMSCSPage_3_0::HTMLEncode


IMSCSPage_3_0::GetShopperId

This method returns the unique shopper ID for the current user. (The shopper ID is returned from a URL query string or a cookie, depending on the initialization mode of the StandardSManager for the site.)

If the current customer does not have a shopper ID, GetShopperID returns NULL.

Important

  • This method is included for backwards compatibility with Site Server 3.0 Commerce Edition. See the AuthManager object, which provides similar functionality to that found in the GetShopperID method. Using the AuthManager methods is the preferred way of adding this type of functionality to your site, and will ensure better compatibility with future versions of Microsoft Commerce Server.

Definition

HRESULT IMSCSPage_3_0::GetShopperId(
VARIANT* pvarShopperID
);

Parameters

pvarShopperID

[out, retval] A pointer to a VARIANT used to return the shopper ID.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pvarShopperID parameter points to valid data only if the method completed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Page Object

StandardSManager Object

AuthManager Object

IMSCSPage_3_0::PutShopperId


IMSCSPage_3_0::HTMLEncode

Use this method to apply HTML encoding to the specified text string. Its typical use is to display the contents of text fields contained in the database in HTML. Characters in the string, such as "<" and "&" that have special meanings in HTML, are converted into their HTML equivalents, such as &lt; and &amp; so that they will be displayed correctly by the client browser.

Important

  • This method is included for backwards compatibility with Site Server 3.0 Commerce Edition.

Definition

HRESULT IMSCSPage_3_0::HTMLEncode(
VARIANT vtValue,
BSTR* pbstrRet
);

Parameters

vtValue

[in] A VARIANT that contains the text string to encode.

pbstrRet

[out, retval] A pointer to a BSTR used to return the encoded HTML text.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pbstrRet parameter points to valid data only if the method completed successfully.

If the text field to be displayed already contains HTML encoding, do not use the HTMLEncode method. For example, suppose your product_description field contains HTML-encoded text such as "The <I>Classic Diner Clock</I> brings the age of the &quot;Golden Oldies&quot; to your kitchen." This string uses the <I> tag to format italic text and the &quot; sequence to display quotation marks when displayed by the client browser. Because the string is already coded in HTML, you do not need to encode it again. Double-encoding the string would produce incorrect results.

The Page.HTMLEncode method is identical to the Page.Encode method, but the HTMLEncode method is the preferred name. The method is similar to Server.HTMLEncode except that the Page.HTMLEncode method handles NULL values by returning an empty string (the Server.HTMLEncode method fails when the vtValue parameter is NULL). This distinction is important because database queries can return NULL.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Page Object

IMSCSPage_3_0::URLEncode


IMSCSPage_3_0::Option

Use this method to generate an OPTION item in an HTML form selection list, and then assign it the value and selection state that you specify. Although this functionality can be created without the Option method, using the method can speed your site development.

Important

  • This method is included for backwards compatibility with Site Server 3.0 Commerce Edition. See the AppFrameWork object, which provides similar functionality to that found in this method. Using the AppFrameWork methods is the preferred way of adding this type of functionality to your site, and will ensure better compatibility with future versions of Microsoft Commerce Server.

Definition

HRESULT IMSCSPage_3_0::Option(
VARIANT vtVal1,
VARIANT vtVal2,
BSTR* pbstrRet
);

Parameters

vtVal1

[in] A VARIANT that contains the value of the option in the selection list.

vtVal2

[in] A VARIANT that contains a value that indicates whether the list option is the selected option. If vtVal2 is equal to vtVal1, then the HTML keyword SELECTED is inserted in the definition of the option list.

pbstrRet

[out, retval] A pointer to a BSTR used to return the OPTION item.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pbstrRet parameter points to valid data only if the method completed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Page Object

IMSCSPage_3_0::Check


IMSCSPage_3_0::ProcessVerifyWith

Use this method in an ASP file that is activated when the shopper submits an HTML form containing an order. The ProcessVerifyWith method reads the posted contents of hidden fields in the HTML form that were created using the VerifyWith method and writes these values into a Dictionary object. This Dictionary object, called _verify_with, is stored in the OrderForm object.

When the pipeline processes the OrderForm, the contents of the _verify_with Dictionary object are compared to the original values of the fields in the OrderForm object to ensure that a page has not been altered between presentation and final purchase.

If the fields do not match, the RequiredTotal pipeline component generates an error, using the MessageManager message name constant pur_badverify.

Important

  • This method is included for backwards compatibility with Site Server 3.0 Commerce Edition. See the AppFrameWork object, which provides similar functionality to that found in this method. Using the AppFrameWork methods is the preferred way of adding this type of functionality to your site, and will ensure better compatibility with future versions of Microsoft Commerce Server.

Definition

HRESULT IMSCSPage_3_0::ProcessVerifyWith(
IDispatch* pdispOrder
);

Parameters

pdispOrder

[in] A pointer to the IDispatch interface that can be used to retrieve an OrderForm object that contains the basket for the current shopper.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Page Object

IMSCSPage_3_0::VerifyWith

Message Manager Object

OrderForm Object


IMSCSPage_3_0::PutShopperId

Use this method to write the specified shopper ID to a cookie, and/or store it for use in a URL or secure URL, depending on the initialization mode of the StandardSManager for the site.

Important

  • This method is included for backwards compatibility with Site Server 3.0 Commerce Edition. See the AuthManager object, which provides similar functionality to that found in the PutShopperID method. Using the AuthManager methods is the preferred way of adding this type of functionality to your site, and will ensure better compatibility with future versions of Microsoft Commerce Server.

Definition

HRESULT IMSCSPage_3_0::PutShopperId(
BSTR bstrShopperID
);

Parameters

bstrShopperID

[in] A BSTR that contains the shopper ID.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

Where the PutShopperID method will store the specified shopper ID depends upon the StandardSManager initialization mode. In URL mode, this method writes the shopper ID to the request, so that the URL and SURL methods add the shopper ID to a query string in the URL from this page.

If the shopper ID is stored in a URL query string, you can retrieve it by passing the value you set for the application-level MSCSSIDURLKey to the IIS Request object.

If you initialize the StandardSManager in URL mode, you cannot use the StandardSManager's implementation of PutShopperID to store the shopper ID on the client system. Instead, you must use the implementation from the Page object.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Page Object

StandardSManager Object

AuthManager Object

IMSCSPage_3_0::GetShopperId

IMSCSPage_3_0::SURL

IMSCSPage_3_0::URL


IMSCSPage_3_0::RequestDate

Use this method to retrieve a value from a URL query string or form post variable and convert it to a date value (Date Variant), based on the specified or default locale.

Optionally, RequestDate also checks the date against a specified date range.

Important

  • This method is included for backwards compatibility with Site Server 3.0 Commerce Edition. See the AppFrameWork object, which provides similar functionality to that found in this method. Using the AppFrameWork methods is the preferred way of adding this type of functionality to your site, and will ensure better compatibility with future versions of Microsoft Commerce Server.

Definition

HRESULT IMSCSPage_3_0::RequestDate(
BSTR bstrName,
VARIANT vtDefault,
VARIANT vtMin,
VARIANT vtMax,
VARIANT vtLocal,
VARIANT* pvtRet
);

Parameters

bstrName

[in] A BSTR that contains the name of the URL query string or form-post variable to retrieve.

vtDefault

[in, optional] A VARIANT that contains the date value to return if the requested URL query string or form-post variable does not exist or contains no value. The default cannot contain DateTime and Time values.

vtMin

[in, optional] A VARIANT that contains a date value that specifies the low end of the range against which to validate the value of the bstrName parameter. If the variant is of type VT_NULL, the vtMin parameter value is not considered in the validation process. If the converted date is less than vtMin, the method returns NULL.

vtMax

[in, optional] A VARIANT that contains a date value that specifies the high end of the range against which to validate the value of the bstrName parameter. If the variant is of type VT_NULL, the vtMax parameter value is not considered in the validation process. If the converted value is greater than vtMax, the method returns NULL.

vtLocale

[in, optional] A VARIANT that contains a number that specifies the locale to use to convert the date. If this value is not specified, the RequestDate method uses the value of the Locale property of the DataFunctions object.

pvtRet

[out, retval] A pointer to a VARIANT used to return the processed date value. If any validation fails, the return value will be NULL.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pvtRet parameter points to valid data only if the method completed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Page Object

IDataFunctions_4_0::get_Locale, put_Locale

IMSCSPage_3_0::RequestDateTime

IDataFunctions_4_0_::ConvertDateString

IDataFunctions_4_0::Date


IMSCSPage_3_0::RequestDateTime

Use this method to retrieve a value from a URL query string or form post variable and convert it to a date/time value (Date Variant), based on the specified or default locale.

Important

  • This method is included for backwards compatibility with Site Server 3.0 Commerce Edition. See the AppFrameWork object, which provides similar functionality to that found in this method. Using the AppFrameWork methods is the preferred way of adding this type of functionality to your site, and will ensure better compatibility with future versions of Microsoft Commerce Server.

Definition

HRESULT IMSCSPage_3_0::RequestDateTime(
BSTR bstrName,
VARIANT vtDefault,
VARIANT vtMin,
VARIANT vtMax,
VARIANT vtLocal,
VARIANT* pvtRet
);

Parameters

bstrName

[in] A BSTR that contains the name of the URL query string or form-post variable to retrieve.

vtDefault

[in, optional] A VARIANT that contains the value to return if the requested URL query string or form-post variable does not exist or contains no value. If this parameter is not supplied, the method returns NULL. The default cannot contain Time values.

vtMin

[in, optional] A VARIANT that contains a DateTime value that specifies the low end of the range against which to validate the value of the bstrName parameter. If the variant is of type VT_NULL, the vtMin parameter value is not considered in the validation process.If the converted value is less than vtMin, the method returns NULL.

vtMax

[in, optional] A VARIANT that contains a DateTime value that specifies the high end of the range against which to validate the value of the bstrName parameter. If the variant is of type VT_NULL, the vtMax parameter value is not considered in the validation process. If the converted value is greater than vtMax, the method returns NULL.

vtLocale

[in, optional] A VARIANT that contains the number that identifies the locale to be used to convert the date/time string. If this parameter is not specified, the RequestDateTime method uses the value of the Locale property of the DataFunctions object.

pvtRet

[out, retval] A pointer to a VARIANT used to return the DateTime value. If any validation fails, the return value will be NULL.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pvtRet parameter points to valid data only if the method completed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Page Object

IDataFunctions_4_0::get_Locale, put_Locale

IMSCSPage_3_0::RequestDate

IDataFunctions_4_0::ConvertDateTimeString

IMSCSPage_3_0::RequestTime


IMSCSPage_3_0::RequestDefault

Use this method to retrieve a value from a URL query string or form post variable and return the value as a string.

Important

  • This method is included for backwards compatibility with Site Server 3.0 Commerce Edition.

Definition

HRESULT IMSCSPage_3_0::RequestDefault(
BSTR bstrName,
VARIANT vtDefault,
VARIANT* pvtRet
);

Parameters

bstrName

[in] A BSTR that contains the name of the URL query string variable to retrieve.

vtDefault

[in] A VARIANT that contains the value to return if the requested URL query string or form post variable contains an empty or a NULL value, or is not present in the request string. If this parameter is not supplied, the method returns NULL.

pvtRet

[out, retval] A pointer to a VARIANT used to return the processed value as a string.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pvtRet parameter points to valid data only if the method completed successfully.

This method is designed so that if a field on a form is blank, or the form does not contain the field, the value returned by default is NULL. NULL is generally the appropriate value to store to a database when a value is not present. If you need the result to be an empty string in the case of a missing value, supply an empty string as the Default parameter.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Page Object


IMSCSPage_3_0::RequestFloat

Use this method to retrieve a value from a URL query string or form post variable and convert it to a floating-point value, based on the specified or default locale.

Optionally, the RequestFloat method also checks the converted number against the specified range.

Important

  • This method is included for backwards compatibility with Site Server 3.0 Commerce Edition. See the AppFrameWork object, which provides similar functionality to that found in this method. Using the AppFrameWork methods is the preferred way of adding this type of functionality to your site, and will ensure better compatibility with future versions of Microsoft Commerce Server.

Definition

HRESULT IMSCSPage_3_0::RequestFloat(
BSTR bstrName,
VARIANT vtDefault,
VARIANT vtMin,
VARIANT vtMax,
VARIANT vtLocal,
VARIANT* pvtRet
);

Parameters

bstrName

[in] A BSTR that contains the name of the URL query string or form-post variable to retrieve.

vtDefault

[in, optional] A VARIANT that contains the value to return if the requested URL query string or form-post variable is not present or contains no value. If this parameter is not supplied, the method returns NULL.

vtMin

[in, optional] A VARIANT that contains the number that specifies the low end of the range of values against which to validate the converted value. If the variant is of type VT_NULL, the vtMin parameter value is not considered in the validation process. If the converted value is less than vtMin, the method returns NULL.

vtMax

[in, optional] A VARIANT that contains the number that specifies the high end of the range of values against which to validate the converted value. If the variant is of type VT_NULL, the vtMax parameter value is not considered in the validation process. If the converted value is greater than vtMax, the method returns NULL.

A Variant that contains the number that specifies the high end of the range of values against which to validate the converted value. The default value is NULL, indicating that this parameter is ignored. If the converted value is greater than vtMax, the method returns NULL. This parameter is optional.

vtLocale

[in, optional] A VARIANT that contains the number that identifies the locale to use to convert the value. If this value is not specified, the RequestFloat method uses the value of the Locale property of the DataFunctions object.

pvtRet

[out, retval] A pointer to a VARIANT used to return the floating-point value. If any validation fails, the return value will be NULL.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pvtRet parameter points to valid data only if the method completes successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Page Object

IDataFunctions_4_0::get_Locale, put_Locale

IMSCSPage_3_0::RequestNumber

IDataFunctions_4_0::ConvertFloatString

IDataFunctions_4_0::Float

IDataFunctions_4_0::ValidateFloat

IMSCSPage_3_0::RequestNumber


IMSCSPage_3_0::RequestMoneyAsNumber

Use this method to retrieve a value from a URL query string or form post variable and convert it to a number in the base monetary units of the specified or default locale.

This method is used for backwards compatibility with Site Server 3.0 Commerce Edition sites, and relies on the Site Server 3.0 Commerce Edition monetary format.

Important

  • This method is included for backwards compatibility with Site Server 3.0 Commerce Edition. See the AppFrameWork object, which provides similar functionality to that found in this method. Using the AppFrameWork methods is the preferred way of adding this type of functionality to your site, and will ensure better compatibility with future versions of Microsoft Commerce Server.

Definition

HRESULT IMSCSPage_3_0::RequestMoneyAsNumber(
BSTR bstrName,
VARIANT vtDefault,
VARIANT vtMin,
VARIANT vtMax,
VARIANT vtLocal,
VARIANT* pvtRet
);

Parameters

bstrName

[in] A BSTR that contains the name of the URL-query string or form-post variable to retrieve.

vtDefault

[in, optional] A VARIANT that contains the value to return if the requested URL-query string or form-post variable is not present or contains no value. If this parameter is not supplied, the method returns NULL. If the default value is a string value, it will be converted into the base monetary value, otherwise, it is assumed that the value is in base monetary units.

vtMin

[in, optional] A VARIANT that contains the monetary value that specifies the low end of the range against which to validate the converted value. A value in base monetary units is expected for the vtMin parameter. If the converted value is less than vtMin, the method returns NULL. This parameter is optional.

vtMax

[in, optional] A VARIANT that contains the monetary value that specifies the high end of the range against which to validate the converted value. If the variant is of type VT_NULL, the vtMax parameter value is not considered in the validation process. A value in base monetary units is expected for the vtMax parameter. If the converted value is greater than vtMax, the method returns NULL.

vtLocale

[in, optional] A VARIANT that contains the number that specifies the locale to use to convert the bstrName parameter. If this parameter is not used, the RequestMoneyAsNumber method uses the value of the Locale property of the DataFunctions object.

pvtRet

[out, retval] A pointer to a VARIANT used to return the number in the base monetary units of the specified or default locale. If any validation fails, the return value will be NULL.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

This method is used for backwards compatibility with Site Server 3.0 Commerce Edition sites, and relies on the Site Server 3.0 Commerce Edition monetary format.

The pvtRet parameter points to valid data only if the method completed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Page Object

IDataFunctions_4_0::get_Locale, put_Locale

IDataFunctions_4_0::ConvertMoneyStringToNumber

IDataFunctions_4_0::Money

IMSCSPage_3_0::RequestFloat

IMSCSPage_3_0::RequestNumber


IMSCSPage_3_0::RequestNumber

Use this method to retrieve a value from a URL query string or form post variable and convert it to a number based on the specified or default locale.

Optionally, the RequestNumber method checks the converted number against the specified range and validates it based on the specified locale.

Important

  • This method is included for backwards compatibility with Site Server 3.0 Commerce Edition. See the AppFrameWork object, which provides similar functionality to that found in this method. Using the AppFrameWork methods is the preferred way of adding this type of functionality to your site, and will ensure better compatibility with future versions of Microsoft Commerce Server.

Definition

HRESULT IMSCSPage_3_0::RequestNumber(
BSTR bstrName,
VARIANT vtDefault,
VARIANT vtMin,
VARIANT vtMax,
VARIANT vtLocal,
VARIANT* pvtRet
);

Parameters

bstrName

[in] A BSTR that contains the name of the URL-query string or form-post variable to retrieve.

vtDefault

[in, optional] A VARIANT that contains the value to return if the requested URL-query string or form-post variable is not present or contains no value. If this parameter is not supplied, the method returns NULL.

vtMin

[in, optional] A VARIANT that contains the number value that specifies the low end of the range against which to validate the converted value. If the converted value is less than vtMin, then NULL is returned. If the variant is of type VT_NULL, the vtMin parameter value is not considered in the validation process.

vtMax

[in, optional] A VARIANT that contains the number value that specifies the high end of the range against which to validate the converted value. If the converted value is greater than vtMax, then NULL is returned. If the variant is of type VT_NULL, the vtMax parameter value is not considered in the validation process. If the converted value is greater than vtMax, the method returns NULL.

vtLocale

[in, optional] A VARIANT that contains the number that specifies the locale to use to convert the bstrName parameter. If this parameter is not used, the RequestNumber method uses the value of the Locale property of the DataFunctions object.

pvtRet

[out, retval] A pointer to a VARIANT used to return the converted number. If any validation fails, the return value will be NULL.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pvtRet parameter points to valid data only if the method completed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Page Object

IDataFunctions_4_0::get_Locale, put_Locale

IMSCSPage_3_0::RequestFloat

IDataFunctions_4_0::ConvertNumberString

IDataFunctions_4_0::Number

IDataFunctions_4_0::ValidateNumber


IMSCSPage_3_0::RequestString

Use this method to retrieve a value from a URL query string or form post variable and perform string processing on it, based on the specified locale.

This processing may involve stripping out leading and trailing white spaces, stripping out carriage returns, checking the length of the string against a specified range, and validating the string based on the specified or default locale.

Important

  • This method is included for backwards compatibility with Site Server 3.0 Commerce Edition. See the AppFrameWork object, which provides similar functionality to that found in this method. Using the AppFrameWork methods is the preferred way of adding this type of functionality to your site, and will ensure better compatibility with future versions of Microsoft Commerce Server.

Definition

HRESULT IMSCSPage_3_0::RequestString(
BSTR bstrName,
VARIANT vtDefault,
VARIANT vtMin,
VARIANT vtMax,
VARIANT vtStripWhite,
VARIANT vtStripReturn,
VARIANT vtCase,
VARIANT vtLocal,
VARIANT* pvtRet
);

Parameters

bstrName

[in] A BSTR that contains the name of the URL-query string or form-post variable to retrieve.

vtDefault

[in, optional] A VARIANT that contains the string to return if the specified URL-query string or form-post variable does not exist or contains no value. If this parameter is not supplied, the method returns NULL.

vtMin

[in, optional] A VARIANT that contains the number that indicates the minimum length against which the length of the bstrName parameter must be validated. If the variant is of type vtMissing, the vtMin parameter value is not considered in the validation process. If this value is invalid or length of the bstrName/vtDefault parameter is not in range, the method returns NULL.

vtMax

[in, optional] A VARIANT that contains the number that indicates the maximum length against which the length of the bstrName parameter must be validated. If the variant is of type vtMissing, the vtMax parameter value is not considered in the validation process. If this value is invalid or length of the bstrName/vtDefault parameter is not in range, the method returns NULL.

vtStripWhite

[in, optional] A VARIANT that contains a Boolean value that indicates whether leading and trailing white spaces should be stripped from the string. The default value is True.

vtStripReturn

[in, optional] A VARIANT that contains a Boolean value that indicates whether carriage returns should be stripped from the string. The default value is True.

vtCase

[in, optional] A VARIANT that contains the number that indicates the case to which the string should be converted. The default value is zero (0), which results in no modification to the case of the string. If the vtCase parameter is one (1), the string is converted to uppercase. If the vtCase parameter is two (2), the string is converted to lowercase.

vtLocal

[in, optional] A VARIANT that contains the number that specifies the locale to be used as the basis of the conversion. If this value is not specified, the RequestString method uses the value of the Locale property of the DataFunctions object.

pvtRet

[out, retval] A pointer to a VARIANT used to return the processed string.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pvtRet parameter points to valid data only if the method completed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Page Object

IDataFunctions_4_0::get_Locale, put_Locale


IMSCSPage_3_0::RequestTime

Use this method to retrieve a value from a URL query string or form post variable and convert the string to a Date Variant, based on the specified or default locale.

Important

  • This method is included for backwards compatibility with Site Server 3.0 Commerce Edition. See the AppFrameWork object, which provides similar functionality to that found in this method. Using the AppFrameWork methods is the preferred way of adding this type of functionality to your site, and will ensure better compatibility with future versions of Microsoft Commerce Server.

Definition

HRESULT IMSCSPage_3_0::RequestTime(
BSTR bstrName,
VARIANT vtDefault,
VARIANT vtMin,
VARIANT vtMax,
VARIANT vtLocal,
VARIANT* pvtRet
);

Parameters

bstrName

[in] A BSTR that contains the name of the URL-query string or form-post variable to retrieve.

vtDefault

[in, optional] A VARIANT that contains the string to return if the specified URL-query string or form-post variable does not exist or contains no value. If this parameter is not supplied, the method returns NULL. The default cannot contain DateTime or Date values.

vtMin

[in, optional] A VARIANT that contains the time value that specifies the low end of the range against which to validate the bstrName parameter. If the VARIANT is of type vtMissing, the vtMin parameter value is not considered in the validation process.If the converted value is less than vtMin, the method returns NULL.

vtMax

[in, optional] A VARIANT that contains the time value that specifies the high end of the range against which to validate the bstrName parameter. If the variant is of type vtMissing, the vtMax parameter value is not considered in the validation process. If the converted value is greater than vtMax, the method returns NULL.

vtLocale

[in, optional] A VARIANT that contains the number that specifies the locale to use to convert the DateTime value. If this value is not specified, the RequestTime method uses the value of the Locale property of the DataFunctions object.

pvtRet

[out, retval] A pointer to a VARIANT used to return the date. If any validation fails, the value will be set to NULL.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pvtRet parameter points to valid data only if the method completed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Page Object

IDataFunctions_4_0::get_Locale, put_Locale

IDataFunctions_4_0::ConvertTimeStringf

IMSCSPage_3_0::RequestDate


IMSCSPage_3_0::SiteRoot

Use this method to return the physical directory that contains the Commerce Server site.

Important

  • This method is included for backwards compatibility with Site Server 3.0 Commerce Edition.

Definition

HRESULT IMSCSPage_3_0::SiteRoot(
BSTR* pbstrRet
);

Parameters

pbstrRet

[out, retval] A pointer to a BSTR used to return the physical directory path.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pvtRet parameter points to valid data only if the method completed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Page Object

IMSCSPage_3_0::VirtualDirectory


IMSCSPage_3_0::SURL

Use this method to generate a properly formatted secure HTTP URL (SURL) based on the provided file name and an optional list of name/value arguments. The formatted URL includes the server name, the virtual directory in which the file is stored (taken from the context in which the Web site is running), and the name of the file itself.

Additionally, if the StandardSManager for the application is initialized in URL mode, the SURL method uses the value stored in the MSCSSIDUrlKey Application object variable as the name in a name/value pair, the value of which is the current customer's shopper ID.

Important

  • This method is included for backwards compatibility with Site Server 3.0 Commerce Edition. See the AuthManager object, which provides similar functionality to that found in the SURL method. Using the AuthManager methods is the preferred way of adding this type of functionality to your site, and will ensure better compatibility with future versions of Microsoft Commerce Server.

Definition

HRESULT IMSCSPage_3_0::SURL(
BSTR bstrPath,
BSTR* pbstrRet
);

Parameters

bstrPath

[in] A BSTR that contains the name of the file for the SURL to reference.

pbstrRet

[out, retval] A pointer to a BSTR used to return the properly formatted secure HTTP URL.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pbstrRet parameter points to valid data only if the method completed successfully.

During application development, you can set the Site.DisableHTTPS property to one (1), which causes the SURL method to use the InsecureHostName value as the host name. The SURL method generates a secure URL only if Site.DisableHTTPS is set to zero (0).

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Page Object

StandardSManager Object

AuthManager Object

IMSCSPage_3_0::URL


IMSCSPage_3_0::SURLPrefix

Use this method to return the secure root domain as determined by the MSCSSecureHostName value. The returned string can be used as the prefix of a complete URL.

Important

  • This method is included for backwards compatibility with Site Server 3.0 Commerce Edition. See the AuthManager object, which provides similar functionality to that found in the SURLPrefix method. Using the AuthManager methods is the preferred way of adding this type of functionality to your site, and will ensure better compatibility with future versions of Microsoft Commerce Server.

Definition

HRESULT IMSCSPage_3_0::SURLPrefix(
BSTR* pbstrRet
);

Parameters

pbstrRet

[out, retval] A pointer to a BSTR used to return the secure root domain string.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pbstrRet parameter points to valid data only if the method completed successfully.

During application development, you can set the DisableHTTPS property of the site dictionary to one (1), which causes the SURLPrefix method to use the InsecureHostName value as the host name. The SURLPrefix method generates a secure URL only if Site.DisableHTTPS is set to zero (0).

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Page Object

StandardSManager Object

AuthManager Object

IMSCSPage_3_0::URLPrefix

IMSCSPage_3_0::URLShopperArgs

IMSCSPage_3_0::SURL

IMSCSPage_3_0::URLArgs

IMSCSPage_3_0::VirtualDirectory


IMSCSPage_3_0::URL

Use this method to generate a URL based on the specified file name and an optional list of name/value arguments. This URL includes the server name, the virtual directory in which the file is stored, and the name of the file itself.

Additionally, if the StandardSManager for the application is initialized in URL mode, the URL method uses the value stored in the Application object's MSCSSIDUrlKey variable as the name in a name/value pair, the value of which is the current shopper ID.

The method applies URL encoding to the values passed in.

Important

  • This method is included for backwards compatibility with Site Server 3.0 Commerce Edition. See the AuthManager object, which provides similar functionality to that found in the URL method. Using the AuthManager methods is the preferred way of adding this type of functionality to your site, and will ensure better compatibility with future versions of Microsoft Commerce Server.

Definition

HRESULT IMSCSPage_3_0::URL(
BSTR bstrPath,
BSTR* pbstrRet
);

Parameters

bstrPath

[in] A BSTR that contains the name of the file to reference in the URL.

pbstrRet

[out, retval] A pointer to a BSTR used to return the encoded value.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pbstrRet parameter points to valid data only if the method completed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Page Object

AuthManager Object

IMSCSPage_3_0::SURL


IMSCSPage_3_0::URLArgs

Use this method to generate a series of query string arguments in an appropriate form for passing in a URL. The method applies URL encoding to the values passed in.

Important

  • This method is included for backwards compatibility with Site Server 3.0 Commerce Edition. See the AuthManager object, which provides similar functionality to that found in the URLArgs method. Using the AuthManager methods is the preferred way of adding this type of functionality to your site, and will ensure better compatibility with future versions of Microsoft Commerce Server.

Definition

HRESULT IMSCSPage_3_0::URLArgs(
BSTR* pbstrRet
);

Parameters

pbstrRet

[out, retval] A pointer to a BSTR used to return the series of query string arguments.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pbstrRet parameter points to valid data only if the method completed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Page Object

AuthManager Object

IMSCSPage_3_0::VirtualDirectory

IMSCSPage_3_0::SURL

IMSCSPage_3_0::SURLPrefix

IMSCSPage_3_0::URL

IMSCSPage_3_0::URLShopperArgs


IMSCSPage_3_0::URLEncode

Use this method to apply URL-encoding rules, including escape characters, to a specified string. An encoded URL string may be passed in a URL as a query string argument.

Important

  • This method is included for backwards compatibility with Site Server 3.0 Commerce Edition. See the AuthManager object, which provides similar functionality to that found in the URLEncode method. Using the AuthManager methods is the preferred way of adding this type of functionality to your site, and will ensure better compatibility with future versions of Microsoft Commerce Server.

Definition

HRESULT IMSCSPage_3_0::URLEncode(
VARIANT vtValue,
BSTR* pbstrRet
);

Parameters

vtValue

[in] A VARIANT that contains the string to be encoded.

pbstrRet

[out, retval] A pointer to a BSTR used to return the URL-encoded string.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pbstrRet parameter points to valid data only if the method completed successfully.

Strings that contain certain characters, such as spaces, slashes (/), or percentage symbols (%), cannot be passed as URL query arguments. URL encoding encodes these characters as escaped text so that they can be passed in a URL.

The Page.URLEncode method is equivalent to the Server.URLEncode method, except that the Page.URLEncode method handles NULL values by returning an empty string. (The Server.URLEncode method fails when the String parameter is NULL). This distinction is important because database queries can return NULL.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Page Object

AuthManager Object

IMSCSPage_3_0::HTMLEncode


IMSCSPage_3_0::URLPrefix

Use this method to return the root domain as determined by the InsecureHostName value. The returned string can be used as the prefix to a complete URL.

Important

  • This method is included for backwards compatibility with Site Server 3.0 Commerce Edition. See the AuthManager object, which provides similar functionality to that found in the URLPrefix method. Using the AuthManager methods is the preferred way of adding this type of functionality to your site, and will ensure better compatibility with future versions of Microsoft Commerce Server.

Definition

HRESULT IMSCSPage_3_0::URLPrefix(
BSTR* pbstrRet
);

Parameters

pbstrRet

[out, retval] A pointer to a BSTR used to return the root domain.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pbstrRet parameter points to valid data only if the method completed successfully.

To generate the domain for the secure host, use the Page.SURLPrefix method.

See Also

Page Object

AuthManager Object

IMSCSPage_3_0::SURLPrefix

IMSCSPage_3_0::VirtualDirectory

IMSCSPage_3_0::SURL

IMSCSPage_3_0::SURLPrefix

IMSCSPage_3_0::URL

IMSCSPage_3_0::URLShopperArgs

IMSCSPage_3_0::URLArgs


IMSCSPage_3_0::URLShopperArgs

Use this method to generate a series of query string arguments in an appropriate form for passing in a URL, and include in the arguments the shopper ID if the StandardSManager has been initialized to URL mode. The URLShopperArgs method URL-encodes the values passed in.

Important

  • This method is included for backwards compatibility with Site Server 3.0 Commerce Edition. See the AuthManager object, which provides similar functionality to that found in the URLShopperArgs method. Using the AuthManager methods is the preferred way of adding this type of functionality to your site, and will ensure better compatibility with future versions of Microsoft Commerce Server.

Definition

HRESULT IMSCSPage_3_0::URLShopperArgs(
BSTR* pbstrRet
);

Parameters

pbstrRet

[out, retval] A pointer to a BSTR used to return the series of query string arguments.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pbstrRet parameter points to valid data only if the method completed successfully.

The URLShopperArgs method appends the current customer's shopper ID to the URL argument list. The name of the argument passed in the URL is stored in the Application object's MSCSSIDUrlKey variable.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Page Object

AuthManager Object


IMSCSPage_3_0::VerifyWith

Use this method to output HTML tags in the form <INPUT TYPE="HIDDEN"> in an HTML form. These hidden fields contain specified values from the OrderForm object to be used to verify that an order has not been altered between presentation of the OrderForm and final purchase. When the order form is submitted, the ProcessVerifyWith method on the target page stores these fields in a Dictionary object in the OrderForm, which is then passed to the Order Processing pipeline (OPP). One of the objects in the pipeline compares the original values with the values from the hidden fields.

Important

  • This method is included for backwards compatibility with Site Server 3.0 Commerce Edition. See the AppFrameWork object, which provides similar functionality to that found in this method. Using the AppFrameWork methods is the preferred way of adding this type of functionality to your site, and will ensure better compatibility with future versions of Microsoft Commerce Server.

Definition

HRESULT IMSCSPage_3_0::VerifyWith(
IDispatch* pdispOrder,
BSTR* pbstrArguments
BSTR* pbstrRet
);

Parameters

pdispOrder

[in] A pointer to the IDispatch interface that can be used to retrieve the OrderForm object that contains the fields to verify.

pbstrArguments

[in] A pointer to a BSTR that contains a comma-separated list of field names in the supplied OrderForm object to verify. This parameter is optional.

pbstrRet

[out, retval] A pointer to a BSTR used to return the HTML tags.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pbstrRet parameter points to valid data only if the method completed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Page Object

IMSCSPage_3_0::ProcessVerifyWith

OrderForm Object


IMSCSPage_3_0::VirtualDirectory

Use this method to return the name of the virtual directory for the site.

Important

  • This method is included for backwards compatibility with Site Server 3.0 Commerce Edition. See the AppFrameWork object, which provides similar functionality to that found in this method. Using the AppFrameWork methods is the preferred way of adding this type of functionality to your site, and will ensure better compatibility with future versions of Microsoft Commerce Server.

Definition

HRESULT IMSCSPage_3_0::VirtualDirectory(
BSTR* pbstrRet
);

Parameters

pbstrRet

[out, retval] A pointer to a BSTR used to return the site virtual directory.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pbstrRet parameter points to valid data only if the method completed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Page Object

IMSCSPage_3_0::SiteRoot

IMSCSPage_3_0::SURL

IMSCSPage_3_0::URL

IMSCSPage_3_0::SURLPrefix

IMSCSPage_3_0::URLArgs

IMSCSPage_3_0::URLPrefix

IMSCSPage_3_0::URLShopperArgs

StandardSManager Object


PooledPipeline Object

Use this object to execute a Microsoft Commerce Server 2000 pipeline configuration file. The pipeline may be an Order Processing pipeline (OPP).

The PooledPipeline object uses COM+ object pooling to greatly increase the loading speed of pipelines, where the contained pipeline components support object pooling. For more information about pooled pipelines, see Pooled Pipelines.

ProgID: | Commerce.PooledPipeline (Externally creatable)
COM Class Name: | CPooledPipeline
COM Interface Name: | IPipeline
Interface ID Constant: | IID_IPipeline
Header File: | pipeline.h, mspu_guids.h
Type Library Name: | Microsoft Commerce 2000 Order Pipeline Type Library
DLL Name: | pipeline.dll
Threading Model: | Both

In C++, use the IPipeline interface to access the properties and methods of the PooledPipeline object.

Because this object is primarily intended for use within ASP script, access from C++ will not be common.

The methods of the PooledPipeline object are shown in the following table.

Method | Description
Execute | Runs the components in the pipeline as configured by the LoadPipe method.
LoadPipe | Loads a pipeline configuration file (.pcf) into the pipeline.
SetLogFile | Identifies the file in which to log pipeline events.

Remarks

The PooledPipeline should be created on each Active Server Pages (ASP) page in which it is used rather thatn being held in Application or Sessions scope.

In general, use the PooledPipeline object only in production Web sites; use the MtsPipeline object when developing the site. If you use the PooledPipeline object during development, you will need to stop and restart Internet Information Services (IIS).

When you create custom poolable pipeline components, you must add the Component Object Model (COM) category, CATID_POOLABLE, to the component to make it poolable.

The PooledPipeline object is registered under COM+ as "transactions not supported." Use this pipeline where transactions are not needed. For more information about transactions and pipelines, see Pipeline Basics.


IPipeline::Execute

Use this method to run the stages in the pipeline configuration file, which was previously specified by the LoadPipe method.

Definition

HRESULT IPipeline::Execute(
long lMode,
IDispatch* pdispOrder,
IDispatch* pdispContext,
long lFlags,
long* pErrorLevel
);

Parameters

lMode

[in] A long integer indicating the mode in which to run the pipeline. This parameter is provided only for backward compatibility with previous versions of Commerce Server. Specify 1 for this parameter.

pdispOrder

[in] A pointer to the IDispatch interface of the business object (typically a dictionary object or an order form object).

pdispContext

[in] A pointer to the IDispatch interface of the secondary business object (typically a context dictionary).

lFlags

[in] An unused long integer parameter. Must be set to zero (0).

pErrorLevel

[out,retval] A pointer to a long that returns the warning level.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

In addition, the pErrorLevel parameter is set to one of the following three values:

Value | Description
1 | The pipeline ran successfully.
2 | A pipeline component raised a warning. Generally, these are basket or user errors that would be reported to the user through the ASP page.
3 | A pipeline component failed to run.

Remarks

The pErrorLevel parameter points to valid data only if the method completes successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

PooledPipeline Object

IPipeline::LoadPipe

IPipeline::SetLogFile


IPipeline::LoadPipe

Use this method to load a pipeline configuration file (.pcf) into a pipeline.

Definition

HRESULT IPipeline::LoadPipe(
BSTR pszFileName
);

Parameters

pszFileName

[in] A BSTR containing the pipeline configuration file (.pcf) name.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The LoadPipe method must be called to initialize all pipelines.

The LoadPipe method fails if you attempt to load a pipeline configuration file that is designated to be used for transactions (for use in MtsTxPipeline or PooledTxPipeline).

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

PooledPipeline Object

IPipeline::Execute

IPipeline::SetLogFile


IPipeline::SetLogFile

Use this method to identify the file in which to log the operations of the pipeline component.

Note

  • This method is for use by developers who want to analyze pipeline configuration file information. Logging should never be enabled in a production environment: it degrades performance and compromises the security of credit card numbers in non-set transactions. The file system must be configured to allow the process running the pipeline to have write access to the specified path.

Definition

HRESULT IPipeline::SetLogFile(
BSTR pszFileName
);

Parameters

pszFileName

[in] A BSTR containing the name of the file in which to log events.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

When logging is set, the pipeline logs the pipeline components that are called and the error values each component returns. The pipeline also logs all Dictionary and SimpleList object read and write operations.

Calling this method with an empty string turns off logging.

The SetLogFile method should be called immediately before executing a pipeline.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

PooledPipeline Object

IPipeline::Execute

IPipeline::LoadPipe


PooledTxPipeline Object

Use this object to execute a Microsoft Commerce Server 2000 pipeline. The pipeline may be an Order Processing pipeline (OPP). Use in place of the PooledPipeline object where you need transactions.

The PooledTxPipeline object uses COM+ object pooling to greatly increase the loading speed of pipelines. For more information about pooled pipelines, see Pooled Pipelines.

ProgID: | Commerce.PooledTxPipeline (Externally creatable)
COM Class Name: | CPooledTxPipeline
COM Interface Name: | IPipeline
Interface ID Constant: | IID_IPipeline
Header File: | pipeline.h, mspu_guids.h
Type Library Name: | Microsoft Commerce 2000 Order Pipeline Type Library
DLL Name: | pipeline.dll
Threading Model: | Both

In C++, use the IPipeline interface to access the properties and methods of the PooledTxPipeline object.

Because this object is primarily intended for use within ASP script, access from C++ will not be common.

The methods of the PooledTxPipeline object are shown in the following table.

Method | Description
Execute | Runs the components in the pipeline as configured by the LoadPipe method.
LoadPipe | Loads a pipeline configuration file (.pcf) into the pipeline.
SetLogFile | Identifies the file in which to log pipeline events.

Remarks

The PooledTxPipeline object is registered under COM+ as "transactions required." Use this pipeline where transactions are needed. For more information about transactions and pipelines, see Pipeline Basics.

The Microsoft Distributed Transaction Coordinator (MSDTC) service must be running in order to use the PooledTxPipeline object.

To verify that the Distributed Transaction Coordinator service is running

  1. Click Start, point to Programs, point to Administrative Tools, and then click Services.

  2. Scroll to Distributed Transaction Coordinator and verify that the Status is Started.

In general, use the PooledTxPipeline object only in production Web sites; use the MtsPipeline object when developing the site. If you use the PooledTxPipeline object during development, you will need to stop and restart Internet Information Services (IIS) in order to force the .pcf files to be re-read when you change them.

The PooledPipeline object should be created on each ASP page in which it is used rather than being held in Application or Session scope.

When you create custom poolable pipeline components, you must add the Component Object Model (COM) category, CATID_POOLABLE, to the component to make it poolable.


KIPipeline::Execute

IPipeline::Execute

Use this method to run the stages in the pipeline configuration file, which was previously specified by the LoadPipe method.

Definition

HRESULT IPipeline::Execute(
long lMode,
IDispatch* pdispOrder,
IDispatch* pdispContext,
long lFlags,
long* pErrorLevel
);

Parameters

lMode

[in] A long integer indicating the mode in which to run the pipeline. This parameter is provided only for backward compatibility with previous versions of Commerce Server. Specify 1 (one) for this parameter.

pdispOrder

[in] A pointer to the IDispatch interface of the business object (typically a dictionary object or an order form object).

pdispContext

[in] A pointer to the IDispatch interface of the secondary business object (typically a context dictionary object).

lFlags

[in] An unused long integer parameter. Must be set to zero (0).

pErrorLevel

[out,retval] A pointer to a long that returns the warning level.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

In addition, the pErrorLevel parameter is set to one of the following three values:

Value | Description
1 | The pipeline ran successfully.
2 | A pipeline component raised a warning. Generally, these are basket or user errors that would be reported to the user through the ASP page.
3 | A pipeline component failed to run.

Remarks

The pErrorLevel parameter points to valid data only if the method completes successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

PooledTxPipeline Object

IPipeline::LoadPipe

IPipeline::SetLogFile


KIPipeline::LoadPipe

IPipeline::LoadPipe

Use this method to load a pipeline configuration file (.pcf) into the pipeline.

Definition

HRESULT IPipeline::LoadPipe(
BSTR pszFileName
);

Parameters

pszFileName

[in] A BSTR containing the pipeline configuration file (.pcf) name.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The LoadPipe method must be called to initialize all pipelines.

The LoadPipe method fails if you attempt to load a pipeline configuration file that is not designated to be used for transactions (for use in MtsPipeline or PooledPipeline).

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

PooledTxPipeline Object

IPipeline::Execute

IPipeline::SetLogFile


KIPipeline::SetLogFile

IPipeline::SetLogFile

Use this method to identify the file in which to log the operations of the pipeline component.

Note

  • This method is for use by developers who want to analyze pipeline configuration file information. Logging should never be enabled in a production environment: it degrades performance and could compromise the security of credit card numbers in non-set transactions. File systems must be configured to allow the process running the pipeline to have write access to the specified path.

Definition

HRESULT IPipeline::SetLogFile(
BSTR pszFileName
);

Parameters

pszFileName

[in] A BSTR containing the name of the file in which to log events.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

When logging is set, the pipeline logs the pipeline components that are called and the error values each component returns. The pipeline also logs all Dictionary and SimpleList object read and write operations.

The SetLogFile methodshould be called immediately before executing a pipeline.

Calling this method with an empty string turns off logging.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

PooledTxPipeline Object

IPipeline::Execute

IPipeline::LoadPipe


PredictorClient Object

Use this object to load an analysis model, set properties controlling the prediction context, and execute the prediction algorithm. Two types of models are supported, prediction models and segment models. Results of a prediction model are used to recommend products and supply missing profile data. Results of a segment model are used to categorize a user. Prediction models provide more accurate recommendations than segment models and the use of segment models for predictions is discouraged.

ProgID: | Commerce.PredictorClient (Externally creatable)
COM Class Name: | PredictorClient
COM Interface Name: | IPredictorClient
Interface ID Constant: | IID_IPredictorClient
Header File: | PredictorClient.h
Type Library Name: | Microsoft Commerce 2000 Predictor Client Type Library
DLL Name: | PredictorClient.dll
Threading Model: | Both

In C++, use the IPredictorClient interface to access the properties and methods of the PredictorClient object.

The properties of the PredictorClient object are shown in the following table.

Property | Type | Description
fpDataFitScore | float | Stores the Data Fit Score. This property is read-only.
fpDefaultConfidence | float | Stores the threshold for confidence in a prediction. This property is read/write.
bFailOnUnknownInputAttributes | VARIANT_BOOL | Controls the behavior of the Predict method when input attributes are unknown. This property is read/write.
fpPopularityPenalty | float | Stores the penalty applied when selecting popular items to recommend. This property is read/write.
fpRecommendScore | float | Stores the Recommendation Score. This property is read-only.
sSiteName | BSTR | Stores the site name in which the PredictorClient object is running. This property is read/write.

The methods of the PredictorClient object are shown in the following table.

Method | Description
Explain | Explains the prediction of a property in terms of the relevant property/value pairs used as input to the prediction model.
LoadModelFromDB | Loads a model from a database.
LoadModelFromFile | Loads a model from the specified file.
Predict | Predicts recommend products or missing profile data.
PredictAllSegments | Calculates the probabilities that the user belongs to each segment of a population of past users.
PredictMostLikelySegment | Calculates the segment to which the user most likely belongs.
SaveModelToFile | Saves a model to the specified file.

Remarks

Applications that need to anticipate user behavior use the PredictorClient object to load analysis models and generate predictions. The models use a specified set of partial cases as the basis for their predictions. A case is all that is known about a previous user and may contain demographic information and transactional history.

Use the PredModelBuilder object to generate new models. Use the PredictorServiceAdmin object to retrieve a list of models and model configurations. Use the PredictorServiceSiteAdmin object to delete or rename models and model configurations.

Measure the effectiveness of a prediction model using the fpDataFitScore and the fpRecommendScore properties. This allows fine-tuning of the input parameters, such as SampleSize, InputAttributeFraction, and OutputAttributeFraction, when building the model.

Load a model using the LoadModelFromDB or LoadModelFromFile methods prior to using other PredictorClient methods.

For optimum performance when using a prediction model, default values for the fpDefaultConfidence and fpPopularityPenalty properties should be set in the Application_OnStart method in the global.asa file, to avoid having to explicitly set the values for every Predict method call.

See Also

Prediction Objects

Predictor Schema

PredictorServiceAdmin Object

PredictorServiceSiteAdmin Object

PredModelBuilder Object

Running the Predictor Resource


IPredictorClient::get_fpDataFitScore

The read-only fpDataFitScore property returns the Data Fit Score, measuring the effectiveness of a prediction model to fill in missing profile data.

Definition

Get method:

HRESULT IPredictorClient::get_fpDataFitScore(
float* pVal
);

Parameters

pVal

[out, retval] A pointer to a float used to return the Data Fit Score.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the following Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The Data Fit Score is automatically computed when a model is built, using a fraction of the data as test data. The amount of data to set aside for testing purposes is specified as the Measured Accuracy Sample Fraction. For more information, see Building a New Analysis Model and PredictorModels Table.

Use the Data Fit Score to test and fine-tune the input parameters for a prediction model. Known cases, taken from the input cases used to build the model, are tested against both the prediction model and a "stalking horse" model. The " stalking horse" model is a marginal model that assumes all properties are independent. An intermediate value is calculated by dividing the probability the prediction model assigns to a case in the test data by the probability the "stalking horse" model assigns to the same case. The score is the logarithm of the geometric average of these values for each output property. Thus, any score greater than zero means that the built model makes predictions that are more accurate than the "stalking horse" model.

Load the prediction model using the LoadModelFromDB or LoadModelFromFile methods prior to accessing this property.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

The pVal parameter contains valid data only if the property is accessed successfully.

See Also

PredictorClient Object

IPredictorClient::Predict


IPredictorClient::get_fpDefaultConfidence, put_fpDefaultConfidence

The read/write fpDefaultConfidence property determines the threshold below which predictions are not returned by the PredictorClient object.

Definition

Get method:

HRESULT IPredictorClient::get_fpDefaultConfidence(
float* pVal
);

Put method:

HRESULT IPredictorClient::put_fpDefaultConfidence(
float pVal
);

Parameters

pVal

[in] When putting the property, a float that contains the threshold confidence for prediction. Valid range is 0 to 100.
[out, retval] When getting the property, a pointer to a float used to return the cutoff value for prediction confidence.

Return Values

These methods return an HRESULT indicating whether or not it completed successfully. See the following Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

The following standard COM error value has a particular meaning in the context of this property.

E_INVALIDARG

The value of the property is outside the valid range of 0 to 100.

Remarks

The fpDefaultConfidence property is a threshold that determines which attributes can be shown on the recommendation list. When a prediction is made, each attribute is assigned a probability of "not missing", which in most uses will correspond to the probability that the product will be purchased. If this probability (in percentage) falls below fpDefaultConfidence, then the attribute is not shown on the recommendation list even when this probability is large relative to probabilities of the other attributes being "not missing". The property should be within the range of 0 to 100, but a value of zero (0) is recommended unless the fpPopularityPenalty property is set to zero (0).

Set a default value for this property in the global.asa file to avoid setting the value for each Predict method call.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

The pVal parameter contains valid data only if the property is accessed successfully.

See Also

PredictorClient Object

IPredictorClient::Predict


IPredictorClient::Explain

Use this method to return the properties and values from the current case that are relevant to a prediction of the specified unknown property. A score corresponding to each returned property/value pair explains the importance of each property/value pair to the prediction.

Definition

HRESULT IPredictorClient::Explain(
IDictionary* dCurrentCase,
BSTR sPropToExplain,
VARIANT* pvsavRelevantProps,
VARIANT* pvsavRelevantValues,
VARIANT* pvsavRelevantScores,
long lMaxExplanations
);

Parameters

dCurrentCase

[in] A pointer to the IDictionary interface of a Dictionary object that contains the current case.

sPropToExplain

[in, string] A BSTR that contains the name of the property to explain.

pvsavRelevantProps

[out] A pointer to a VARIANT used to return a SAFEARRAY containing the list of properties from the current case that are relevant to the prediction.

pvsavRelevantValues

[out] A pointer to a VARIANT used to return a SAFEARRAY containing the list of values corresponding to the relevant properties.

pvsavRelevantScores

[out] A pointer to a VARIANT used to return a SAFEARRAY containing the list of scores corresponding to the importance of each property towards the prediction.

lMaxExplanations

[in, optional, default value (-1)] A long that contains the maximum number of properties to return. The default value indicates to return all the properties.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

This method returns property/value/score triplets sorted in descending order by score. The higher the score, the greater the probability the unknown property is correctly predicted by the corresponding property/value pair.

Load the prediction model using the LoadModelFromDB or LoadModelFromFile methods prior to using this method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

The pvsavReleventProps, pvsavRelevantValues, and pvsavRelevantScores parameters contain valid data only if the method completes successfully.

See Also

PredictorClient Object


IPredictorClient::get_bFailOnUnknownInputAttributes, put_bFailOnUnknownInputAttributes

The read/write bFailOnUnknownInputAttributes property controls whether the Predict method continues or fails when encountering unknown input attributes.

Definition

Get method:

HRESULT IPredictorClient::get_bFailOnUnknownInputAttributes(
VARIANT_BOOL* pbVal
);

Put method:

HRESULT IPredictorClient::put_bFailOnUnknownInputAttributes(
VARIANT_BOOL pbval
);

Parameters

pbVal

[in] When putting the property, a VARIANT_BOOL that indicates whether or not the Predict method should fail on unknown input attributes. The default value is False.
[out, retval] When getting the property, a pointer to a VARIANT_BOOL indicating whether the Predict method fails on unknown input attributes.

Return Values

These methods return an HRESULT indicating whether or not it completed successfully. See the following Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

This property is used as a debugging flag. By default, the Predict method ignores unknown input attributes. Setting this property to True causes the Predict method to fail when unknown input attributes are encountered.

When debugging, set a default value for this property in the global.asa file to avoid setting the value for each Predict method call.

Load the prediction model using the LoadModelFromDB or LoadModelFromFile methods prior to accessing this property.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

The pbVal parameter contains valid data only if the property is accessed successfully.

See Also

PredictorClient Object

IPredictorClient::Predict


IPredictorClient::LoadModelFromDB

Use this method to load a model stored in a database.

Definition

HRESULT IPredictorClient::LoadModelFromDB(
BSTR sModelName,
BSTR sDWConnStr
);

Parameters

sModelName

[in] A BSTR that contains the model name.

sDWConnStr

[in] A BSTR that contains the connection information for the Data Warehouse.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

A valid model must be loaded before calling the other methods of the PredictorClient object. This model, typically in the range of 100k to 10M, must be loaded onto the local Web server to ensure a timely response to a prediction request.

The information for the model is loaded from the PredictorModels table. For more information about this table, see Predictor Schema.

The sDWConnStr parameter must be a SQL OLE DB connection string.

Use the LoadModelFromFile method to load a model from a file.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

PredictorClient Object

IPredictorClient::Predict

IPredictorClient::LoadModeFromFile


IPredictorClient::LoadModelFromFile

Use this method to load a model stored in a file.

Definition

HRESULT IPredictorClient::LoadModelFromFile(
BSTR sFilePath
);

Parameters

sFilePath

[in] A BSTR that contains the file name, extension, and path.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

A valid model must be loaded before calling the other methods of the PredictorClient object. A model is originally stored in a database and must be loaded using the LoadModelFromDB method. Once loaded, the model may be saved to a file using the SaveModelToFile method.

The file path is relative to the current working directory of the calling process.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

PredictorClient Object

IPredictorClient::Predict

IPredictorClient::LoadModelFromDB


IPredictorClient::get_fpPopularityPenalty, put_fpPopularityPenalty

The read/write fpPopularityPenalty property influences the likelihood that the Predict method recommends popular items.

Definition

Get method:

HRESULT IPredictorClient::get_fpPopularityPenalty(
float* pbVal
);

Put method:

HRESULT IPredictorClient::put_fpPopularityPenalty(
float pbVal
);

Parameters

pbVal

[in] When putting the property, a float that contains the popularity penalty value to be applied to subsequent predictions. Valid range is 0.0 to less than 1. Default is zero (0).
[out, retval] When getting the property, a pointer to a float used to return the popularity penalty value used in predictions.

Return Values

These methods return an HRESULT indicating whether or not it completed successfully. See the following Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

The following standard COM error value has a particular meaning in the context of this property.

E_INVALIDARG

The parameter pbVal = 1. The valid range is 0 to less than 1.

Remarks

Popular items are frequently purchased items that are so well known that they do not need to be recommended to a user. A higher penalty value reduces the probability that a popular item is included as a recommended product in the prediction results. The value ranges from 0.0 to less than 1.0. To maximize sales of the most popular items, the default popularity penalty of zero (0) is recommended. For applications where most of the users are familiar with many of the popular products, a value of 0.9 is appropriate.

Set a default value for this property in the Application_OnStart method in the global.asa file to avoid setting the value for each Predict method call.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

The pbVal parameter contains valid data only if the property is accessed successfully.

See Also

PredictorClient Object

IPredictorClient::Predict


IPredictorClient::Predict

Use this method to generate predictions that are used to recommend relevant products to a user, the current case, or to fill in missing profile data associated with the user.

Definition

HRESULT IPredictorClient::Predict(
IDictionary* dCurrentCase,
ISimpleList* slPropsToPredict,
VARIANT* pvsavPredictedProps
VARIANT* pvsavPredictedVals
long lMaxPredictions,
VARIANT* pvsavDetails
);

Parameters

dCurrentCase

[in] A pointer to the IDictionary interface of a Dictionary object that contains the current case.

slPropsToPredict

[in] A pointer to the ISimpleList interface of a SimpleList object that contains the names of the properties to predict.

pvsavPredictedProps

[out] A pointer to a VARIANT used to return a SAFEARRAY containing the predicted property names.

pvsavPredictedVals

[out] A pointer to a VARIANT used to return a SAFEARRAY containing the predicted property values.

lMaxPredictions

[in, optional, defaultvalue (-1)] A long that specifies the maximum number of predictions to return. The default value indicates to return all predictions.

pvsavDetails

[out, optional] Reserved for future use.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

Predictions are made using the currently loaded prediction model based on user profile and selection information contained in the current case. The predicted property/value pairs are returned sorted in descending order of likelihood.

Set the fpDefaultConfidence and fpPopularityPenalty properties and load the prediction model using the LoadModelFromDB or LoadModelFromFile methods before using the Predict method.

Default values for the fpDefaultConfidence and fpPopularityPenalty properties may be set in the Application_OnStart method in the global.asa file to avoid having to explicitly set the values for every Predict method call.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

PredictorClient Object

IPredictorClient::LoadModelFromFile

IPredictorClient::LoadModelFromDB

IPredictorClient::get_fpDefaultConfidence, put_fpDefaultConfidence


IPredictorClient::PredictAllSegments

Use this method to predict the probabilities that a particular user, the current case, belongs to each segment of a population.

Definition

HRESULT IPredictorClient::PredictAllSegments(
IDictionary* dCurrentCase,
VARIANT* pvsavSegmentNames,
VARIANT* pvsavProbabilities
);

Parameters

dCurrentCase

[in] A pointer to the IDictionary interface that contains the current case.

pvsavSegmentNames

[out] A VARIANT used to return a SAFEARRAY containing the segment names.

pvsavProbabilities

[out] A VARIANT used to return a SAFEARRAY containing the membership probabilities associated with the segment names.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The Microsoft Research Cluster Engine Data Modeler groups similar users into segments. Similar segments are further grouped into higher order collections of segments, creating a hierarchy from which to analyze trends and discover hidden correlations. The returned probability associated with each segment name indicates the probability that the current user belongs to that segment.

Load the segment model using the LoadModelFromDB or LoadModelFromFile methods prior to using this method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

The pvsavSegmentNames and pvsavProbabilities parameters contain valid data only if the method completes successfully.

See Also

PredictorClient Object


IPredictorClient::PredictMostLikelySegment

Use this method to predict the most likely segment of a population to which a user, the current case, belongs.

Definition

HRESULT IPredictorClient::PredictMostLikelySegment(
IDictionary* dCurrentCase,
VARIANT* pvarProbability,
BSTR* pbstrSegment
);

Parameters

dCurrentCase

[in] A pointer to the IDictionary interface that contains the current case.

pvarProbability

[out, optional] A pointer to a VARIANT used to return the membership probability associated with the segment name.

pbstrSegment

[out, retval] A pointer to a BSTR used to return the name of the segment most likely to contain the given case.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The Microsoft Research Cluster Engine Data Modeler groups similar users into segments. Similar segments are further grouped into higher order collections of segments, creating a hierarchy from which to analyze trends and discover hidden correlations.

This method returns the name of the segment most likely to contain the given case, and optionally, the probability that the user belongs to this segment.

Load the segment model using the LoadModelFromDB or LoadModelFromFile methods prior to using this method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

The pvarProbability and pbstrSegment parameters contain valid data only if the method completes successfully.

See Also

PredictorClient Object


IPredictorClient::get_fpRecommendScore

The read-only fpRecommendScore property returns the Recommendation Score, which measures the quality of a ranked list of recommendations returned from a prediction model.

Definition

Get method:

HRESULT IPredictorClient::get_fpRecommendScore(
float* pVal
);

Parameters

pVal

[out, retval] A pointer to a float used to return the Recommendation Score.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the following Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

Use the Recommendation Score to test and adjust the input parameters for a prediction model. Known cases, taken from the input cases used to build the model, are tested against the prediction model with one of the transactions randomly removed. A list of recommendations is returned, and the prediction is deemed successful if the removed transaction is on the list. The score is the percentage of cases in which the model was successful.

The Recommendation Score is automatically computed when a model is built, using a fraction of the data as test data. The amount of data to set aside for testing purposes is specified as the Measured Accuracy Sample Fraction. For more information, see Building a New Analysis Model and PredictorModels Table.

Load the prediction model using the LoadModelFromDB or LoadModelFromFile methods prior to accessing this property.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

The pVal parameter contains valid data only if the property is accessed successfully.

See Also

PredictorClient Object

IPredictorClient::Predict


IPredictorClient::SaveModelToFile

Use this method to save the currently loaded model to a file.

Definition

HRESULT IPredictorClient::SaveModelToFile(
BSTR sFilePath
);

Parameters

sFilePath

[in] A BSTR that contains the file name, extension, and path relative to the working directory of the calling process.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The directory where the file is saved must exist prior to the call.

A model must be loaded using the LoadModelFromDB or LoadModelFromFile methods before using the SaveModelToFile method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

PredictorClient Object

IPredictorClient::LoadModelFromFile

IPredictorClient::LoadModelFromDB


IPredictorClient::get_sSiteName, put_sSiteName

The read/write sSiteName property contains the name of the site in which the PredictorClient object is running.

Definition

Get method:

HRESULT IPredictorClient::get_sSiteName(
BSTR* psSiteName
);

Put method:

HRESULT IPredictorClient::put_ sSiteName(
BSTR psSiteName
);

Parameters

psSiteName

[in] When putting the property, a BSTR that contains the name of the site where the PredictorClient object will run.
[out, retval] When getting the property, a pointer to a BSTR used to return the name of the site in which the PredictorClient object is running.

Return Values

These methods return an HRESULT indicating whether or not it completed successfully. See the following Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

This property should be set in the On_Start method of the global.asa file to allow logging of performance monitoring counters to be aggregated over the site. Performance counters are specific to a given computer. If multiple sites are running on the same Web server, the counters give a combined total for all sites. Specifying a site name allows the counts from one site to be distinguished from the counts of other sites.

The following counters are available:

  • Total number of predictions made since the site was initialized.

  • Average time per prediction.

  • Total number of model loads from files.

  • Total number of model loads from a database.

The counters can be accessed in Microsoft Windows 2000 by clicking Control Panel, double-clicking Administrative Tools, and then double-clicking Performance. The counters can also be accessed programmatically through the performance APIs described in the Windows 2000 Platform SDK.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

The psSiteName parameter contains valid data only if the property is accessed successfully.

See Also

PredictorClient Object

IPredictorClient::Predict


PredictorServiceAdmin Object

Use this object to retrieve a list of the available analysis models, a list of the available model configurations, and the date the Predictor resource was last started.

ProgID: | Commerce.PredictorServiceAdmin (Externally creatable)
COM Class Name: | PredictorServiceAdmin
COM Interface Name: | IPredictorServiceAdmin
Interface ID Constant: | IID_IPredictorServiceAdmin
Header File: | PredictorService.h
Type Library Name: | Microsoft Commerce 2000 Predictor Service Type Library
EXE Name: | PredServ.exe
Threading Model: | Both

In C++, use the IPredictorServiceAdmin interface to access the properties of the object.

The properties of the PredictorServiceAdmin object are shown in the following table.

Property | Type | Description
dateLastStarted | DATE | Retrieves the date the Predictor resource was last started. This property is read-only.
slModelConfigs | ISimpleList | Retrieves a list of currently available model configurations. This property is read-only.
slModels | ISimpleList | Retrieves a list of currently available models. This property is read-only.

Remarks

The PredictorServiceSiteAdmin object provides methods for maintaining the models and model configurations. The PredictorClient object loads the appropriate model and makes the actual predictions. Generate new models by using the PredModelBuilder object.

See Also

Prediction Objects

Predictor Schema

PredictorClient Object

PredictorServiceSiteAdmin Object

PredModelBuilder Object

Running the Predictor Resource


IPredictorServiceAdmin::get_dateLastStarted

The dateLastStarted property is a read-only Date that indicates when the Predictor resource was last started.

Definition

HRESULT IPredictorServiceAdmin::get_dateLastStarted(
DATE* pdateVal
);

Parameters

pdateVal

[out, retval] A pointer to a DATE that specifies when the Predictor resource last started.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the following Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

The pDateVal parameter contains valid data only if the property is accessed successfully.

See Also

PredictorServiceAdmin Object

PredictorServiceSiteAdmin Object

PredModelBuilder Object


IPredictorServiceAdmin::get_slModelConfigs

The slModelConfigs property is a read-only SimpleList object that contains information about the available model configurations.

Definition

HRESULT IPredictorServiceAdmin::get_slModelConfigs(
ISimpleList** ppslVal
);

Parameters

ppslVal

[out, retval] The address of a pointer to the ISimpleList interface of a SimpleList object used to return the list of model configurations.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the following Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The SimpleList object, slModelConfigs, contains a Dictionary object for each model configuration. A model configuration contains information used to build a model. The following table describes the keys of the Dictionary object which are the names of the model configuration properties.

Key Name | Type | Description
DWResourceName | BSTR | Name of the Data Warehouse resource where the model configuration is defined.
ModelCfgName | BSTR | Name of the model configuration.
SiteName | BSTR | Reserved. May not appear in the dictionary.

Use the DeleteModelConfig method of the PredictorServiceSiteAdmin object to delete a model configuration.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

The ppslVal parameter contains valid data only if the property is accessed successfully.

See Also

PredictorServiceAdmin Object

PredictorServiceSiteAdmin Object

PredModelBuilder Object


IPredictorServiceAdmin::get_slModels

The slModels property is a read-only SimpleList object that contains information about the available models.

Definition

HRESULT IPredictorServiceAdmin::get_slModels(
ISimpleList** ppslVal
);

Parameters

ppslVal

[out, retval] The address of a pointer to the ISimpleList interface of a SimpleList object used to return the information about the models.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the following Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The SimpleList object, slModels, contains a Dictionary object for each available model. A model is available if a copy of it exists and is not currently being built. The keys of the Dictionary object are the names of the model properties as listed in the PredictorModels Table. The following table describes a few of these keys. For information about the remaining keys, see PredictorModels Table.

Key Name | Type | Description
DWResourceName | BSTR | Name of the Data Warehouse resource where the model configuration is defined.
ModelCfgName | BSTR | Name of the model configuration used to build the model.
ModelName | BSTR | Model name.

Use the Start method of the PredModelBuilder object to create a new model.

Use the DeleteModel method of the PredictorServiceSiteAdmin object to delete a model.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

The ppslVal parameter contains valid data only if the property is accessed successfully.

See Also

PredictorServiceAdmin Object

PredictorServiceSiteAdmin Object

PredModelBuilder Object


PredictorServiceSiteAdmin Object

Use this object to manage analysis models and model configurations.

ProgID: | Commerce.PredictorSiteAdmin (Externally creatable)
COM Class Name: | PredictorServiceSiteAdmin
COM Interface Name: | IPredictorServiceSiteAdmin
Interface ID Constant: | IID_IPredictorServiceSiteAdmin
Header File: | PredictorService.h
Type Library Name: | Microsoft Commerce 2000 Predictor Service Type Library
EXE Name: | PredServ.exe
Threading Model: | Both

In C++, use the IPredictorServiceSiteAdmin interface to access the properties and methods of the PredictorServiceSiteAdmin object.

Because this object is primarily intended for use within ASP script, access from C++ will not be common.

The properties of the PredictorServiceSiteAdmin object are shown in the following table.

Property | Type | Description
lCaseCount | long | Retrieves the number of cases used by a model configuration. This property is read-only.
dModelInfo | IDictionary | Retrieves information on the specified model. This property is read-only.
SegmentLabels | VARIANT | Stores the segment labels for a segment model. This property is read/write.

The methods of the PredictorServiceSiteAdmin object are shown in the following table.

Method | Description
DeleteModel | Deletes the specified predictor model.
DeleteModelConfig | Deletes the specified model configuration.
GenerateSegmentList | Generates a list of members of a segment.
Init | Initializes the server.
RenameModel | Renames a predictor model.
RenameModelConfig | Renames a model configuration.

Remarks

An analysis model summarizes dependency relationships among attributes found in data. A model configuration contains information used to build the analysis model.

Two types of analysis models are available. A prediction model is used to produce a ranked list of recommendations or to fill in a missing user profile attribute. A segment model is used to group similar users into segments of a population.

The PredictorServiceAdmin object contains lists of the available models and model configurations. The PredictorClient object loads the appropriate model and makes the actual predictions. The generation of new models is controlled by the PredModelBuilder object.

See Also

Prediction Objects

Predictor Schema

PredictorClient Object

PredictorServiceAdmin Object

PredModelBuilder Object

Running the Predictor Resource


IPredictorServiceSiteAdmin::get_lCaseCount

The lCaseCount property is a read-only Long that contains a count of the number of cases used by a model configuration.

Definition

HRESULT IPredictorServiceSiteAdmin::get_lCaseCount(
BSTR sConfigName,
long* plCaseCount
);

Parameters

sConfigName

[in] A BSTR that contains the model configuration name.

plCaseCount

[out, retval] A pointer to a long that contains the number of cases for the specified model configuration.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the following Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

A case is the set of information known about a particular user. This information might include user profile data, purchase history, URL click history, or other user associated data. The number of cases used to build a model affects the accuracy of that model. In general, predictions will be more accurate when many cases are available for the model. However, the time necessary to build the model increases with the number of cases in the configuration and increases in accuracy are slight when the number of cases becomes very large (typically, greater than 50,000 cases).

Use the slModelConfigs property of the PredictorServiceAdmin object to retrieve a list of the available model configurations.

Connect to the Data Warehouse using the Init method before accessing this property.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

The plCaseCount parameter contains valid data only if the property is accessed successfully.

See Also

PredictorServiceAdmin Object

PredictorServiceSiteAdmin Object

PredModelBuilder Object


IPredictorServiceSiteAdmin::DeleteModel

Use this method to delete the specified model.

Definition

HRESULT IPredictorServiceSiteAdmin::DeleteModel(
BSTR sModelName
);

Parameters

sModelName

[in] A BSTR that contains the name of the model to delete.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the following Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

Use the slModels property of the PredictorServiceAdmin object to retrieve a list of the available models.

Deleting a model causes its entry in the PredictorModels table in the Data Warehouse to be removed.

Passing an empty string for the model name will result in an invalid argument error.

Connect to the Data Warehouse using the Init method before calling the DeleteModel method.

Use the Start method of the PredModelBuilder object to create a new model.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

PredictorServiceAdmin Object

PredictorServiceSiteAdmin Object

PredModelBuilder Object


IPredictorServiceSiteAdmin::DeleteModelConfig

Use this method to delete the specified model configuration.

Definition

HRESULT IPredictorServiceSiteAdmin::DeleteModelConfig(
BSTR sModelConfigName
);

Parameters

sModelConfigName

[in] A BSTR that contains the name of the model configuration to delete.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the following Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

Use the slModelConfigs property of the PredictorServiceAdmin object to retrieve a list of the available model configurations.

Passing an empty string for the model configuration name will result in an invalid argument error.

Deleting a model configuration causes its entries in the PredictorModelCfgs and PredictorDataTables tables in the Data Warehouse to be removed, as well as the Attributes table it references. No case data is deleted.

Caution

  • For this release of Microsoft Commerce Server 2000, the user must directly modify tables in the Data Warehouse to create a new model configuration. No API function is provided.

Connect to the Data Warehouse using the Init method before calling the DeleteModelConfig method.For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

PredictorServiceAdmin Object

PredictorServiceSiteAdmin Object

PredModelBuilder Object


IPredictorServiceSiteAdmin::get_dModelInfo

The dModelInfo property is a read-only Dictionary object that contains information on the specified model.

Definition

HRESULT IPredModelBuilder::get_dModelInfo(
BSTR sModelName,
IDictionary** ppdictInfo
);

Parameters

sModelName

[in] A BSTR that contains the model name.

ppdictInfo

[out, retval] The address of a pointer to the IDictionary interface of a Dictionary object used to retrieve the information on the specified model.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the following Error Values section for more details. The IErrorInfo interface provides more specific error information.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The keys of the returned Dictionary object are the names of the model properties as listed in the PredictorModels Table. The following table describes a few of these keys. For information about the remaining keys, see PredictorModels Table.

Key Name | Type | Description
DWResourceName | BSTR | Name of the Data Warehouse resource where the model configuration is defined.
ModelCfgName | BSTR | Name of the model configuration used to build the model.
ModelName | BSTR | Model name.

Connect to the Data Warehouse using the Init method before accessing this property.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

The ppdictInfo parameter contains valid data only if the property is accessed successfully.

See Also

PredictorServiceAdmin Object

PredictorServiceSiteAdmin Object

PredModelBuilder Object


IPredictorServiceSiteAdmin::GenerateSegmentList

Use this method to generate a list of the members of a segment.

Definition

HRESULT IPredictorServiceSiteAdmin::GenerateSegmentList(
 BSTR sLMConn,
BSTR sTableName,
BSTR sModelName,
BSTR sSegmentName
double fpMinProbability

);

Parameters

sLMConn

[in] A BSTR that specifies the connection information for the ListManager object.

sTableName

[in] A BSTR that specifies the name of the table to store the list of segment members.

sModelName

[in] A BSTR that specifies the name of the segment model to use.

sSegmentName

[in] A BSTR that specifies the name of the segment to export.

fpMinProbability

[in] A double that specifies the minimum probability associated with a segment member for that member to be exported. The valid range is between 0 and 1.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the following Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

This method is provided for use by the ListManager object and should not be called independently. The CreateFromSegment method of the ListManager object calls this method and creates the list. For more information, see IListManager::CreateFromSegment.

Passing an empty string for the model name results in an empty list.

If the segment name, sSegmentName, does not exist or is the name of a segment group, an empty list is generated. No error is returned for this case.

Connect to the Data Warehouse using the Init method before calling the GenerateSegmentList method.

A segment model classifies groups of users into segments of users with similar user properties. Similar segments are further grouped into higher order collections of segments.

Each user is assigned a probability of membership to each segment. The sum of the probabilities for all segments equals one for the user. If the probability of membership in a particular segment for the user is greater than fpMinProbability, the user will be included in the export list.

All members (individual cases) of the specified segment level with an associated probability greater than the value specified in the fpMinProbability attribute are stored in the named table, and then exported into the List Manager.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

PredictorServiceAdmin Object

PredictorServiceSiteAdmin Object

PredModelBuilder Object


IPredictorServiceSiteAdmin::Init

Use this method to initialize the connection to the Data Warehouse.

Definition

HRESULT IPredictorServiceSiteAdmin::Init(
BSTR sSiteName,
BSTR sDWConnStr
);

Parameters

sSiteName

[in] A BSTR that is unused. Pass in an empty string.

sDWConnStr

[in] A BSTR that contains the Data Warehouse connection string.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the following Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The models and model configurations are stored in tables in the Data Warehouse.

Initialize the connection to the Data Warehouse before any other properties or methods of the PredictorServiceSiteAdmin object are called.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

PredictorServiceAdmin Object

PredictorServiceSiteAdmin Object

PredModelBuilder Object

PredictorClient Object


IPredictorServiceSiteAdmin::RenameModel

Use this method to rename a model.

Definition

HRESULT IPredictorServiceSiteAdmin::RenameModel(
BSTR sOldModelName,
BSTR sNewModelName
);

Parameters

sOldModelName

[in] A BSTR that contains the old model name.

sNewModelName

[in] A BSTR that contains the new model name.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the following Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

The following standard COM error value has a particular meaning in the context of this method.

E_FAIL

A model with the old name could not be found, or a model with the new name already exists.

Remarks

When renaming a model, update any sites that load the model using the LoadModelFromDB method of the PredictorClient object.

The name change is made to the model entry in the PredictorModels table in the Data Warehouse.

Use the slModels property of the PredictorServiceAdmin object to retrieve a list of available models. Use the RenameModelConfig method to rename a model configuration.

Passing an empty string for either model name will result in an invalid argument error.

Connect to the Data Warehouse using the Init method before calling the RenameModel method. For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

PredictorClient Object

PredictorServiceAdmin Object

PredictorServiceSiteAdmin Object

PredModelBuilder Object


IPredictorServiceSiteAdmin::RenameModelConfig

Use this method to rename a model configuration.

Definition

HRESULT IPredictorServiceSiteAdmin::RenameModelConfig(
BSTR sOldModelConfigName,
BSTR sNewModelConfigName
);

Parameters

sOldModelConfigName

[in] A BSTR that contains the old model configuration name.

sNewModelConfigName

[in] A BSTR that contains the new model configuration name.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the following Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

The following standard COM error value has a particular meaning in the context of this method.

E_FAIL

A model configuration with the old name could not be found, or a model configuration with the new name already exists.

Remarks

The name change is made to the model configuration entry in the PredictorModelCfgs table in the Data Warehouse.

Use the slModelsConfigs property of the PredictorServiceAdmin object to retrieve a list of the model configurations. Use the RenameModel method to rename a model.

Passing an empty string for the model configuration name will result in an invalid argument error.

Connect to the Data Warehouse using the Init method before calling the RenameModelConfig method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

PredictorServiceAdmin Object

PredictorServiceSiteAdmin Object

PredModelBuilder Object


IPredictorServiceSiteAdmin::get_SegmentLabels, put_SegmentLabels

The SegmentLabels property is a read/write Variant that contains the labels for a given segment model.

Definition

Get method:

HRESULT IPredictorServiceSiteAdmin::get_SegmentLabels(
BSTR sModelName,
long lDepth,
VARIANT* pvarsaLabels
);

Put method:

HRESULT IPredictorServiceSiteAdmin::put_SegmentLabels(
BSTR sModelName,
long lDepth,
VARIANT pvarsaLabels
);

Parameters

sModelName

[in] A BSTR that contains the name of the segment model.

lDepth

[in] A long that specifies the depth in the segment hierarchy from which labels are assigned or retrieved.

pvarsaLabels

[in] When putting the property, a VARIANT that contains the segment labels.
[out, retval] When getting the property, a pointer to a VARIANT used to return the segment labels.

Return Values

These methods return an HRESULT indicating whether or not they completed successfully. See the following Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

A segment model classifies groups of users into segments of users with similar user properties. Similar segments are grouped into higher order collections of segments, creating a hierarchy. When the segments are first generated they are generically labeled (for example, Segment4 or Group2). Rename the labels to better identify the different groups.

Valid values for the lDepth parameter are -1 (returns all segments) and 2 or greater.

Connect to the Data Warehouse using the Init method before accessing this property.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

The pvarsaLabels parameter contains valid data only if the property is accessed successfully.

See Also

PredictorServiceAdmin Object

PredictorServiceSiteAdmin Object

PredModelBuilder Object


PredModelBuilder Object

Use this object to control the creation of analysis models using multiple prioritized build threads.

ProgID: | Commerce.PredictorModelBuilder (Externally creatable)
COM Class Name: | PredModelBuilder
COM Interface Name: | IPredModelBuilder
Interface ID Constant: | IID_IPredModelBuilder
Header File: | PredictorService.h
Type Library Name: | Microsoft Commerce 2000 Predictor Service Type Library
EXE Name: | PredServ.exe
Threading Model: | Both

In C++, use the IPredModelBuilder interface to access the properties and methods of the PredModelBuilder object.

The properties of the PredModelBuilder object are shown in the following table.

Property | Type | Description
dModelInfo | IDictionary | Retrieves information on the specified running model. This property is read-only.
Priority | enum | Stores the build thread priority. This property is read/write.
slRunningModels | ISimpleList | Retrieves a list of running models. This property is read-only.
Status | enum | Indicates the build thread status. This property is read-only.

The methods of the PredModelBuilder object are shown in the following table.

Method | Description
Pause | Pauses a running build thread.
Resume | Resumes a paused build thread.
Start | Sets the thread identifier for a build and starts a new build thread.
Stop | Stops a running build thread.
StopAllBuilds | Stops all currently running build threads.

Remarks

Two types of analysis models are available in Microsoft Commerce Server 2000. A Prediction model is a collection of decision trees (called a dependency net) and is used either to produce a ranked list of recommendations, such as products to advertise, or to fill in missing user profile information, such as age. A Segment model is based on the process of clustering (segmentation) and is used to group similar users into segments of a population.

An analysis model is associated with a model configuration. More than one analysis model can be associated with the same model configuration. The model configuration contains attribute and case information used to build the analysis model. A case is all the information known about a user, such as profile data and transaction data. A typical model uses between 10,000 and 20,000 cases with a resulting size of between 100 kilobytes (KB) and 10 megabytes (MB).

The PredictorServiceAdmin object contains lists of the available analysis models and model configurations. The PredictorServiceSiteAdmin object provides methods for maintaining the analysis models and model configurations. The PredictorClient object loads the appropriate analysis model and makes the actual prediction.

The generation of an analysis model occurs in an individual build thread. A single instance of the PredModelBuilder object may control multiple simultaneous build threads. If a problem occurs in a build thread, that specific thread may be paused or terminated.

See Also

Prediction Objects

Predictor Schema

PredictorClient Object

PredictorServiceAdmin Object

PredictorServiceSiteAdmin Object

Running the Predictor Resource


IPredModelBuilder::get_dModelInfo

The dModelInfo property is a read-only Dictionary object that contains information on the specified running model.

Definition

HRESULT IPredModelBuilder::get_dModelInfo(
long lBuildID,
IDictionary** ppdictVal
);

Parameters

lBuildID

[in] A long that contains the build identifier used to select a specific build thread.

ppdictVal

[out, retval] The address of a pointer to the IDictionary interface of a Dictionary object.

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the following Error Values section for more details. The IErrorInfo interface provides more specific error information.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The keys of this dictionary are the build parameters of the running model. For information on the build parameters, see PredictorModels Table.

Initiate the build thread using the Start method before you access the thread using the dModelInfo property.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

The ppdictVal parameter contains valid data only if the property is accessed successfully.

See Also

PredModelBuilder Object

IPredModelBuilder::Start

IPredModelBuilder::Stop


IPredModelBuilder::Pause

Use this method to suspend the model build thread.

Definition

HRESULT IPredModelBuilder::Pause(
long lBuildID
);

Parameters

lBuildID

[in] A long that contains the build thread identifier.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the following Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The build thread identifier is returned by the Start method when a model build is initiated.

Use the Resume method to resume the paused build thread.

Use the Stop method to stop the execution of the build thread. A stopped thread may not be resumed. The thread must be restarted with the Start method.

Use the Status property to check the current status of a model build.

See Also

PredModelBuilder Object

IPredModelBuilder::Start

IPredModelBuilder::Resume

IPredModelBuilder::Stop

IPredModelBuilder::get_Status

IPredModelBuilder::get_Priority, put_Priority


IPredModelBuilder::get_Priority, put_Priority

The Priority property is a read/write ePredBuildPriority enumerated type. This property stores the priority of a build thread.

Definition

Get method:

HRESULT IPredModelBuilder::get_Priority(
long lBuildID,
ePredBuildPriority* pePriority
);

Put method:

HRESULT IPredModelBuilder::put_Priority(
long lBuildID,
ePredBuildPriority pePriority
);

Parameters

lBuildID

[in] A long that contains the build identifier.

pePriority

[in] When putting the property, an ePredBuildPriority enumerated priority level.
[out, retval] When getting the property, a pointer to the ePredBuildPriority enumerated priority level for the build.

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the following Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

Change this property to raise or lower the priority of the build thread depending on how quickly the build is needed.

The following table defines the possible values for the ePredBuildPriority enumerated priority levels. Absolute thread priority is not supported. These priority values are relative to the spawning thread.

Name | Value | Description
PriLowest | -2 | Lowest priority.
PriBelowNormal | -1 | Lower priority.
PriNormal | 0 | Normal priority.
PriAboveNormal | 1 | Higher priority.
PriHighest | 2 | Highest priority.

Initiate the build thread with the Start method before you access the Priority property.

Use the Pause method to temporarily suspend execution of equal or higher priority threads when a particular build thread is time-critical. Threads are executed round robin for each priority level. Threads with lower priorities are not executed until all the threads with a higher priority have executed.

See the Microsoft Developer Network (MSDN) documentation for the system SetThreadPriority method for more information about thread scheduling.

The Priority method does not support the THREAD_PRIORITY_REALTIME priority.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

The pePriority parameter contains valid data only if the property is accessed successfully.

See Also

PredModelBuilder Object

IPredModelBuilder Start

IPredModelBuilder Pause


IPredModelBuilder::Resume

Use this method to resume the execution of a build thread suspended by the Pause method.

Definition

HRESULT IPredModelBuilder::Resume(
long lBuildID
);

Parameters

lBuildID

[in] A long that contains the identifier of the paused build thread.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the following Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The build thread identifier is returned by the Start method when a model build is initiated.

Use the Status property to determine if a build thread is running or paused.

See Also

PredModelBuilder Object

IPredModelBuilder::Start

IPredModelBuilder::Pause

IPredModelBuilder::Stop

IPredModelBuilder::get_Status


IPredModelBuilder::get_slRunningModels

The slRunningModels property is a read-only SimpleList object that contains information on the active (running and paused) model build threads.

Definition

HRESULT IPredModelBuilder::get_slRunningModels(
ISimpleList** ppslVal
);

Parameters

ppslVal

[out, retval] The address of a pointer to the ISimpleList interface for the SimpleList object used to return the infomation on the active model build threads.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the following Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The SimpleList object, slRunningModels, contains a Dictionary object for each running model. The keys of the Dictionary object are the names of the model properties as listed in the PredictorModels Table except for the properties dependent on a successful finished build. The properties that are unavailable are: DateCreated, DataFitScore, RecommendScore, and BuildTime. After a successful build, these properties are available through the slModels property of the PredictorServiceAdmin object or the dModelInfo property of the PredictorServiceSiteAdmin object. The following table describes a few of the keys contained in the Dictionary object. For information about the remaining keys, see PredictorModels Table.

Key Name | Type | Description
DWResourceName | BSTR | Name of the Data Warehouse resource where the model configuration is defined.
ModelCfgName | BSTR | Name of the model configuration used to build the model.
BuildID | long | The ID of the build thread.
ModelName | BSTR | Model name.

Use the Status property to check the status of a specific model build thread.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

The ppslVal parameter contains valid data only if the property is accessed successfully.

See Also

IPredictorServiceAdmin::get_slModels

IPredictorServiceSiteAdmin::get_dModelInfo

PredModelBuilder Object

IPredModelBuilder::Start

IPredModelBuilder::Stop

IPredModelBuilder::StopAllBuilds

IPredModelBuilder::get_Status


IPredModelBuilder::Start

Use this method to create a new model build thread.

Definition

HRESULT IPredModelBuilder::Start(
BSTR sDWConnStr,
BSTR sSiteName,
BSTR sConfigName,
BSTR sModelName,
BSTR sXMLBuildParams,
VARIANT_BOOL bOverWrite,
long* plBuildID
);

Parameters

sDWConnStr

[in] A BSTR that contains the connection information for the data warehouse.

sSiteName

[in] A BSTR that is not used. Pass an empty string.

sConfigName

[in] A BSTR that contains the model configuration name.

sModelName

[in] A BSTR that contains the model name.

sXMLBuildParams

[in] A BSTR that contains the run-time build parameters for the model in XML format.

bOverWrite

[in] A VARIANT_BOOL that indicates whether to overwrite the model if it already exists.

plBuildID

[out, retval] A pointer to a long that contains the identifier for the new build thread.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the following Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

The following standard COM error value has a particular meaning in the context of this method.

E_FAIL

The overwrite flag is False, and the specified model already exists or the build thread failed.

Remarks

For information on the run-time build parameters contained in the sXMLBuildParams parameter, see PredictorModels Table. The sXMLBuildParams parameter must be passed in as the return value of the SaveXML method of the IPersistXML interface of a Dictionary object containing the build parameters. For an example of this technique, see Code to Build a New Model.

Connect to the data warehouse to access the model configuration.

Associating the site name with the PredModelBuilder object allows logging of performance monitoring counters to be aggregated over the site. See the PredictorClient object for more information.

Use the returned identifier for all subsequent access to the build thread.

If a model with the same name already exists and the overwrite parameter is False, the Start method fails.

The priority of a build thread may be set using the Priority property.

Use the Status property to check the status of a build thread.

Use the Stop method to stop a build thread that is currently running. A stopped thread may not be resumed. The thread must be restarted with the Start method.

Use the Pause method to temporarily suspend the execution of a build thread. Use the Resume method to resume execution of the suspended thread.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

The plBuildID parameter contains valid data only if the method completes successfully.

See Also

PredModelBuilder Object

IPredModelBuilder::Pause

IPredModelBuilder::Resume

IPredModelBuilder::Stop

IPredModelBuilder::get_Status

IPredModelBuilder::get_Priority, put_Priority

PredictorClient Object


IPredModelBuilder::get_Status

The Status property is a read-only ePredBuildStatus enumerated type. This property indicates the current status of a model build thread.

Definition

HRESULT IPredModelBuilder::get_Status(
long lBuildID,
ePredBuildStatus* peStatus
);

Parameters

lBuildID

[in] A long that contains the build identifier used to select a specific build thread.

peStatus

[out, retval] A pointer to an ePredBuildStatus enumerated type that indicates the status of the specified thread.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the following Error Values section for more details. The IErrorInfo interface provides more specific error information.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The following table defines the possible values for the ePredBuildStatus enumerated build states.

Name | Value | Description
PredBldRunning | 0 | Is currently running.
PredBldPaused | 1 | Is paused.
PredBldShuttingDown | 2 | Is shutting down in response to the Stop method.

BuildIDs become invalid when a build is finished, either successfully or due to failure. For status information on finished builds, view the event log.

Initiate the build thread using the Start method before you access the thread using the Status property.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

The peStatus parameter contains valid data only if the property is accessed successfully.

See Also

PredModelBuilder Object

IPredModelBuilder::Start

IPredModelBuilder::Stop


IPredModelBuilder::Stop

Use this method to stop execution of a specific model build thread.

Definition

HRESULT IPredModelBuilder::Stop(
long lBuildID
);

Parameters

lBuildID

[in] A long that identifies the model build thread.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the following Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

The following standard COM error value has a particular meaning in the context of this method.

E_FAIL

The build ID was invalid or the status of the build thread was neither running nor paused.

Remarks

The build thread identifier is returned by the Start method when a model build is initiated.

The Stop method sets a flag that signals the data modeler for the specified build thread to stop when it is ready. The data modeler checks the flag each time it updates progress information. If the flag is set, the data modeler ends thread execution and performs necessary clean-up operations.

Use the Status property to access the current status of a build thread. If the data modeler has not completed the thread termination, the build thread status is PredBldShuttingDown.

After the thread terminates, the build identifier no longer indicates a valid build thread. A stopped thread may not be resumed. The thread must be restarted with the Start method.

Use the StopAllBuilds method to halt execution of all build threads associated with the PredModelBuilder object.

See Also

PredModelBuilder Object

IPredModelBuilder::Start

IPredModelBuilder::get_Status

IPredModelBuilder::StopAllBuilds


IPredModelBuilder::StopAllBuilds

Use this method to stop execution of all model build threads associated with the PredModelBuilder object.

Definition

HRESULT IPredModelBuilder::StopAllBuilds(
);

Parameters

None.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the following Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The StopAllBuilds method sets a flag that signals each build thread to stop when it is ready. If the flag is set for a build thread, the data modeler for that thread ends thread execution and performs necessary clean-up operations.

Use the Status property to access the current status of a build thread. If a data modeler has not completed thread termination, the thread status for the modeler is PredBldShuttingDown. After the thread terminates, the build identifier no longer indicates a valid build thread. A stopped thread may not be resumed. The thread must be restarted with the Start method.

Use the Stop method to stop a specific build thread.

See Also

PredModelBuilder Object

IPredModelBuilder::Start

IPredModelBuilder::get_Status

IPredModelBuilder::Stop


Product Object

Use this object to work with products and variants in a catalog.

ProgID: | Dependent (See Remarks for more information)
COM Class Name: | Product
COM Interface Name: | IProduct
Interface ID Constant: | IID_IProduct
Header File: | Catalog.h, mspu_guids.h
Type Library Name: | Microsoft Commerce 2000 Catalog Type Library
DLL Name: | Catalog.dll
Threading Model: | Both

In C++, use the IProduct interface to access the properties and methods of the Product object.

Because this object is primarily intended for use within ASP script, access from C++ will not be common.

The properties of the Product object are shown in the following table.

Property | Type | Description
AncestorCategories | _Recordset | Contains a recordset of category names that exist anywhere above this product, and that directly or indirectly contain this product in the hierarchy. This property is read-only.
CatalogName | BSTR | Contains the name of the catalog of which this Product object is a member. This property is read-only.
GetProductProperties | _Recordset | Contains a recordset containing the property values for this product. This property is read-only.
ParentCategories | _Recordset | Contains a recordset of categories that directly contain this product. This property is read-only.
PricingCategory | BSTR | Contains the name of the pricing category for this product. This property is read/write.
ProductID | BSTR | Contains the unique ID for this product. This property is read-only.
RelatedCategories | _Recordset | Contains a recordset that describes all of the categories that are related to this product. This property is read-only.
RelatedProducts | _Recordset | Contains a recordset that describes all of the products that are related to this product. This property is read-only.
Variants | _Recordset | Contains a recordset that describes all of the variants of this product, if any. This property is read-only.

The methods of the Product object are shown in the following table.

Method | Description
AddRelationshipToCategory | Adds a relationship to a specified category from this product.
AddRelationshipToProduct | Adds a relationship to another specified product from this product.
CreateVariant | Creates a new product variant.
DeleteVariant | Deletes a product variant.
GetVariantProperties | Returns the properties of a specified product variant.
RemoveRelationshipToCategory | Removes the specified relationship between this product and the specified category.
RemoveRelationshipToProduct | Removes the specified relationship between this product and the specified product.
SetProductProperties | Sets the properties for this product and all its variants.
SetVariantProperties | Sets the properties for variants of this product.

Remarks

The Product object is a dependent object. Obtain a pointer to the IProduct interface by calling one of the following methods:

  • IProductCatalog::CreateProduct

  • IProductCatalog::GetProduct


IProduct::AddRelationshipToCategory

Use this method to add a relationship to a specified category from this product.

Definition

HRESULT IProduct::AddRelationshipToCategory(
BSTR strRelatedCategoryName,
BSTR strRelationshipName,
VARIANT strRelationshipDescription
);

Parameters

strRelatedCategoryName

[in] A BSTR that contains the name of the category to which a relationship is to be added.

strRelationshipName

[in] A BSTR that contains a name for the relationship.

strRelationshipDescription

[in, optional] A VARIANT that optionally contains a description for the relationship.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_CATEGORY_DOESNT_EXIST | 0x8898001C | The specified category did not exist.
E_CAT_INVALID_RELATION | 0x88980039 | The specified relationship was invalid. For example, a category or product cannot be related to itself.
E_CAT_INVALID_RELATION_DESC | 0x88980055 | The relationship description exceeded 256 characters.
E_CAT_INVALID_RELATION_NAME | 0x88980054 | The relationship name exceeded 128 characters.
E_CAT_RELATIONSHIP_EXISTS | 0x88980033 | The specified relationship already existed.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The new relationship must have a name, which you specify in the strRelationshipName parameter. It may also optionally have a description, which you can specify in the strRelationshipDescription parameter.

More than one relationship may be created between the same product and category, however in this case each relationship created must be given a unique name.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Product Object

IProduct::AddRelationshipToProduct

IProduct::RemoveRelationshipToCategory


IProduct::AddRelationshipToProduct

Use this method to add a relationship to a specified product from this product.

Definition

HRESULT IProduct::AddRelationshipToProduct(
VARIANT varRelatedProductID,
BSTR strRelationshipName,
VARIANT strRelationshipDescription
);

Parameters

varRelatedProductID

[in] A VARIANT that contains the ID of the related product.

strRelationshipName

[in] A BSTR that contains the name of the relationship.

strRelationshipDescription

[in, optional] A VARIANT that optionally contains a description for the relationship.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_INVALID_RELATION | 0x88980039 | The specified relationship was invalid. For example, a product cannot be related to itself.
E_CAT_INVALID_RELATION_DESC | 0x88980055 | The relationship description exceeded 256 characters.
E_CAT_INVALID_RELATION_NAME | 0x88980054 | The relationship name exceeded 128 characters.
E_CAT_PRODUCT_DOESNT_EXIST | 0x8898001E | The specified product ID did not exist.
E_CAT_RELATIONSHIP_EXISTS | 0x88980033 | The specified relationship already existed.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The new relationship must have a name, which you specify in the strRelationshipName parameter. It may also optionally have a description, which you can specify in the strRelationshipDescription parameter.

More than one relationship may be created between the same two products, however in this case each relationship created must be given a unique name.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Product Object

IProduct::AddRelationshipToCategory

IProduct::RemoveRelationshipToProduct


IProduct::get_AncestorCategories

The AncestorCategories property is a read-only Recordset object that contains the names of categories that exist anywhere above this product in the hierarchy.

Definition

HRESULT IProduct::get_AncestorCategories(
_Recordset** AncestorCategories
);

Parameters

AncestorCategories

[out, retval] The address of a pointer to a _Recordset object used to return the ancestor categories.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_CIRCULAR_REFERENCE | 0x88980037 | Circular referencing is not supported. A circular reference would put a category in more than one place in the hierarchy.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The AncestorCategories parameter contains valid data only if the property was accessed successfully.

The AncestorCategories property is a Recordset object with a single 128-character field, named Name.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Product Object

IProduct::get_ParentCategories


IProduct::get_CatalogName

The CatalogName property is a read-only String that contains the name of the catalog within which this product exists.

Definition

HRESULT IProduct::get_CatalogName(
BSTR* CatalogName
);

Parameters

CatalogName

[out, retval] A BSTR used to return the catalog name.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The CatalogName parameter contains valid data only if the property was accessed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Product Object


IProduct::CreateVariant

Use this method to create a new product variant of the current product. Only product specifc attributes will be set in the new variant.

Definition

HRESULT IProduct::CreateVariant(
VARIANT varProductVariantID,
_Recordset** ppRSProductVariant
);

Parameters

varProductVariantID

[in] A VARIANT that contains the unique ID of the product variant.

ppRSProductVariant

[out, retval] A pointer to a Recordset object used to return the product variant.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_BLANK_VARIANT | 0x8898004F | A blank value was specified for the VariantID.
E_CAT_CATALOG_DOESNT_SUPPORT_VARIANTS | 0x88980032 | This catalog does not support product variants. This is determined when the catalog is created and cannot be changed.
E_CAT_INVALID_VARIANTID | 0x8898005C | The VariantID exceeded 256 characters in length.
E_CAT_INVALIDVALUE_FOR_PROPERTY 0x88980038 An invalid value was specified for one of the product properties.

This error can be due to:

  • One of the values in the recordset does not satisfy the requirements of the minimum value/maximum value attributes set for the properties.

  • An enumeration property has a value that is not defined in its list of legal values.

  • Strings exceed the maximum length defined for the property or are shorter than the minimum length.
E_CAT_INVALIDVALUE_FOR_VARIANTID 0x8898004D An invalid value was specified for the VariantID.

This error can be due to the value of the VariantId being out of range.
E_CAT_NO_VARIANTS_UNDER_PRODUCT | 0x88980051 | This product does not support variants. Variants cannot be created under a regular product.
E_CAT_PRODUCT_DOESNT_EXIST | 0x8898001E | This product has been removed from the catalog.
E_CAT_VARIANT_EXISTS | 0x88980026 | The specified variant already existed.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The ppRSProductVariant parameter contains valid data only if the property was accessed successfully.

The value and type of the varProductVariantID parameter must be valid for the property specified as the unique ID for product variants. This property, strProductVariantID, is specified when a catalog is created.

If the catalog created does not support variants, that is strProductVariantID was not specified on catalog creation, an error is returned.

Upon successful completion, the method returns an ActiveX Data Object (ADO) recordset that contains fields for all the properties defined for the new product-variant and an integer field named oid. The oid field is for internal use and should not be updated. The returned recordset is updateable, but disconnected. In order to modify the variant properties, pass this recordset to the SetVariantProperties method.

The product-variants inherit the properties that are present in the product definition. Values for non variant-specific product properties are propagated from the Product object down to the variants, but values for variant-specific properties must be explicitly set for each variant.

The variant ID value should be unique within the product family. There can be two product variants with same variant IDs within the same catalog, as long as they are in different product families and the unique Product identifier and the unique Variant identifier are different.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Product Object

IProduct::DeleteVariant

IProduct::SetVariantProperties


IProduct::DeleteVariant

Use this method to delete the specified product variant.

Definition

HRESULT IProduct::DeleteVariant(
VARIANT varVariantID
);

Parameters

varVariantID

[in] A VARIANT that contains the unique ID of the variant.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_CATALOG_DOESNT_SUPPORT_VARIANTS | 0x88980032 | This catalog does not support product variants. This is determined when the catalog is created and cannot be changed.
E_CAT_VARIANT_DOESNT_EXIST | 0x8898001F | Variant did not exist.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Product Object

IProduct::CreateVariant


IProduct::get_GetProductProperties

The GetProductProperties property is a read-only recordset that contains the properties of this Product object.

Definition

HRESULT IProduct::get_GetProductProperties(
_Recordset** GetProductProperties
);

Parameters

GetProductProperties

[out, retval] The address of a pointer to a _Recordset object used to return the properties of this product.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_PRODUCT_DOESNT_EXIST | 0x8898001E | This product has been deleted.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The GetProductProperties parameter contains valid data only if the property was accessed successfully.

The returned single-row recordset contains all the fields defined for the product definition as well as all the common fields in the CatalogProduct Recordset.

The recordset returned is updateable, but disconnected. To modify the product properties, pass this recordset to the SetProductProperties method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Product Object

IProduct::SetProductProperties


IProduct::GetVariantProperties

Use this method to retrieve the properties for a specified product variant.

Definition

HRESULT IProduct::GetVariantProperties(
VARIANT varProductVariantID,
_Recordset** ppRSProductVariant
);

Parameters

varProductVariantID

[in] A VARIANT that contains the unique ID of the product variant.

ppRSProductVariant

[out, retval] A pointer to a Recordset object used to return the product variant properties.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_CATALOG_DOESNT_SUPPORT_VARIANTS | 0x88980032 | This catalog does not support product variants.
E_CAT_VARIANT_DOESNT_EXIST | 0x8898001F | This product variant has been removed from the catalog.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The ppRSProductVariant parameter contains valid data only if the property was accessed successfully.

This method returns the properties of the specified product variant. If the product variant specified in the varProductVariantID parameter does not exist in the product, the method will fail.

The single-row recordset returned contains fields for all of the properties defined for variants of this product followed by the following fields:

Field | Type | Description
TimeStamp | Timestamp | None
cy_list_price | Currency | List price
oid | Integer | None

The oid field is for internal use only and should not be updated.

The recordset returned is updateable, but disconnected. To modify the product properties, pass this recordset to the SetVariantProperties method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Product Object

IProduct::SetVariantProperties


IProduct::get_ParentCategories

The ParentCategories property is a read-only recordset that contains the names of categories that directly contain this product.

Definition

HRESULT IProduct::get_ParentCategories(
_Recordset** ParentCategories
);

Parameters

ParentCategories

[out, retval] A _Recordset object used to return the parent categories.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The ParentCategories parameter contains valid data only if the property was accessed successfully.

If the product is not contained in any categories, the returned recordset will be empty, and its EOF property will be set to VARIANT_TRUE.

The returned recordset will have a single 128-character String field called Name. Each row in the recordset will contain the name of a category containing this product.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Product Object

IProduct::get_AncestorCategories


IProduct::get_PricingCategory, put_PricingCategory

The PricingCategory property is a read/write String that contains the name of the pricing category for this product.

Definition

Get method:

HRESULT IProduct::get_PricingCategory(
BSTR* PricingCategory
);SET

Put method:

HRESULT IProduct::put_PricingCategory(
BSTR PricingCategory
);

Parameters

PricingCategory

[in] When using the put method, a BSTR that contains the pricing category.
[out, retval] When using the get method, a pointer to a BSTR used to return the pricing category.

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_CATEGORY_DOESNT_EXIST | 0x8898001C | The specified category did not exist.
E_CAT_PRICING_CAT_PRICELESS | 0x8898002F | The specified category did not have a list price. Categories that do not have a list price cannot be used as a pricing category.
E_CAT_PRODUCT_DOESNT_EXIST | 0x8898001E | This product has been deleted.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The PricingCategory parameter contains valid data only if the property was accessed successfully.

Using a category as a Pricing category allows you to set the prices of multiple products by making a single change, rather than having to change the price for each product. Setting the Pricing category for a product family will also set the Pricing category for all the variants of the product family.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Product Object


IProduct::get_ProductID

The ProductID property is a read-only String that contains the unique ID for this product.

Definition

HRESULT IProduct::get_ProductID(
BSTR* ProductID
);

Parameters

ProductID

[out, retval] The address of a BSTR used to return the product ID.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The ProductID parameter contains valid data only if the property was accessed successfully.

The value of this property is a copy of the value of the IdentifyingProductProperty property of the catalog containing this product.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Product Object


IProduct::get_RelatedCategories

The RelatedCategories property is a read-only Recordset object that contains the names of categories that are related to this product.

Definition

HRESULT IProduct::get_RelatedCategories(
_Recordset** RelatedCategories
);

Parameters

RelatedCategories

[out, retval] A _Recordset used to return the related categories.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The RelatedCategories parameter contains valid data only if the property was accessed successfully.

The returned recordset contains one row for each relationship present.

The returned recordset contains the following fields:

Field Data Type Description
CategoryName String
Maximum of 128 characters 		Name of the category.
RelationshipName String
Maximum of 128 characters 		Name of the relationship.
RelationshipDescription String
Maximum of 256 characters 		Description of the relationship.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Product Object

IProduct::get_RelatedProducts

IProduct::AddRelationshipToCategory


IProduct::get_RelatedProducts

The RelatedProducts property is a read-only Recordset object that contains the names of products that are related to this product.

Definition

HRESULT IProduct::get_RelatedProducts(
_Recordset** RelatedProducts
);

Parameters

RelatedProducts

[out, retval] A _Recordset object used to return the related products.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The RelatedProducts parameter contains valid data only if the property was accessed successfully.

The recordset returned contains one row for each relationship present.

The recordset returned contains the following fields:

Field | Data Type | Description
<defined ProductID field> | Varies | The field that uniquely defines a product in this catalog.
RelationshipName String
Maximum of 128 characters 		Name of the relationship.
RelationshipDescription String
Maximum of 128 characters 		Description of the relationship.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Product Object


IProduct::RemoveRelationshipToCategory

Use this method to remove the specified relationship between the specified category and this product.

Definition

HRESULT IProduct::RemoveRelationshipToCategory(
BSTR strRelatedCategoryName,
BSTR strRelationshipName
);

Parameters

strRelatedCategoryName

[in] A BSTR that contains the name of the category that is to have its relationship to this product removed.

strRelationshipName

[in] A BSTR that contains the name of the relationship to be removed.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Product Object

IProduct::get_RelatedCategories

IProduct::AddRelationshipToCategory

IProduct::RemoveRelationshipToProduct


IProduct::RemoveRelationshipToProduct

Use this method to remove the specified relationship between the specified product and this product.

Definition

HRESULT IProduct::RemoveRelationshipToProduct(
VARIANT varRelatedProductID,
BSTR strRelationshipName
);

Parameters

varRelatedProductID

[in] A VARIANT that contains the unique ID of the product that is to have its relationship to this product removed.

strRelationshipName

[in] A BSTR that contains the name of the relationship to be removed.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Product Object

IProduct::get_RelatedProducts

IProduct::AddRelationshipToProduct

IProduct::RemoveRelationshipToCategory


IProduct::SetProductProperties

Use this method to set the properties for this product.

Definition

HRESULT IProduct::SetProductProperties(
_Recordset* pRSProduct,
VARIANT fForceUpdate
);

Parameters

pRSProduct

[in] A pointer to a Recordset object that contains the new product properties. This should be an updated recordset returned by the GetProductProperties method.

fForceUpdate

[in, optional] A VARIANT that determines whether to force an update of the product properties.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_INVALID_LISTPRICE | 0x8898003C | The value specified for the list price was invalid.
E_CAT_INVALIDVALUE_FOR_PROPERTY 0x88980038 An invalid value was specified for one of the product properties. This error was returned if:
  • One of the properties did not satisfy the Min/Max condition.

  • The properties of string or enumeration data type exceeded the maximum length.

  • The value of the enumeration property was not one of the legal values defined.
E_CAT_PRODUCT_CHANGED | 0x88980027 | This product's properties were changed since they were last read. This error is returned only if the fForceUpdate parameter is set to False.
E_CAT_PRODUCT_DOESNT_EXIST | 0x8898001E | The specified product ID did not exist.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

Use the SetProductProperties method to modify the properties of a product. The pRSProduct parameter specifies a Recordset object that describes the new property values for this product. This method will not update the fields derived from the catalog such as ProductId and VariantID. If this method is called for a product family it will update the properties for all variants that belong to the Product family.

Use the Recordset object returned by the GetProductProperties property so that the timestamps can be compared to the records updated by this method for error detection.

If the fForceUpdate parameter is set to False, and the property values for this product have been changed since the pRSProduct record set was read, the method will fail.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Product Object

IProduct::GetProductProperties


IProduct::SetVariantProperties

Use this method to set the properties for a variant of this product.

Definition

HRESULT IProduct::SetVariantProperties(
_Recordset* pRSNewState,
VARIANT fForceUpdate
);

Parameters

pRSNewState

[in] A pointer to a Recordset object that contains the new product variant properties. This should be a recordset returned by the GetVariantProperties property, or by the CreateVariant method.

fForceUpdate

[in, optional] A VARIANT that determines whether to force an update of the product variant properties.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_CATALOG_DOESNT_SUPPORT_VARIANTS | 0x88980032 | Catalog does not support variants.
E_CAT_INVALIDVALUE_FOR_PROPERTY 0x88980038 An invalid value was specified for one of the product properties. This error was returned if:
  • One of the properties did not satisfy the Min/Max condition.

  • The properties of string or enumeration data type exceeded the maximum length.

  • The value of the enumeration property was not one of the legal values defined.
E_CAT_PRODUCT_CHANGED | 0x88980027 | This product's properties were changed since they were last read. This error is returned only if the fForceUpdate parameter is set to False.
E_CAT_VARIANT_DOESNT_EXIST | 0x8898001F | This product variant has been removed from the catalog.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

Use the SetVariantProperties method to modify the properties of a product variant. The pRSNewState parameter specifies a Recordset object that describes the new property values for this product variant. Use the recordset returned by the GetVariantProperties property, or by the CreateVariant method, so that timestamps can be compared for error detection.

If the fForceUpdate parameter is set to False, and the property values in the pRSNewState parameter have changed, the method will fail.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Product Object

IProduct::GetVariantProperties


IProduct::get_Variants

The Variants property is a read-only recordset that describes all of the variants of this product.

Definition

HRESULT IProduct::get_Variants(
VARIANT strPropertyToSortOn,
_Recordset** Variants
);

Parameters

strPropertyToSortOn

[in, optional] A VARIANT that contains the property on which the returned Recordset object is to be sorted.

Variants

[out, retval] A pointer to a _Recordset object used to return the variants.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The Variants parameter contains valid data only if the property was accessed successfully.

If this product has no variants, the returned recordset will be empty, and its EOF property will be set to VARIANT_TRUE.

The recordset returned contains fields for all of the properties defined for variants of this product and the following fields:

Field | Type | Description
TimeStamp | Timestamp | None
cy_list_price | Currency | List price
<defined variant ID> | Varies | None

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Product Object


ProductCatalog Object

Use this object to alter catalogs and to modify catalog contents. The ProductCatalog object is the primary object for working with catalogs in the Product Catalog System.

ProgID: | Dependent (See Remarks for more information)
COM Class Name: | ProductCatalog
COM Interface Name: | IProductCatalog
Interface ID Constant: | IID_IProductCatalog
Header File: | Catalog.h, mspu_guids.h
Type Library Name: | Microsoft Commerce 2000 Catalog Type Library
DLL Name: | Catalog.dll
Threading Model: | Both

In C++, use the IProductCatalog interface to access the properties and methods of the ProductCatalog object.

Because this object is primarily intended for use within ASP script, access from C++ will not be common.

The properties of the ProductCatalog object are shown in the following table.

Property | Type | Description
BaseCatalogName | BSTR | Contains the name of a base catalog for a custom catalog. This property is read-only.
CatalogName | BSTR | Contains the name of this catalog. This property is read-only.
IdentifyingProductProperty | BSTR | Contains the name of the column used to uniquely identify products and product families. This property is read-only.
IdentifyingVariantProperty | BSTR | Contains the name of the column used to uniquely identify product variants. This property is read-only.
RootCategories | _Recordset | Returns a recordset containing the names of categories that are the root categories for this catalog. This property is read-only.
RootProducts | _Recordset | Returns a recordset containing the products that are part of this catalog, but are not contained in any category. This property is read-only.
SearchableCategories | _Recordset | Returns a recordset with a single field that contains the names of the categories that are defined as searchable. This property is read-only.

The methods of the ProductCatalog object are shown in the following table.

Method | Description
AddSpecificationSearchClause | Adds a search constraint to the search context when performing a specification search of this catalog.
BeginSpecificationSearch | Initiates a specification search of this catalog.
CreateCategory | Creates a new category based on the specified category definition.
CreateCustomCatalog | Creates a new custom catalog template. The returned recordset is disconnected and updateable.
CreateProduct | Creates a new product or product family based on the specified product definition.
DeleteCategory | Deletes a category from this catalog.
DeleteCustomCatalog | Deletes a custom catalog from this catalog.
DeleteProduct | Deletes a product from this catalog.
GenerateCustomCatalog | Populates the specified custom catalog template with data derived from this catalog.
GetCatalogAttributes | Returns the attributes of this catalog. The returned recordset is disconnected and updateable.
GetCategory | Returns the specified category.
GetCategoryCustomPrice | Returns the custom price of the specified category.
GetCustomCatalogAttributes | Returns the attributes of the specified custom catalog. The returned recordset is disconnected and updateable.
GetProduct | Returns the specified product.
GetProductVariant | Returns a recordset with a single row containing all of the properties for the specified product variant.
GetSpecificationSearchClauses | Returns a recordset with a single field containing all of the search clauses for a specification search.
GuaranteedSpecificationSearch | Performs a specification search in which search constraints are removed until a match is found.
PerformSpecificationSearch | Performs a specification search of this catalog using the specified search context.
RegenerateFreeTextSearchIndex | Updates the free text search index for this catalog.
RemoveSpecificationSearchClause | Removes the last search constraint from the specified search context.
SetCatalogAttributes | Sets attributes for this catalog.
SetCategoryCustomPrice | Defines a custom price for the specified category.
SetCustomCatalogAttributes | Sets attributes for the specified custom catalog.

Remarks

The ProductCatalog object is a dependent object. Obtain a pointer to the IProductCatalog interface by calling one of the following methods:

  • ICatalogManager::GetCatalog

  • ICatalogManager::CreateCatalog

Note

  • There is limit on the number of ProductCatalogs objects upon which you can search. Above 256 ProductCatalog objects, full-text search will break. This is a limitation of SQL Server 2000.


IProductCatalog::AddSpecificationSearchClause

Use this method to add constraints to a specification search of this catalog.

Definition

HRESULT IProductCatalog::AddSpecificationSearchClause(
BSTR strClause,
VARIANT* pstrSearchHandle
);

Parameters

strClause

[in] A BSTR that contains the clause to be added to the specified specification search.

pstrSearchHandle

[in] A VARIANT that contains the state of the specification search to which the clause will be added.
[out] A VARIANT used to return the updated state of the specification search.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

Upon successful completion, the pstrSearchHandle parameter will contain the name of the updated specification search.

The specification clause contained in the strClause parameter will be appended to the existing clauses and sent to SQL Server without any changes when the specification search is performed.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ProductCatalog Object

IProductCatalog::BeginSpecificationSearch

IProductCatalog::GetSpecificationSearchClauses

IProductCatalog::PerformSpecificationSearch


IProductCatalog::get_BaseCatalogName

The BaseCatalogName property is a read-only string that contains the name of the base catalog for this catalog. If this is not a custom catalog, it does not have a base catalog, and the BaseCatalogName property contains the name of the catalog in hand.

Definition

HRESULT IProductCatalog::get_BaseCatalogName(
BSTR* BaseCatalogName
);

Parameters

BaseCatalogName

[out, retval] A BSTR used to return the base catalog name.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The BaseCatalogName parameter contains valid data only if the property was accessed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ProductCatalog Object


IProductCatalog::BeginSpecificationSearch

Use this method to initialize a specification search of a catalog.

Definition

HRESULT IProductCatalog::BeginSpecificationSearch(
BSTR strCategoryName,
VARIANT* pRSInitialPropValuesList,
VARIANT* plTotalRecordsAvailable,
BSTR* pstrSearchHandle
);

Parameters

strCategoryName

[in] A BSTR that contains the name of the category in which to search.

pRSInitialPropValuesList

[out, optional] A pointer to a VARIANT used to return the recordset of initial property values.

plTotalRecordsAvailable

[out, optional] A pointer to a VARIANT used to return the total records available.

pstrSearchHandle

[out, retval] A BSTR used to return the state of the specification search.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_CATEGORY_DOESNT_EXIST | 0x88980041 | The category you specified did not exist in the catalog.
E_CAT_CATEGORY_NOT_SEARCHABLE | 0x88980034 | The specified category was not specification searchable.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pRSInitialPropValuesList and pstrSearchHandle parameters contain valid data only if the property was accessed successfully.

The optional parameter pRSInitialPropValuesList is a single row recordset. The returned recordset contains one field for each searchable property for the products under the specified category. Each field contains a SAFEARRAY. Each SAFEARRAY contains a set of all the distinct values found in all the products under that category. Only the properties that are marked as searchable are returned in the recordset.

If all the searchable categories contain NULL values then pRSInitialPropValuesList parameter will be set to NULL and the plTotalRecordsAvailable parameter will be 0.

A category can be marked as searchable by setting the IsSearchable property to True.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ProductCatalog Object

IProductCatalog::AddSpecificationSearchClause

IProductCatalog::GetSpecificationSearchClauses

IProductCatalog::PerformSpecificationSearch


IProductCatalog::get_CatalogName

The CatalogName property is a read-only string that contains the name of this catalog.

Definition

HRESULT IProductCatalog::get_CatalogName(
BSTR* CatalogName
);

Parameters

CatalogName

[out, retval] A BSTR used to return the catalog name.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The CatalogName parameter contains valid data only if the property was accessed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ProductCatalog Object


IProductCatalog::CreateCategory

Use this method to create a new category.

Definition

HRESULT IProductCatalog::CreateCategory(
BSTR strDefinitioName,
BSTR strCategoryName,
VARIANT strParentCategoryName,
VARIANT fIsSpecificationSearchable,
ICategory** ppCategory
);

Parameters

strDefinitioName

[in] A BSTR that contains the name of the category definition on which the category is based.

strCategoryName

[in] A BSTR that contains the name of the category to be created.

strParentCategoryName

[in, optional] A VARIANT that contains the name of the category that will be a parent to this new category, if any.

IsSpecificationSearchable

[in, optional] A VARIANT that determines whether or not this category is to be specification searchable.

ppCategory

[out, retval] A pointer to an ICategory object used to return the newly created category.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_CATEGORY_DOESNT_EXIST | 0x8898001C | The specified parent category did not exist.
E_CAT_CATEGORY_EXISTS | 0x8898001D | The specified name for the new category was already in use. Category names must be globally unique across the entire system.
E_CAT_DEFINITION_DOESNT_EXIST | 0x8898000B | The specified definition did not exist.
E_CAT_INVALID_CATEG_LENGTH | 0x88980047 | The category name exceeded 128 characters.
E_CAT_PRODUCT_DEFN_FOR_CATEGORY | 0x8898004B | The definition specified was not a category definition but a product definition.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The ppCategory parameter contains valid data only if the property was accessed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ProductCatalog Object

IProductCatalog::GetCategory

IProductCatalog::DeleteCategory


IProductCatalog::CreateCustomCatalog

Use this method to create a new template for a custom catalog.

Definition

HRESULT IProductCatalog::CreateCustomCatalog(
BSTR strCCName,
_Recordset** ppRSCustomCat
);

Parameters

strCCName

[in] A BSTR that contains the name of the custom catalog to be created.

ppRSCustomCat

[out, retval] A Recordset used to return the properties of the newly created custom catalog.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_CATALOG_EXISTS | 0x88980001 | There was already a base catalog with the specified name. Catalog names and custom catalog names must be unique throughout the Product Catalog System.
E_CAT_CUSTOMCAT_EXISTS | 0x88980022 | There was already a custom catalog with the specified name.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The ppRSCustomCat parameter contains valid data only if the property was accessed successfully.

The following table shows the fields that the returned single-row recordset contains.

Field | Data Type | Description
CustomCatalogName | String 256 characters | The name of the custom catalog.
CatalogName | String 256 characters | The name of the base catalog.
CustomCatalogID | Integer | The field name that uniquely identifies custom catalogs.
TimeStamp | Timestamp | None.

The returned recordset is disconnected and updateable.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ProductCatalog Object

IProductCatalog::DeleteCustomCatalog

IProductCatalog::GenerateCustomCatalog

IProductCatalog::SetCategoryCustomPrice


IProductCatalog::CreateProduct

Use this method to create a new product within the catalog according to specified parameters.

Definition

HRESULT IProductCatalog::CreateProduct(
BSTR strDefinitionName,
VARIANT varProductID,
CURRENCY cyListPrice,
VARIANT strParentCategoryName,
IProduct** ppProduct
);

Parameters

strDefinitionName

[in] A BSTR that contains the name of the product definition for the product.

varProductID

[in] A VARIANT that contains the unique product ID for the product to be created. The data type must match the property used to uniquely identify products in this catalog.

cyListPrice

[in] A CURRENCY object that contains the list price of the product to be created.

strParentCategoryName

[in, optional] A VARIANT that contains the name of the category to be designated as the parent category of the product to be created.

ppProduct

[out, retval] A pointer to a Product object used to return the properties of the newly created product.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_CATEGORY_DEFN_FOR_PRODUCT | 0x8898004A | The specified definition was a category definition not a product definition
E_CAT_CATEGORY_DOESNT_EXIST | 0x8898001C | The specified category did not exist.
E_CAT_DEFINITION_DOESNT_EXIST | 0x8898000B | The specified definition did not exist.
E_CAT_PRODUCT_EXISTS | 0x8898001B | The specified product ID was already in use. The product ID must be unique throughout the catalog.
E_CAT_INVALID_PRODUCTID | 0x8898005B | The length of the ProductID exceeded 256 characters.
E_CAT_INVALIDVALUE_FOR_PRODUCTID | 0x8898004E | An invalid value was specified for the ProductID

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The ppProduct parameter contains valid data only if the property was accessed successfully.

A product family is a product that has variants.

The properties of the definition on which a new product is based will determine whether the product being created is a single product or a product family. If the definition used to create the product has variant properties, the newly created product will be a product family.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ProductCatalog Object

IProductCatalog::DeleteProduct

IProductCatalog::GetProduct


IProductCatalog::DeleteCategory

Use this method to delete a category from the Product Catalog System.

Definition

HRESULT IProductCatalog::DeleteCategory(
BSTR strCategoryName
);

Parameters

strCategoryName

[in] A BSTR that contains the name of the category to be deleted.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM error that this method can return.

Constant | Value | Description
E_CAT_CATEGORY_DOESNT_EXIST | 0x8898001C | The specified category did not exist.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

Any products or categories that existed in the deleted category, but not in another category, will be orphaned. Categories will become root categories and products will become root products. For example: CategoryA and CategoryB are child categories of CategoryX. CategoryA is also a child of CategoryY. When CategoryX is deleted, CategoryB will become a root category, but CategoryA will not.

If this category has been specified as a Pricing category for a custom catalog, it will be removed as the Pricing category. All the products using this category as a Pricing category will revert to their original price and the category will be removed as the Pricing category

See Also

ProductCatalog Object

IProductCatalog::get_RootCategories

IProductCatalog::CreateCategory

IProductCatalog::GetCategory


IProductCatalog::DeleteCustomCatalog

Use this method to delete a custom catalog from the Product Catalog System.

Definition

HRESULT IProductCatalog::DeleteCustomCatalog(
BSTR strCCName
);

Parameters

strCCName

[in] A BSTR that contains the name of the custom catalog to be deleted.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

All data relating to the custom catalog will be deleted. If the custom catalog was generated, then the generated catalog will also be deleted.

See Also

ProductCatalog Object

IProductCatalog::CreateCustomCatalog

IProductCatalog::GenerateCustomCatalog


IProductCatalog::DeleteProduct

Use this method to delete a product from the Product Catalog System.

Definition

HRESULT IProductCatalog::DeleteProduct(
VARIANT varProductID
);

Parameters

varProductID

[in] A VARIANT that contains the unique identifier of the product to be deleted.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM error that this method can return.

Constant | Value | Description
E_CAT_CATALOG_DOESNT_EXIST | 0x88980002 | The catalog did not exist.
E_CAT_PRODUCT_DOESNT_EXIST | 0x88980010 | The specified product did not exist.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

This method removes the product from the SQL Server database. The Product object caches information for improved performance. Because of this cache, the CatalogName and ProductID methods of the Product object will continue to return the old values after the DeleteProduct method has been called. The Variants, ParentCategories, AncestorCategories, RelatedCategories, and RelatedProducts properties will return an empty recordset and no error message.

Caution

  • Deleting a product with variants also deletes all of the variants.

See Also

ProductCatalog Object

IProductCatalog::CreateProduct

IProductCatalog::GetProduct


IProductCatalog::GenerateCustomCatalog

Use this method to populate a custom catalog with data or to update a custom catalog to reflect the latest version of the base catalog. A copy of the base catalog is made and custom prices and rules are applied to generate the custom catalog.

Definition

HRESULT IProductCatalog::GenerateCustomCatalog(
BSTR strCustomCatalogName
);

Parameters

strCustomCatalogName

[in] A BSTR that contains the custom catalog name.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM error that this method can return.

Constant | Value | Description
E_CAT_CUSTOMCAT_DOESNT_EXIST | 0x88980024 | The specified custom catalog did not exist.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

Use this method to populate a custom catalog template with data. If the custom catalog already exists then the existing data will be deleted. The generated custom catalog is a copy of the base catalog at the moment when it is populated by this method. The prices of the products in the custom catalog are determined by applying the custom pricing rule that has been set with the SetCategoryCustomPrice method. After the custom catalog has been generated by this method, the custom catalog can be treated as any other catalog.

Because custom catalogs are only copies of an existing base catalog, and are not dynamically linked to the base catalog, any changes made to the base catalog will not be automatically reflected in any custom catalogs derived from it. Similarly, any changes made to a custom catalog will not automatically propagate back to the base catalog. Use this method to update the custom catalog to reflect the latest version of the base catalog.

Note

  • This method cannot be called in a transacted object. This method involves the creation, deletion, or updating of free text indexes. SQL Server does not allow these operations in a transaction.

See Also

ProductCatalog Object

IProductCatalog::CreateCustomCatalog

IProductCatalog::DeleteCustomCatalog

IProductCatalog::SetCategoryCustomPrice


IProductCatalog::GetCatalogAttributes

Use this method to retrieve the attributes of this catalog. The returned recordset is disconnected and updateable.

Definition

HRESULT IProductCatalog::GetCatalogAttributes(
_Recordset** ppRSCatalogAttributes
);

Parameters

ppRSCatalogAttributes

[out, retval] A pointer to a Recordset used to return the attributes of this catalog.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

Ther ppRSCatalogAttributes parameter contains valid data only if the property was accessed successfully.

The returned recordset is disconnected and updateable. The following table shows the fields that the returned recordset contains.

Field | Data Type | Description
CatalogName | String 128 characters | The name of the catalog.
Locale | Integer | None.
StartDate | Datetime | None.
End Date | Datetime | None.
VariantID | String 128 characters | The field name that uniquely identifies variants.
ProductID | String 128 characters | The field name that uniquely identifies products.
Currency | String 128 characters | None.
WeightMeasure | String 128 characters | None.
TimeStamp | Timestamp | None.
CatalogID | Integer | None.
CustomCatalog | Boolean | A flag indicating whether this is a custom catalog. True indicates a custom catalog.
FreeTextIndexCreated | Datetime | None.
ProductTableUpdated | Datetime | None.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ProductCatalog Object

IProductCatalog::GetCustomCatalogAttributes

IProductCatalog::SetCatalogAttributes


IProductCatalog::GetCategory

Use this method to retrieve the specified category from a catalog.

Definition

HRESULT IProductCatalog::GetCategory(
BSTR strCategoryName,
ICategory** ppCategory
);

Parameters

strCategoryName

[in] A BSTR that contains the name of the category to be returned.

ppCategory

[out, retval] A pointer to an ICategory object used to return the specified category.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following standard COM error value has a particular meaning in the context of this method:

S_FALSE

The catalog specified did not exist.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The ppCategory parameter contains valid data only if the property was accessed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ProductCatalog Object

IProductCatalog::CreateCategory

IProductCatalog::DeleteCategory


IProductCatalog::GetCategoryCustomPrice

Use this method to retrieve the custom price and custom price type for a specified custom catalog and category.

Definition

HRESULT IProductCatalog::GetCategoryCustomPrice(
BSTR strCCName,
BSTR strCategoryName,
VARIANT* peCustomPrice,
VARIANT* pfpCustomPriceAmount
);

Parameters

strCCName

[in] A BSTR that contains the name of the custom catalog.

strCategoryName

[in] A BSTR that contains the category name for which the custom price will be returned.

peCustomPrice

[out] A pointer to a VARIANT used to return the type of the custom price. Valid values are from the CatalogCustomPriceEnum enumeration, and are described in the Remarks section below.

pfpCustomPriceAmount

[out] A pointer to a VARIANT used to return the custom price adjustment.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_CATEGORY_DOESNT_EXIST | 0x8898001C | The specified category did not exist.
E_CAT_CUSTOMCAT_DOESNT_EXIST | 0x88980024 | The specified custom catalog did not exist.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The peCustomPrice and pfpCustomPriceAmount parameters contain valid data only if the property was accessed successfully.

The following table shows the values of the CatalogCustomPriceEnum enumeration, their associated names, and describes their use.

Name | Value | Description
cscNoCustomPrice | 0 | The custom price is the same as the base price.
cscPercentageMultiplier | 1 | The custom price is the base price multiplied by the percentage value in the pfpCustomPriceAmount parameter.
cscAddFixedAmount | 2 | The custom price is the pfpCustomPriceAmount added to the base price.
cscReplacePrice | 3 | The custom price is the pfpCustomPriceAmount.
cscInvalidCustomPrice | -1 | Reserved for future use.

If the Category has not been specified as a Custom Category then the peCustomPrice parameter and the pfpCustomPriceAmount parameter will be set to 0.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ProductCatalog Object

IProductCatalog::SetCategoryCustomPrice


IProductCatalog::GetCustomCatalogAttributes

Use this method to retrieve the attributes for a specified custom catalog.

Definition

HRESULT IProductCatalog::GetCustomCatalogAttributes(
BSTR strCCName,
_Recordset** ppRSCustomCatalog
);

Parameters

strCCName

[in] A BSTR that contains the name of the custom catalog.

ppRSCustomCatalog

[out, retval] A pointer to a Recordset used to return the custom catalog attributes.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The ppRSCustomCatalog parameter contains valid data only if the method competed successfully.

The following table shows the fields that the returned single-row recordset contains.

Field | Data Type | Description
CustomCatalogName | String Maximum of 128 unicode characters | The name of the custom catalog.
CatalogName | String Maximum of128 unicode characters | The name of the base catalog.
CustomCatalogID | Integer | The field name that uniquely identifies custom catalogs.
TimeStamp | Timestamp | None.

The returned recordset is disconnected and updateable. The CustomCatalogName parameter is the only field that can be modified.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ProductCatalog Object

IProductCatalog::CreateCustomCatalog

IProductCatalog::SetCustomCatalogAttributes


IProductCatalog::GetProduct

Use this method to retrieve the specified product from a catalog.

Definition

HRESULT IProductCatalog::GetProduct(
VARIANT varProductID,
IProduct** ppProduct
);

Parameters

varProductID

[in] A VARIANT that contains the unique identifier of the product.

ppProduct

[out, retval] A pointer to an IProduct object used to return the specified product.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following standard COM error value has a particular meaning in the context of this method:

S_FALSE

The catalog specified did not exist.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The ppProduct parameter contains valid data only if the method completed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ProductCatalog Object

IProductCatalog::CreateProduct

IProductCatalog::DeleteProduct


IProductCatalog::GetProductVariant

Use this method to retrieve the properties of a specified product variant.

Definition

HRESULT IProductCatalog::GetProductVariant(
VARIANT varProductID,
VARIANT varVariantID,
_Recordset** ppRSVariant
);

Parameters

varProductID

[in] A VARIANT that contains the unique identifier of the product family.

varVariantID

[in] A VARIANT that contains the unique identifier of the product variant.

ppRSVariant

[out, retval] A pointer to hold the reference to the returned Recordset object, which will contain the properties of the variant.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_CATALOG_DOESNT_SUPPORT_VARIANTS | 0x88980032 | This catalog does not support variants. This is determined when the catalog is created and cannot be changed.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The ppRSVariant parameter contains valid data only if the property was accessed successfully.

A single row recordset with all the properties of the variant is returned. The fields of the returned recordset are determined by the properties associated with the definition on which it is based. Both the product properties and the variant properties are returned.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ProductCatalog Object

IProductCatalog::get_IdentifyingVariantProperty


IProductCatalog::GetSpecificationSearchClauses

Use this method to retrieve the specified specification search constraints.

Definition

HRESULT IProductCatalog::GetSpecificationSearchClauses(
BSTR strSearchHandle,
_Recordset** ppRSSearchClauses
);

Parameters

strSearchHandle

[in] A BSTR that contains the specification search handle.

ppRSSearchClauses

[out, retval] A pointer to a Recordset used to return the search clauses.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The ppRSSearchClauses parameter contains valid data only if the method completed successfully.

The returned recordset contains a single variable-length String field, called Clause, and one row for each constraint present.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ProductCatalog Object

IProductCatalog::AddSpecificationSearchClause

IProductCatalog::RemoveSpecificationSearchClause


IProductCatalog::GuaranteedSpecificationSearch

Use this method to guarantee results when performing a specification search of a catalog.

Definition

HRESULT IProductCatalog::GuaranteedSpecificationSearch(
VARIANT* pstrSearchHandle,
VARIANT eClassTypeRequired,
VARIANT lDesiredRecords,
VARIANT* plTotalRecordsAvailable,
VARIANT* pRSNewPropValuesList,
VARIANT vrPropertiesRequired,
_Recordset** ppRSSearchResults
);

Parameters

pstrSearchHandle

[in, out]A VARIANT that contains the specification search handle.

eClassTypeRequired

[in, optional] A VARIANT that contains the catalog class desired. Valid values are from the CatalogClassTypeEnum enumeration, and are described in the Remarks section below.

lDesiredRecords

[in, optional] A VARIANT that contains the number of records desired.

plTotalRecordsAvailable

[out, optional] A pointer to a VARIANT used to return the total records available.

pRSNewPropValuesList

[out, optional] A Recordset used to return the new property values list.

vrPropertiesRequired

[in,optional] A VARIANT that contains the properties required in a comma delimited String.

ppRSSearchResults

[out, retval] A Recordset used to return the search results.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors, and the standard COM errors with special meanings, that this method can return.

Constant | Value | Description
S_FALSE 0x00000001 This value is returned when the pRSNewPropValuesList parameter is specified and:
  • There are no properties in the catalog that are marked for specification search.

  • There are no products under the category selected for specification search.
E_CAT_CATEGORY_NOT_EXISTS_NOT_SEARCHABLE | 0x88980049 | The category you specified did not exist or was not specification searchable.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pstrSearchHandle, plTotalRecordsAvailable, pRSNewPropValuesList, and ppRSSearchResults parameters contain valid data only if the property was accessed successfully.

This method is similar to the PerformSpecificationSearch method. The optional output parameter, pRSNewPropValuesList, is a single row recordset. This recordset contains one field for each searchable property for the products under the category specified in the BeginSpecificationSearch method. Each field contains a SAFEARRAY. The SAFEARRAY contains a set of distinct values for that property. The set is all the values in all the products that match the search clauses in the search handle. Only the properties that are marked as searchable are returned in the recordset. A property can be marked as searchable by setting the IncludeInSpecSearch attribute of that property to True.

This method guarantees that results will be returned from a specification search of the catalog by removing search constraints in the reverse order that they were added until a match is found. Therefore, remember to add constraints to a specification search in order of decreasing importance.

The Recordset object returned by this method will contain a field for each property name in the vrPropertiesRequired parameter. If the parameter is omitted, the Recordset object will contain all of the corresponding fields. For more information about these fields, see CatalogProduct Recordset.

Note

  • When field names begin with a number or contain spaces they must be enclosed in brackets. Data errors will occur if the field names are not formatted correctly. For example, "[123_Prop1],[123_ Prop2]". If the vrPropertiesRequired property is omitted then the data in all fields will be returned correctly.

The following table shows the values of the CatalogClassTypeEnum enumeration, their associated names, and describes their use.

Name | Value | Description
cscCategoryClass | 1 | Requests category data.
cscProductVariantClass | 2 | Requests product variant data.
cscProductClass | 4 | Requests product data.
cscProductFamilyClass | 8 | Requests product family data.
cscProductFamilyForVariantsClass | 16 | Requests family for variant data, which means the product family of a product variant is being requested.
cscProductVariantsForFamily | 32 | Requests variants for family data, which means that all of the product variants for a product family are being requested.

CatalogClassTypeEnum values can be combined in the eClassTypeRequired parameter with logical ORs , so that specifying cscProductClass OR cscProductVariantClass will return both product and product variant data.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ProductCatalog Object

IProductCatalog::AddSpecificationSearchClause

IProductCatalog::PerformSpecificationSearch

IProductCatalog::RemoveSpecificationSearchClause


IProductCatalog::get_IdentifyingProductProperty

The IdentifyingProductProperty property is a read-only String that contains the name of the unique identifier field for the products in this catalog.

Definition

HRESULT IProductCatalog::get_IdentifyingProductProperty(
BSTR* IdentifyingProductProperty
);

Parameters

IdentifyingProductProperty

[out, retval] A BSTR used to return the name of the identifying product property.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The IdentifyingProductProperty parameter contains valid data only if the property was accessed successfully.

The product id is cached in the ProductCatalog object. Because of the cache, this method will continue to return the old value after the catalog has been deleted.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ProductCatalog Object

IProductCatalog::get_IdentifyingVariantProperty


IProductCatalog::get_IdentifyingVariantProperty

The IdentifyingProductVariantProperty property is a read-only String that contains the name of the unique identifier field for product variants in this catalog.

Definition

HRESULT IProductCatalog::get_IdentifyingVariantProperty(
BSTR* IdentifyingVariantProperty
);

Parameters

IdentifyingVariantProperty

[out, retval] A BSTR used to return the name of the identifying variant property.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The IdentifyingVariantProperty parameter contains valid data only if the property was accessed successfully.

The variant id is cached in the ProductCatalog object. Because of the cache, this method will continue to return the old value after the catalog has been deleted.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ProductCatalog Object

IProductCatalog::get_IdentifyingProductProperty


IProductCatalog::PerformSpecificationSearch

Use this method to perform a specification search of a catalog.

Definition

HRESULT IProductCatalog::PerformSpecificationSearch(
BSTR strSearchHandle,
VARIANT eClassTypeRequired,
VARIANT lDesiredRecords,
VARIANT* plTotalRecordsAvailable,
VARIANT* pRSNewPropValuesList,
VARIANT vrPropertiesRequired,
_Recordset** ppRSSearchResults
);

Parameters

strSearchHandle

[in] A BSTR that contains the name of the search to perform.

eClassTypeRequired

[in, optional] A VARIANT that contains the catalog class desired. Valid values are from the CatalogClassTypeEnum enumeration, and are described in the Remarks section below.

lDesiredRecords

[in, optional] A VARIANT that contains the records desired.

plTotalRecordsAvailable

[out, optional] A pointer to a VARIANT used to return the total number of records available.

pRSNewPropValuesList

[out, optional] A pointer to a VARIANT used to return the Recordset of the new property values list.

vrPropertiesRequired

[in,optional] A VARIANT that contains the properties required in a comma-delimited String.

ppRSSearchResults

[out, retval] A pointer to hold the reference to the returned Recordset object, which will contain the search results.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
S_FALSE 0x00000001 This value is returned when the pRSNewPropValuesList parameter is supplied and:
  • There are no properties in the catalog that are marked for specification search.

  • There are no products under the category selected for specification search.
E_CAT_CATEGORY_NOT_EXISTS_NOT_SEARCHABLE | 0x88980049 | The category you specified did not exist or was not specification searchable.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The plTotalRecordsAvailable, pRSNewPropValuesList, and ppRSSearchResults parameters contain valid data only if the property was accessed successfully.

The PerformSpecificationSearch method executes a query using all of the constraints that have been added to the specified specification search handle.

The optional output parameter, pRSNewPropValuesList, is a single row recordset. This recordset contains one field for each searchable property for the products under the category specified in the BeginSpecificationSearch method. Each field contains a SAFEARRAY. The SAFEARRAY contains a set of distinct values for that property. The set is all the values in all the products that match the search clauses in the search handle. Only the properties that are marked as searchable are returned in the recordset. A property can be marked as searchable by setting the IncludeInSpecSearch attribute of that property to True.

The Recordset object returned by this method will contain a field for each property name in the vrPropertiesRequired parameter. It will always contain a CatalogName field. If the parameter is omitted, the Recordset object will contain all of the corresponding fields. For more information about these fields, see CatalogProduct Recordset.

Note

  • When field names begin with a number or contain spaces they must be enclosed in brackets. Data errors will occur if the field names are not formatted correctly. For example, "[123_Prop1],[123_ Prop2]". If the vrPropertiesRequired property is omitted then the data in all fields will be returned correctly.

The following table shows the values of the CatalogClassTypeEnum enumeration, their associated names, and describes their use.

Name | Value | Description
cscCategoryClass | 1 | Requests category data.
cscProductVariantClass | 2 | Requests product variant data.
cscProductClass | 4 | Requests product data.
cscProductFamilyClass | 8 | Requests product family data.
cscProductFamilyForVariantsClass | 16 | Requests family for variant data, which means the product family of a product variant is being requested.
cscProductVariantsForFamily | 32 | Requests variants for family data, which means that all of the product variants for a product family are being requested.

CatalogClassTypeEnum values can be combined in the eClassTypeRequired parameter with logical OR operators, so that specifying cscProductClass OR cscProductVariantClass will return both product and product variant data.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ProductCatalog Object

IProductCatalog::AddSpecificationSearchClause

IProductCatalog::BeginSpecificationSearch

IProductCatalog::GuaranteedSpecificationSearch

IProductCatalog::RemoveSpecificationSearchClause


IProductCatalog::RegenerateFreeTextSearchIndex

Use this method to regenerate the free text search index of a catalog.

Definition

HRESULT IProductCatalog::RegenerateFreeTextSearchIndex(
VARIANT_BOOL fGenerateIncremental
);

Parameters

fGenerateIncremental

[in, defaultvalue(0)] A VARIANT_BOOL that determines whether an incremental or a full rebuild of the free text search index is to be performed. A value of True indicates an incremental rebuild. A value of False indicates a full rebuild. See the Remarks section for more information.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_CANNOT_REFRESH | 0x8898004C | A catalog import operation is currently in progress. The refresh operation cannot be performed now.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

This method should be called after new products or categories are added to a catalog. Otherwise, those new products and categories will not be returned in any free text search results.

The fGenerateIncremental parameter determines what type of free text index rebuild to perform. The default is to completely rebuild the free text index. Though this option ensures completeness, it is slower than an incremental rebuild, which appends only recently added products and categories to the index.

If the database in which Commerce Server keeps its catalog data does not have the SQL Server 2000 full-text engine installed, this method will return with no action.

Note

  • This method cannot be called in a transacted object. This method involves the creating, deleting, or updating of free text indexes. SQL Server does not allow these operations in a transaction.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ProductCatalog Object


IProductCatalog::RemoveSpecificationSearchClause

Use this method to remove the last constraint from a specified specification search.

Definition

HRESULT IProductCatalog::RemoveSpecificationSearchClause(
VARIANT* pstrSearchHandle,
BSTR* pstrPoppedClause
);

Parameters

pstrSearchHandle

[in, out] A VARIANT that contains the specification search handle from which a constraint is to be removed.

pstrPoppedClause

[out, retval] A pointer to a BSTR used to return the removed clause.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pstrSearchHandle and pstrPoppedClause parameters contain valid data only if the property was accessed successfully.

This method always removes the last constraint that was added to the search using the AddSpecificationSearchClause method. The returned string will be in the same form as the original constraint.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ProductCatalog Object


IProductCatalog::get_RootCategories

The RootCategories property is a read-only recordset that contains the names of the categories that exist at the root level of this catalog.

Definition

HRESULT IProductCatalog::get_RootCategories(
VARIANT vrPropertiesRequired,
_Recordset** RootCategories
);

Parameters

vrPropertiesRequired

[in,optional] A VARIANT, subtype String, that contains a comma-separated list of the required property names.

RootCategories

[out, retval] A Recordset used to return the root categories.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The RootCategories parameter contains valid data only if the property was accessed successfully.

Any category without parents is considered to be a root category.

The Recordset object returned by this method will contain one row for each root category, and a field for each property name in the vrPropertiesRequired parameter. If the parameter is omitted, the Recordset object will contain all of the corresponding fields. For more information about these fields, see CatalogProduct Recordset.

Note

  • Leading numbers in the property names in the vrPropertiesRequired parameter will be trimmed from the corresponding field names in the returned recordset. The data will be correct; only the field names will be incorrect. If the property is omitted, then the field names will be correct. Enclose field names that begin with a number in brackets to avoid this problem. For example, oProductCatalog.RootCategories("[123_Prop1],[123_ Prop2]").

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ProductCatalog Object

IProductCatalog::get_RootProducts


IProductCatalog::get_RootProducts

The RootProducts property is a read-only recordset that contains the products that exist at the root level of a catalog.

Definition

HRESULT IProductCatalog::get_RootProducts(
_Recordset** RootProducts
);

Parameters

RootProducts

[out, retval] A Recordset used to return the root products.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The RootProducts parameter contains valid data only if the property was accessed successfully.

Any product that is not contained within a category is considered to be a root product.

The Recordset object returned by this method will contain all of the corresponding fields. For more information about these fields, see CatalogProduct Recordset.

Products added by importing a comma-separated value (CSV) file will be root products.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ProductCatalog Object

IProductCatalog::get_RootCategories


IProductCatalog::get_SearchableCategories

The SearchableCategories property is a read-only recordset that contains the names of all searchable categories.

Definition

HRESULT IProductCatalog::get_SearchableCategories(
_Recordset** SearchableCategories
);

Parameters

SearchableCategories

[out, retval] A Recordset used to return the names of the searchable categories.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The SearchableCategories parameter contains valid data only if the property was accessed successfully.

The SearchableCategories property returns the names of all the categories in this catalog that can be queried using a specification search. Whether or not a particular category is specification searchable is determined by the value of the IsSearchable attribute. This property can be set at the time the category is created, or can be changed at any time using the SetCategoryProperties methods of the category object.

The Recordset object returned by this property will contain a single 128-character field called Name. Each row will contain the name of a searchable category.

If there are no searchable categories, a recordset with its EOF property set to VARIANT_TRUE will be returned.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ProductCatalog Object

IProductCatalog::CreateCategory

IProductCatalog::GetCategory


IProductCatalog::SetCatalogAttributes

Use this method to set the attributes of a catalog.

Definition

HRESULT IProductCatalog::SetCatalogAttributes(
_Recordset* pRSCatalogAttributes,
VARIANT fForceUpdate
);

Parameters

pRSCatalogAttributes

[in] A Recordset containing the new attributes.

fForceUpdate

[in, optional] A VARIANT that causes a forced update of the catalog attributes.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Value | Description
E_CAT_CATALOG_DOESNT_EXIST | 0x88980002 | The catalog did not exist.
E_CAT_CATALOG_CHANGED | 0x88980012 | The catalog has been updated since it was last read.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

Use the GetCatalogAttributes method to get a recordset of the current attributes. After the recordset has been modified, use it as the pRSCatalogAttributes parameter to the SetCatalogAttributes method to write the changes back to the catalog. The timestamps in the recordset will be compared to the timestamps of the attributes being updated for error detection.

The catalog Name, ProductID, CatalogID, and VariantID attributes cannot be changed with this method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ProductCatalog Object

IProductCatalog::GetCatalogAttributes


IProductCatalog::SetCategoryCustomPrice

Use this method to set a custom price rule for a category.

Definition

HRESULT IProductCatalog::SetCategoryCustomPrice(
BSTR strCCName,
BSTR strCategoryName,
CatalogCustomPriceEnum eCustomPrice,
DOUBLE fpCustomPriceAmount
);

Parameters

strCCName

[in] A BSTR that contains the name of the custom catalog template for which this rule will apply.

strCategoryName

[in] A BSTR that contains the name of the category for which a custom price will be set.

eCustomPrice

[in] The type of price adjustment. Valid values are from the CatalogCustomPriceEnum enumeration, and are described in the Remarks section below.

fpCustomPriceAmount

[in] A DOUBLE that contains the custom price adjustment amount.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM error that this method can return.

Constant | Value | Description
E_CAT_CATEGORY_DOESNT_EXIST | 0x8898001C | The category did not exist.
E_CAT_CUSTOMCAT_DOESNT_EXIST | 0x88980024 | The specified custom catalog did not exist.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The SetCategoryCustomPrice method defines a custom pricing rule for a category, and all the immediate child products of that category, in the specified custom catalog. The SetCategoryCustomPrice method does not affect child categories.

If a product exists within multiple categories, each having different custom prices, the custom price will not be applied to that product for either category.

The following table shows the values of the CatalogCustomPriceEnum enumeration, their associated names, and describes their use.

Name | Value | Description
cscNoCustomPrice | 0 | The custom price is the same as the base price.
cscPercentageMultiplier | 1 | The custom price is the base price multiplied by the percentage value in the pfpCustomPriceAmount parameter.
cscAddFixedAmount | 2 | The custom price is the pfpCustomPriceAmount added to the base price.
cscReplacePrice | 3 | The custom price is the pfpCustomPriceAmount.
cscInvalidCustomPrice | -1 | Reserved for future use.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ProductCatalog Object

IProductCatalog::GetCategoryCustomPrice


IProductCatalog::SetCustomCatalogAttributes

Use this method to set the attributes of a custom catalog.

Definition

HRESULT IProductCatalog::SetCustomCatalogAttributes(
_Recordset* pRSNewState,
VARIANT fForceUpdate
);

Parameters

pRSNewState

[in] A pointer to a Recordset object containing the new attributes.

fForceUpdate

[in, optional] A VARIANT that causes a forced update of the custom catalog attributes.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM error that this method can return.

Constant | Value | Description
E_CAT_CANNOT_ALTER_CC | 0x88980060 | The specified changes could not be made.
E_CAT_CUSTOMCATALOG_CHANGED | 0x88980035 | The custom catalog has been altered since it was last read.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

Use the SetCustomCatalogAttributes method to modify the CustomCatalogName attribute of a custom catalog. No other attributes can be modified. The pRSNewState parameter specifies a Recordset object that describes the new attribute values for this custom catalog. The method will fail if the custom catalog has already been published.

Use the Recordset object returned by the GetCustomCatalogAttributes method so that its timestamp can be compared for quality assurance.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ProductCatalog Object

IProductCatalog::GetCustomCatalogAttributes


CatalogProduct Recordset

The fields in this Recordset object will vary, depending on the product definitions in the catalog. The following table contains a list of common fields that will always be part of this Recordset object.

Field name | Data type
CategoryName | String Maximum of 128 characters
Oid | Integer
DefinitionName | String Maximum of 128 characters
IsSearchable | Small integer
cy_list_price | Money
PricingCategoryOID | Integer
TimeStamp | TimeStamp
OriginalPrice | Money
i_ClassType | Integer
ParentOID | Integer
ProductID | String Maximum of 256 characters
VariantID | String Maximum of 256 characters

Note

  • The Oid field is for internal use and should not be updated.

See Also

IProductCatalog::GuaranteedSpecificationSearch

IProductCatalog::PerformSpecificationSearch

IProductCatalog::get_RootCategories

IProductCatalog::get_RootProducts


ProfileObject Object

Use this object to retrieve the data in specific profile object instances and modify the property values for that profile object. In addition, use the ProfileObject object to examine and navigate the property attributes of a profile object.

ProgID: | Commerce.ProfileObject (Externally creatable)
COM Class Name: | ProfileObject
COM Interface Name: | IProfileObject
Interface ID Constant: | IID_IProfileObject
Header File: | mscsups.h, mspu_guids.h
Type Library Name: | Microsoft Commerce 2000 Profile Service Type Library
DLL Name: | mscsups.dll
Threading Model: | Both

In C++, use the IProfileObject interface to access the properties and methods of the ProfileObject object.

Because this object is primarily intended for use within ASP script, access from C++ will not be common.

The properties of the ProfileObject object are shown in the following table.

Property | Type | Description
Fields | Fields | Stores the profile property collection. This property is read-only.

The methods of the ProfileObject object are shown in the following table.

Method | Description
GetProfileXML | Retrieves an XML fragment representing the data structure of the profile object.
Update | Saves the profile data to the underlying data store.

Remarks

The ProfileObject object maintains backward compatibility with the AUO 1.0 object (released in Microsoft Site Server 3.0 Commerce Edition) by inheriting from the IADs interface. Refer to the MSDN ADSI documentation for descriptions of the methods of the IADs interface.

The ProfileObject object supports extended dot notation. For example, using extended dot notation, the following:

oProfileObject.Fields("Address.Zipcode")

is equivalent to:

oProfileObject.Fields("Address").Value("Zipcode")

The first technique retrieves the Zipcode value in a single call to Fields.Value, while the second technique requires two calls to retrieve the same value.

The ProfileObject object also provides smart navigation into profiles. For example, using smart navigation, the following:

oProfileObject.Address.ZipCode

is equivalent to:

oProfileObject.Fields("Address.Zipcode")

In general, the CreateProfile method of the ProfileService object is used to instantiate this object.

See Also

Profile Objects

Profile Schema

Profile XML Structures

ProfileService Object


IProfileObject::get_Fields

The Fields property is a read-only Fields collection that contains the profile property data for the ProfileObject object. Read-only refers to the inability to add or delete members (profile properties) of the Fields collection. This property is the default property of the ProfileObject object. Use this property to set and retrieve profile property values and to navigate the attribute list of the properties.

Definition

HRESULT IProfileObject::get_Fields(
Fields** ppFields
);

Parameters

ppFields

[out, retval] The address of a pointer to a Fields collection used to return the profile object properties.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the following Error Values section for more details.

Error Values

The Errors property of the ProfileService object stores the collection of errors encountered in the last Profiles resource operation. For more information, see IProfileService::get_Errors.

Remarks

The Fields collection is similar to an ADO Fields collection object. The following ADO Fields methods and properties are supported:

  • Count

  • Item

  • _NewEnum

A member of the Fields collection is a Field object that represents a single property or property group of a ProfileObject object. The Field object is similar to an ADO Field object. The following ADO Field methods and properties are supported:

  • Properties - Returns the read-only Attributes collection.

  • DefinedSize - Retrieves the defined size of the data type.

  • Name

  • Type

  • Value

The Attributes collection is represented as an ADO Properties object. The following ADO Properties methods and properties are supported:

  • Count

  • Item

  • _NewEnum

Use the Update method of the ProfileObject object to save any changed profile data in the underlying data store.

The Fields property of the ProfileObject object supports extended dot notation for increased performance. For example, using extended dot notation, the following:

oProfileObject.Fields("Address.Zipcode")

is equivalent to:

oProfileObject.Fields("Address").Value("Zipcode")

For information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

The ppFields parameter contains valid data only if the property is accessed successfully.

See Also

ProfileObject Object

ProfileService Object


IProfileObject::GetProfileXML

Use this method to retrieve the XML schema and data of the profile object.

Definition

HRESULT IProfileObject::GetProfileXML (
XMLRetrieveEnum eRetrieveEnum,
VARIANT_BOOL bAttributeCentric,
BSTR* pbstrXML
);

Parameters

bAttributeCentric

[in] A VARIANT_BOOL that indicates the XML output format. Set this parameter to True (1) to retrieve the XML in an attribute-centric format, and to False (0) to retrieve the XML in an element-centric format.

pbstrXML

[out, retval] A pointer to a BSTR that contains the resulting XML fragment.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

The Errors property of the ProfileService object stores the collection of errors encountered in the last Profiles resource operation. For more information, see IProfileService::get_Errors.

Remarks

The pbstrXML parameter contains valid data only if the method completes successfully.

The following table defines the possible values for XMLRetrieveEnum.

Name | Value | Description
psRetrieveInvalidValue | 0 | Invalid option
psRetrieveSchemaAndData | 1 | Both the schema and data are retrieved.
psRetrieveDataOnly | 2 | Only the data is retrieved.
psRetrieveSchemaOnly | 3 | Only the schema is retrieved.

For information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ProfileObject Object

IProfileObject::get_Fields

Profile XML Structures


IProfileObject::Update

Use this method to save ProfileObject object data to the underlying data store.

Definition

HRESULT IProfileObject::Update(
);

Parameters

None.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

The Errors property of the ProfileService object stores the collection of errors encountered in the last Profiles resource operation. For more information, see IProfileService::get_Errors.

Remarks

The Update method commits the object to the data store.

Any changes made using the IADs interface routines are committed to the database.

Use the Fields property to access the ProfileObject object data.

See Also

ProfileObject Object

IProfileObject::get_Fields


ProfileService Object

Use this object to create, delete, and retrieve ProfileObject objects.

ProgID: | Commerce.ProfileService (Externally creatable)
COM Class Name: | ProfileService
COM Interface Name: | IProfileService
Interface ID Constant: | IID_IProfileService
Header File: | mscsups.h, mspu_guids.h
Type Library Name: | Microsoft Commerce 2000 Profile Service Type Library
DLL Name: | mscsups.dll
Threading Model: | Both

In C++, use the ProfileService interface to access the properties and methods of the ProfileService object.

Because this object is primarily intended for use within ASP script, access from C++ will not be common.

The properties of the ProfileService object are shown in the following table.

Property | Type | Description
Errors | Errors | Stores the collection of errors encountered in the last Profiles resource operation. This property is read-only.

The methods of the ProfileService object are shown in the following table.

Method | Description
BindAs | Sets the user credentials for accessing the underlying Profiles store.
CreateProfile | Creates the specified ProfileObject object.
DeleteProfile | Deletes a ProfileObject object specified by a primary key value from the Profiling System.
DeleteProfileByKey | Deletes a ProfileObject object specified by a key member/value pair from the Profiling System.
GetProfile | Retrieves a ProfileObject object specified by a primary key value from the Profiling System.
GetProfileByKey | Retrieves a ProfileObject object specified by a key member/value pair from the Profiling System.
GetProfileDefXML | Retrieves the XML description of the specified profile definition.
Initialize | Establishes connection to the specified Profiles store and populates the schema cache.
UnBind | Clears the user credentials for accessing the underlying Profiles store.

Remarks

The ProfileService object implements read/write run-time access for ProfileObject objects and read-only access for profile definitions.

The ProfileService object provides run-time access to a profile object, which is a specific instantiation of a profile schema. The Profile Designer module in Commerce Server Business Desk and the Profiles resource in Commerce Server Manager provide design-time access for modifying the profile schema.

In a Web-based application context, the ProfileService object is intended to be created and initialized in the Global.asa file for the application. The ProfileObject objects are intended to be created within page scope.

Call the Initialize method before you use any other ProfileService method or property.

See Also

Profile Objects

Profile Schema

Profile XML Structures

ProfileObject Object


IProfileService::BindAs

Use this method to set the credentials used to access ProfileObject objects in the underlying Profiles store.

Definition

HRESULT IProfileService::BindAs (
BSTR sUserName,
BSTR sPassword,
);

Parameters

sUserName

[in] A BSTR that contains the user name for accessing ProfileObject objects.

sPassword

[in] A BSTR that contains the password for accessing ProfileObject objects.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

The Errors property stores the collection of errors encountered in the last Profiles resource operation. For more information, see IProfileService::get_Errors.

Remarks

This method sets the credentials used to access and modify ProfileObject objects in the underlying directory store. Any new ProfileObject objects or modifications will be bound to these credentials. The specified credentials define the security context under which all subsequent ProfileObject object operations will be performed, until the UnBind method is invoked. The credentials specified here will be used as is to bind to the underlying directory stores. It is the responsibility of the client to pass in these credentials in the appropriate format. For example, to bind to Active Directory one could pass in either the

  • Full User Principal Name (UPN) (for example, joeuser@domain.com), or

  • SAM Account Name (for example, Domain\SAMAccountName), or

  • Fully specified distinguished name of the security principal (for example, CN=joeuser, CN=Users, DC=Domain, DC=com).

For Membership Directory, you must specify the fully specified distinguished name of the security principal.

Use the UnBind method to clear the credentials.

Call the Initialize method before you use this ProfileService method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ProfileService Object

IProfileService::UnBind


IProfileService::CreateProfile

Use this method to create a ProfileObject object.

Definition

HRESULT IProfileService::CreateProfile(
VARIANT sValue,
BSTR bstrType,
IProfileObject** ppProfileObject
);

Parameters

sValue

[in] A VARIANT that contains the primary key value for the new ProfileObject object. The variable types permitted for this variant are VT_BSTR or VT_I4.

bstrType

[in] A BSTR that contains the schema type for the new ProfileObject object.

ppProfileObject

[out, retval] The address of a pointer to the IProfileObject interface of the newly created ProfileObject object. The pointer is set to NULL if a ProfileObject object of the specified primary key and schema type already exists in the Profiles store.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

The Errors property stores the collection of errors encountered in the last Profiles resource operation. For more information, see IProfileService::get_Errors.

Remarks

If the CreateProfile method fails on an aggregated profile (one that has multiple data sources), the DeleteProfile method must be called to clean up any entries in the data stores. In this case, the DeleteProfile method will produce an error that should be ignored.

The CreateProfile method verifies that a ProfileObject object with the specified attributes does not already exist in the database.

The Fields property of the returned ProfileObject object provides access to the profile properties.

Use the GetProfile or GetProfileByKey method to retrieve existing ProfileObject instances from the Profiles store.

Call the Initialize method before you use this ProfileService method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

The ppProfileObject parameter contains valid data only if the method completes successfully.

See Also

ProfileService Object

IProfileService::DeleteProfile

IProfileService::GetProfile

IProfileService::GetProfileByKey

IProfileService::Initialize

ProfileObject Object

IProfileObject::get_Fields


IProfileService::DeleteProfile

Use this method to delete the ProfileObject object specified by a primary key value and schema type. All properties associated with the profile are purged from the system.

Definition

HRESULT IProfileService::DeleteProfile(
VARIANT sValue,
BSTR bstrType
);

Parameters

sValue

[in] A VARIANT that contains the primary key value.

bstrType

[in] A BSTR that contains the profile schema type.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

The Errors property stores the collection of errors encountered in the last Profiles resource operation. For more information, see IProfileService::get_Errors.

Remarks

If the DeleteProfile method is called because of an error in creating a new ProfileObject object, any error message produced should be ignored.

Use the DeleteProfileByKey method to delete a profile specified by a key member/value pair and schema type.

Call the Initialize method before you use this ProfileService method.

Caution

  • Care must be taken when deleting ProfileObject objects due to possible expression dependencies. See the ExpressionStore and ExpressionEval objects for details on expressions.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ProfileService Object

IProfileService::CreateProfile

IProfileService::DeleteProfileByKey

ExpressionEval Object

ExpressionStore Object


IProfileService::DeleteProfileByKey

Use this method to delete the ProfileObject object specified by a key member name/value pair and schema type. All properties associated with the profile are purged from the system.

Definition

HRESULT IProfileService::DeleteProfileByKey(
BSTR bstrKeyMemberName,
VARIANT sValue,
BSTR bstrType
);

Parameters

bstrKeyMemberName

[in] A BSTR that contains the key member name.

sValue

[in] A VARIANT that contains the key value.

bstrType

[in] A BSTR that contains the profile schema type.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

The Errors property stores the collection of errors encountered in the last Profiles resource operation. For more information, see IProfileService::get_Errors.

Remarks

Use the DeleteProfile method to delete a profile by specifying a primary key value and schema type.

Call the Initialize method before you use this ProfileService method.

Caution

  • Care must be taken when deleting ProfileObject objects due to possible expression dependencies. See the ExpressionStore and ExpressionEval objects for details on expressions.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ProfileService Object

IProfileService::CreateProfile

IProfileService::DeleteProfile

ExpressionEval Object

ExpressionStore Object


IProfileService::get_Errors

The Errors property is a read-only ADO Errors object that stores the collection of errors encountered in the last Profiles resource operation.

Definition

HRESULT IProfileObject::get_Errors(
Errors** ppErrors
);

Parameters

ppErrors

[out, retval] The address of a pointer to an Errors object.

Return Values

This method returns an HRESULT indicating whether it completed successfully.

Remarks

The Errors property collects all errors generated by a ProfileService object operation, including those that emerge from the underlying technology.

If the error is coming from the underlying data store providers (such as OLE DB Provider for SQL Server and OLE DB Provider for Microsoft Directory Services) it is passed, for example, in some cases only the Number and Source properties of the Error object are set.

For information about standard COM errors, see Standard COM Errors.

The following ADO Errors methods and properties are supported:

  • Clear

  • Count

  • Item

  • _NewEnum

The following ADO Error methods and properties are supported:

  • Description

  • HelpFile

  • Number

  • Source

Call the Initialize method before you access the Errors property.

See Also

ProfileObject Object

ProfileService Object


IProfileService::GetProfile

Use this method to retrieve the ProfileObject object corresponding to the specified primary key value and schema type.

Definition

HRESULT IProfileService::GetProfile(
VARIANT sValue,
BSTR bstrType,
VARIANT_BOOL bReturnError,
IProfileObject** ppProfileObject
);

Parameters

sValue

[in] A VARIANT that contains the primary key value.

bstrType

[in] A BSTR that contains the profile schema type.

bReturnError

[in, optional, defaultvalue (-1)] An optional VARIANT_BOOL.

ppProfileObject

[out, retval] The address of a pointer to the IProfileObject interface of the returned ProfileObject object.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

The Errors property stores the collection of errors encountered in the last Profiles resource operation. For more information, see IProfileService::get_Errors.

Remarks

If the optional bReturnError parameter is set to True (-1) and the specified ProfileObject object is not found, an error message, E_PS_PROFILE_NOTEXISTS, is returned instead of a ProfileObject object.

If the bReturnError parameter is set to False (0) and the specified ProfileObject object is not found, an empty ProfileObject object is returned without an error message.

Properties with the IsCached attribute set to False are not loaded by this method.

The Fields property of the returned ProfileObject object provides access to the profile properties.

Use the GetProfileByKey method to retrieve a profile by specifying a key member name/value pair and schema type.

Call the Initialize method before you use this ProfileService method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

The ppProfileObject parameter contains valid data only if the method completes successfully.

See Also

ProfileService Object

IProfileService::GetProfileByKey

IProfileService::Initialize

ProfileObject Object

IProfileObject::get_Fields


IProfileService::GetProfileByKey

Use this method to retrieve a ProfileObject object that corresponds to a specified key member name/value pair and schema type.

Definition

HRESULT IProfileService::GetProfileByKey(
BSTR bstrKeyMemberName,
VARIANT sValue,
BSTR bstrType,
VARIANT_BOOL bReturnError,
IProfileObject** ppProfileObject
);

Parameters

bstrKeyMemberName

[in] A BSTR that contains the key member name.

sValue

[in] A VARIANT that contains the key value.

bstrType

[in] A BSTR that contains the schema type.

bReturnError

[in, optional, defaultvalue (-1)] An optional VARIANT_BOOL.

ppProfileObject

[out, retval] The address of a pointer to the IProfileObject interface of the returned ProfileObject object.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

The Errors property stores the collection of errors encountered in the last Profiles resource operation. For more information, see IProfileService::get_Errors.

Remarks

If the optional bReturnError parameter is set to True (-1) and the specified ProfileObject object is not found, an error message, E_PS_PROFILE_NOTEXISTS, is returned instead of a ProfileObject object.

If the bReturnError parameter is set to False (0) and the specified ProfileObject object is not found, an empty ProfileObject object is returned without an error message.

Properties with the IsCached attribute set to False are not loaded by this method.

The Fields property of the returned ProfileObject object provides access to the profile properties.

Use the GetProfile method to retrieve a profile by specifying a primary key value and schema type.

Call the Initialize method before you use this ProfileService method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

The ppProfileObject parameter contains valid data only if the method completes successfully.

See Also

ProfileService Object

IProfileService::GetProfile

IProfileService::Initialize

ProfileObject Object

IProfileObject::get_Fields


IProfileService::GetProfileDefXML

Use this method to retrieve the XML definition of the named profile schema type.

Definition

HRESULT IProfileService::GetProfileDefXML(
BSTR bstrProfileName,
VARIANT_BOOL bNamesOnly,
BSTR* pbstrXML
);

Parameters

bstrProfileName

[in] A BSTR that contains the name of the profile schema type.

bNamesOnly

[in] A VARIANT_BOOL that determines whether the method returns the profile schema name or the profile schema definition. A value of FALSE indicates to return the profile definition. A value of TRUE indicates to return only the name of the profile schema.

pbstrXML

[out, retval] A pointer to a BSTR that will contain the XML description.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

The Errors property stores the collection of errors encountered in the last Profiles resource operation. For more information, see IProfileService::get_Errors.

Remarks

If the bstrProfileName parameter is empty and the bNamesOnly parameter is False (0), the XML descriptions of all the schema types in the catalog are returned.

If the bstrProfileName parameter is empty and the bNamesOnly parameter is True (-1), the names of all the schema types in the catalog are returned.

For information about the XML definitions, see the Profile XML Structures topic.

Call the Initialize method before you use this ProfileService method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

The pbstrXML parameter contains valid data only if the method completes successfully.

See Also

ProfileService Object

Profile XML Structures


IProfileService::Initialize

Use this method to establish a connection to the Commerce Server Profiles store and populate the schema cache with all the schemas from the specified catalog.

Definition

HRESULT IProfileService::Initialize(
BSTR sConfigStore,
BSTR sCatalog
);

Parameters

sConfigStore

[in] A BSTR that contains the connection string to the Profiles store.

sCatalog

[in, optional] A BSTR that identifies the catalog. If this is specified it must be "Profile Definitions".

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

The Errors property stores the collection of errors encountered in the last Profiles resource operation. For more information, see IProfileService::get_Errors.

Remarks

The Initialize method creates the necessary internal parameters and schema cache for profile management. A ProfileService object must connect to only one Profiles store. Multiple instances of the ProfileService object must be created to access multiple stores.

The connection string for the Profiles store may be obtained through the SiteConfigReadOnly object, or through the Commerce Server Manager console from the s_ProfileServiceConnectionString property under the key "Commerce Server Manager\Global Resources\Profiles(ComputerName SiteName)".

The connection string is comprised of the following mandatory tokens:

  • Data Source and/or Database [mandatory]. This attribute allows applications to specify the name of the underlying SQL Server containing the Profiles database. At least one of these attributes must be specified. If both of these attributes are specified, the value of the Data Source attribute takes precedence.

  • Initial Catalog and/or Server [mandatory]. This attribute allows applications to specify the name of the Profiles database containing profile definitions. At least one of these attributes must be specified. If both of these attributes are specified, the value of the Initial Catalog attribute takes precedence.

  • User ID and/or UID [mandatory]. This attribute allows applications to specify the login name to connect to the Profiles database. At least one of these attributes must be specified. If both of these attributes are specified, the value of the User ID attribute takes precedence.

The following is a sample connection string containing these attributes:

   Data Source=servername;Initial Catalog=dbname;User ID=user

Spaces are not allowed around the delimiting semi-colon, and a semi-colon is not allowed in the names of any of the tokens.

Additionally, the following optional tokens are also supported by the Profiles resource:

  • Provider [optional]. Allows applications to specify the OLE DB provider to which the Profiles resource connects. This parameter exists for consistency with standard ADO connection strings. The default value and only acceptable value for this attribute is CSOLEDB.

  • Password [optional]. Allows applications to specify the password for the user specified by the User ID or UID attribute. The default value for this attribute is NULL.

  • PsObjectCacheSize [optional]. Allows applications to specify the size of the Profiles resource object cache. This cache stores ProfileObject objects instantiated by the CreateProfile and GetProfile methods. The default value for this attribute is 32768.

  • PsSchemaCacheSize [optional]. Allows applications to specify the size of the Profiles resource definition (schema) cache. Once loaded, entries cannot be purged from the cache. The default value for this attribute is 64.

  • PsBackgroundThread [optional]. Allows applications to control the creation of a background thread to periodically clean up entries from the Profiles resource object cache. The acceptable values for this parameter are zero (0) or one (1). Zero turns off the background thread, one turns it on. By default, the background thread is on.

  • PsObjectAgeoutPeriod [optional]. Allows applications to specify the age-out period for the Profiles resource cache entries. The age-out period is the amount of time an unreferenced object can remain in the cache without being discarded. The default value for this attribute is five minutes.

Notes

  • The Initial Catalog in the connection string is the database containing the Profiles store.

  • The sCatalog parameter in the Initialize method is the catalog containing the profile schema definitions, which is "Profile Definitions".

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

ProfileService Object


IProfileService::Unbind

Use this method to clear the credentials that are used to access ProfileObject objects in the underlying Profiles store.

Definition

HRESULT IProfileService::Unbind (
);

Parameters

None.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

The Errors property stores the collection of errors encountered in the last Profiles resource operation. For more information, see IProfileService::get_Errors.

Remarks

This method clears the credentials used to access ProfileObject objects in the underlying store. Any new profiles or modifications will not be bound to a specific user. Use this method to gain access to existing ProfileObject objects that are not bound to a specific user.

Use the Bind method to set the credentials to access ProfileObject objects that are bound to a specific user.

Call the Initialize method before you use this ProfileService method.

See Also

ProfileService Object

IProfileService::BindAs


ReportRenderer Object

Use this object to render (display) or export a static report synchronously.

ProgID: | Commerce.ReportRenderer (Externally creatable)
COM Class Name: | ReportRenderer
COM Interface Name: | _ReportRenderer
Interface ID Constant: | None
Header File: | None
Type Library Name: | Microsoft Commerce 2000 Report Renderer Type Library
DLL Name: | ReportRenderer.dll
Threading Model: | Both

In C++, use the _ReportRenderer interface to access the methods of the ReportRenderer object.

Because this object is primarily intended for use within ASP script, access from C++ will not be common.

The methods of the ReportRenderer object are shown in the following table.

Method | Description
Init | Initializes the object.

Remarks

The ReportRender object must be passed the ReportStatusID parameter of the report to be rendered in its initialization string. This parameter is set when the report is run or exported from the Reports module.

Exporting a static report writes a result table to a target database. The ListManager object imports from this table using the CreateFromDWCalc method of the ListManager object.

The ReportRender object runs synchronously. Use the AsyncRpt object to run static reports asynchronously.

The ReportRenderer object is a Microsoft Visual Basic component.

See Also

Analysis/Reporting Schema

Analysis/Reporting XML Structures

Creating Custom Reports

AsyncRpt Object

ListManager Object

Running Reports


_ReportRenderer::Init

Use this method to initialize the ReportRenderer object and to render or export a static report synchronously.

Definition

HRESULT IReportRenderer::Init(
BSTR* sParamString,
VARIANT_BOOL* pvResult
);

Parameters

sParamString

[in, out] A pointer to a BSTR used to supply parameters to the ReportRenderer object.

pvResult

[out, retval] A pointer to a VARIANT_BOOL used to indicate whether the initialization was successful. True (1) indicates success.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The sParamString parameter consists of a string containing six parameters delineated by the '|' symbol. The string is of the form:

   "ReportStatusID|Data warehouse connection string|
    OLAP connection string|Destination connection string|
    Destination table name|Report execution time"

The possible parameters consist of the following:

  • ReportStatusID - used to identify the report to be displayed or exported. This parameter is stored in the ReportStatus table which is created when a report is run or exported.

  • Data warehouse connection string - where the underlying data is stored. A valid connection string is of the type "DRIVER={SQL Server};SERVER=Server Name;DATABASE=Database Name;UID=username;PWD=password;".

  • OLAP connection string - where the underlying OLAP data is stored. A valid connection string is of the type "DATA SOURCE=Server Name;INITIAL CATALOG=Database Name;".

  • Destination connection string - where the table that will contain the exported report data is located. A valid connection string is of the type "SERVER=Server Name;DATABASE=Database Name;UID=username;PWD=password;".

  • Destination table name - the table that will contain the exported report data.

  • Report execution time - the time when the report was executed. If not supplied, this defaults to the current time in the format of the client computer.

The actual parameters used depend on the type of report (SQL or MDX) and whether the report is being displayed or exported. The ReportStatusID and the Data warehouse connection string parameters are required in all cases. The remaining parameters are required, as shown in the following table. Parameters not used are left blank.

Action- Report Type | Report StatusID | Data Warehouse connection string | OLAP connection string | Destination connection string | Destination table name | Report execution time
Display-SQL | X | X |  |  |  | X
Display-MDX | X | X | X |  |  | X
Export-SQL | X | X |  | X | X |
Export-MDX | X | X | X | X | X |

The ReportRenderer object constrains displayed reports with the following limitations:

  • Maximum of 1000 rows.

  • Maximum of 50 columns.

  • Maximum of 5 dimension levels for each row or column dimension.

The number of rows and columns is determined by the report query, report parameters, and report definitions. The number of dimensions is set in the ReportDimension table (for SQL queries) when the report is created. Trying to display a report outside these limitations results in the report being truncated at the above limits. There are no limits when exporting a report. For information on the report tables, see Analysis/Reporting Schema.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

The pvResult parameter contains valid data only if the method completes successfully.

See Also

ReportRenderer Object

Analysis/Reporting Schema

Creating Custom Reports


RowCollection Object

Use this object to access data contained in a ContentList object and its corresponding ContentListFactory object. Some RowCollection objects allow access to all of the rows in these objects. Other RowCollection objects allow access to a calculated subset of the rows in these objects.

ProgID: | Dependent (See the Remarks section for more information)
COM Class Name: | RowCollection
COM Interface Name: | IRowCollection
Interface ID Constant: | IID_IRowCollection
Header File: | cacheint.h, mspu_guids.h
Type Library Name: | Microsoft Commerce 2000 Cache Manager Type Library
DLL Name: | mscscache.dll
Threading Model: | Both

In C++, use the IRowCollection interface to access to the methods and properties of a RowCollection object.

The properties of the RowCollection object are shown in the following table.

Property | Type | Description
_NewEnum | IUnknown | Allows iteration through the rows in the RowCollection object using the Microsoft Visual Basic "for each Row in Collection" syntax. This property is read-only.
Count | long | Stores the number of rows in the RowCollection object. This property is read-only.
EOF | VARIANT_BOOL | Tracks whether the current row is beyond the actual number of rows in the RowCollection object. This property is read-only.
Fields | Fields | Contains the Fields collection object for the current row. This property is read-only.
RowNum | long | Stores the position of the current row, starting from zero (0). This property is read-only.

The methods of the RowCollection object are shown in the following table.

Method | Description
MoveFirst | Sets the first row in the RowCollection object to be the current row.
MoveNext | Sets the row after the current row in the RowCollection object to be the new current row.

Remarks

The RowCollection object is a dependent object. Obtain a pointer to the IRowCollection interface by calling one of the following methods:

  • IContentList::get_ActiveRows

  • IContentList::get_AllRows

  • IContentList::Search

  • IContentListFactory::get_AllRows

  • IContentListFactory::Search


IRowCollection::get__NewEnum

The read-only _NewEnum property provides a mechanism for enumerating through the rows in a RowCollection object using the Microsoft Visual Basic "for each Row in Collection" syntax. Each row in the collection is a Fields collection object that can be used to access the individual fields in the row.

Definition

Get method:

HRESULT IRowCollection::get__NewEnum(
IUnknown** _NewEnum
);

Parameters

_NewEnum

[out,retval] When getting the property, an IUnknown interface pointer used to return a pointer to an IEnumVARIANT interface, which manages the iteration of the rows in the collection.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

This property exists so that the "for each Row in Collection" syntax in Microsoft Visual Basic can be used to iterate through the rows in a RowCollection object. This property is not accessed directly.

See Also

RowCollection Object


IRowCollection::get_Count

The Count property is a read-only Long that contains the number of rows in the collection.

Definition

Get method:

HRESULT IRowCollection::get_Count(
long* Count
);

Parameters

Count

[out,retval] A long that contains the number of rows in the RowCollection object.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

See Also

RowCollection Object


IRowCollection::get_EOF

The EOF property is a read-only Boolean that returns True when the end of the collection has been reached.

Definition

Get method:

HRESULT IRowCollection::get_EOF(
VARIANT_BOOL* EOF
);

Parameters

EOF

[out,retval] A pointer to a VARIANT_BOOL used to return an indication of whether row iteration is complete.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

See Also

RowCollection Object


IRowCollection::get_Fields

The Fields property is a read-only Fields collection object that contains the Field objects for the current row.

Definition

Get method:

HRESULT IRowCollection::get_Fields(
Fields** Fields
);

Parameters

Fields

[out,retval]A pointer to an ActiveX Data Objects (ADO) Fields object used to return the fields of the current row.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The Fields object associated with this property corresponds to the current row in the RowCollection object. When the EOF property is True, indicating that the current row is set beyond the actual rows in the collection, accessing this property will result in an error.

See Also

RowCollection Object


IRowCollection::MoveFirst

Use this method to set the current row to be the first row in a RowCollection object.

Definition

HRESULT IRowCollection::MoveFirst(
);

Parameters

None.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

See Also

RowCollection Object


IRowCollection::MoveNext

Use this method to set the current row to be the row that is one row beyond the current row. In other words, the next row in the collection.

Definition

HRESULT IRowCollection::MoveNext(
);

Parameters

None.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

See Also

RowCollection Object


IRowCollection::get_RowNum

The RowNum property is a read-only number that contains the position of the current row within the RowCollection object. Row positions begin at zero (0), not one (1).

Definition

Get method:

HRESULT IRowCollection::get_RowNum(
long* RowNum
);

Parameters

RowNum

[out,retval] A long used to return the position of the current row in the RowCollection object. Row positions begin at zero (0), not one (1).

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The value of this property corresponds to the current row in the RowCollection object. When the EOF property is True, indicating that the current row is set beyond the actual rows in the collection, accessing this property will result in an error.

See Also

RowCollection Object


Shipping Object

Use this object to create shipping cost preview information.

ProgID: | Commerce.Shipping (Externally creatable)
COM Class Name: | Shipping
COM Interface Name: | _Shipping
Interface ID Constant: | None
Header File: | None
Type Library Name: | Microsoft Commerce 2000 Shipping Components Type Library
DLL Name: | shipmgr.dll
Threading Model: | Apartment

Because this object is primarily intended for use within ASP script, access from C++ will not be common.

The single method of the Shipping object is shown in the following table.

Method | Description
PreviewShipments | Divides an order into shipments and produces shipping cost previews for each shipment using each method.


_Shipping::PreviewShipments

Use this method to create shipment preview information.

Definition

HRESULT _Shipping::PreviewShipments(
VARIANT* orderform,
VARIANT* context,
VARIANT* ShipmentDistinguishers,
VARIANT* ShippingPreview
);

Parameters

orderform

[in] A pointer to a VARIANT containing the OrderForm dictionary for which to calculate shipping cost previews.

context

[in] A pointer to a VARIANT containing the Context dictionary to use to run the shipping components.

ShipmentDistinguishers

[in] A pointer to a VARIANT containing a SIMPLEARRAY of strings containing the line item attributes (keys) to use to split the order into shipments.

ShippingPreview

[out, retval] A pointer to a VARIANT used to return a Simplelist of dictionaries, one for each shipment, which in turn contain a Simplelist of dictionaries containing the shipping cost previews, one for each shipping method.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The ShippingPreview parameter points to valid data only if the method completes successfully.

The PreviewShipments method creates the shipping cost previews by splitting the order into individual shipments. The mechanism used is the same as the Splitter pipeline component. For more information about how shipment distinguishers are used to split shipments, see Splitter.

The PreviewShipments method returns a SimpleList of dictionaries, one for each shipment. Each shipment dictionary in turn contains a SimpleList of dictionaries each of which contains the shipping cost for using a particular shipping method.

For example code showing how to loop through the preview shipments, see Previewing Shipping Costs.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Previewing Shipping Costs

Shipping Object

ShippingDiscountAdjust

ShippingManagerCache

ShippingMethodManager Object

ShippingMethodRouter

StepwiseShipping


ShippingMethodManager Object

Use this object to manage shipping methods that will be available on the site. The ShippingMethodManager object lets you add and remove methods, and set their description, availability, and configuration.

ProgID: | Commerce.ShippingMethodManager (Externally creatable)
COM Class Name: | ShippingMethodManager
COM Interface Name: | _ShippingMethodManager
Interface ID Constant: | None
Header File: | None
Type Library Name: | Microsoft Commerce 2000 Shipping Components Type Library
DLL Name: | shipmgr.dll
Threading Model: | Apartment

Because this object is primarily intended for use within ASP script, access from C++ will not be common.

The methods of the ShippingMethodManager object are shown in the following table.

Method | Description
CreateMethodInstance | Creates an empty instance of a shipping method.
DeleteMethodInstance | Deletes the current shipping method instance.
GetComponentConfig | Retrieves the Configuration dictionary for the shipping component, which implements the current shipping method.
GetInstalledMethodList | Returns a recordset containing the current shipping methods.
GetMethodInfo | Returns a recordset containing information about one or more shipping methods.
Initialize | Initializes the ShippingMethodManager object and connects it to a database.
LoadMethodInstance | Loads a given shipping method to be manipulated by other methods.
SaveMethodConfig | Saves information about the current method.
SetCachableComponentConfig | Saves configuration and other component information for a component.
SetMethodConfig | Sets pairs of names and values for the current method

Remarks

The shipping architecture in Commerce Server 2000 is designed so that shipping methods can be changed through the Shipping Methods module in Commerce Server Business Desk without programming or editing pipelines. To do this, Commerce Server maintains a database table, ShippingConfig, of shipping methods and the information required to configure shipping components to implement those methods.

The ShippingMethodManager object is used by Business Desk to manage the ShippingConfig database table.

For more information about shipping objects, see the Multiple Shipment Architecture Overview.


_ShippingMethodManager::CreateMethodInstance

Use this method to create a new shipping method.

Definition

HRESULT __ShippingMethodManager::CreateMethodInstance(
VARIANT* bOnDisk,
VARIANT* sMethodId
);

Parameters

bOnDisk

[in] A VARIANT containing a Boolean indicating whether or not to create the shipping method on disk. This parameter is usually set to True

sMethodId

[out, retval] A VARIANT containing a BSTR that is the method ID of the new method. Set to an empty string if the bOnDisk parameter is False.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The sMethodId parameter contains valid data only if the method completes successfully.

If the shipping method is created to be saved on disk (the bOnSaved parameter is True), the function adds a new record to the current recordset with the enabled column value set to zero (0) and the shipping_method_id column set to the new shipping method ID.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Splitter

Shipping Object

ShippingDiscountAdjust

ShippingManagerCache

ShippingMethodManager Object

ShippingMethodRouter

StepwiseShipping


_ShippingMethodManager::DeleteMethodInstance

Use this method to delete the current shipping method instance.

Definition

HRESULT _ShippingMethodManager::DeleteMethodInstance(void);

Parameters

None.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

This method acts on the loaded shipping method. You must call LoadMethodInstance or CreateMethodInstance to load a shipping method into the ShippingMethodManager object before calling this method.

See Also

Splitter

Shipping Object

ShippingDiscountAdjust

ShippingManagerCache

ShippingMethodManager Object

ShippingMethodRouter

StepwiseShipping


_ShippingMethodManager::GetComponentConfig

Use this method to retrieve the Configuration dictionary for the shipping component to implement the current shipping method. The shipping method must be loaded using LoadMethodInstance before calling GetComponentConfig.

Definition

HRESULT _ShippingMethodManager::GetComponentConfig(
VARIANT* dConfig
);

Parameters

dConfig

[out, retval] A pointer to a VARIANT containing the Configuration dictionary.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

This method acts on the loaded shipping method. You must call LoadMethodInstance or CreateMethodInstance to load a shipping method into the ShippingMethodManager object before calling this method.

The dConfig parameter points to valid data only if the method completes successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Splitter

Shipping Object

ShippingDiscountAdjust

ShippingManagerCache

ShippingMethodManager Object

ShippingMethodRouter

StepwiseShipping


_ShippingMethodManager::GetInstalledMethodList

Use this method to get a list of the current shipping methods. The GetInstalledMethodList method allows you to filter the list, select the columns to return, and to sort the list into a particular order.

Definition

HRESULT _ShippingMethodManager::GetInstalledMethodList(
VARIANT* Filter,
VARIANT* OrderBy,
VARIANT* columns,
VARIANT* rsReturn
);

Parameters

Filter

[in] A pointer to a VARIANT that contains a BSTR that becomes the WHERE clause of the query. Pass a null variant if no filtering is wanted. An example filter is "enabled = 1", this will cause GetInstalledMethodList to only return enabled shipping methods.

OrderBy

[in] A pointer to a VARIANT that contains a BSTR that becomes the ORDER BY clause of the query. Pass a null variant if no ordering is wanted. An example OrderBy argument is "shipping_method_name", which will cause the results to be sorted by shipping_method_name.

columns

[in] A pointer to a VARIANT that contains a SAFEARRAY of column names of the values to retrieve. If an empty array is passed, all columns from the ShippingConfig table are returned.

rsReturn

[out, retval] A pointer to a VARIANT containing an ADO Recordset object with the wanted values.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The rsResult parameter points to valid data only if the method completes successfully.

The GetInstalledMethodList method constructs a SQL query from its three parameters, runs it against the current ShippingConfig table, and returns the result in an ADO Recordset object.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Splitter

Shipping Object

ShippingDiscountAdjust

ShippingManagerCache

ShippingMethodManager Object

ShippingMethodRouter

StepwiseShipping


_ShippingMethodManager::GetMethodInfo

Use this method to retrieve information about the database attributes of one or more columns in the ShippingConfig table.

Definition

HRESULT _ShippingMethodManager::GetMethodInfo(
VARIANT* columns,
VARIANT* rsResult
);

Parameters

columns

[in] A VARIANT containing a SAFEARRAY of BSTR strings containing names of the columns. Specify an empty array to return all columns.

rsResult

[out, retval] A pointer to a VARIANT containing an ADO Recordset object that contains the information about the requested database columns.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The rsResult parameter points to valid data only if the method completes successfully.

This method acts on the loaded shipping method. You must call LoadMethodInstance or CreateMethodInstance to load a shipping method into the ShippingMethodManager object before calling this method.

This method returns an ADO Recordset object containing the data type, defined size, and attributes of the requested columns in the ShippingConfig table.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Splitter

Shipping Object

ShippingDiscountAdjust

ShippingManagerCache

ShippingMethodManager Object

ShippingMethodRouter

StepwiseShipping


_ShippingMethodManager::Initialize

Use this method to initialize a ShippingMethodManager object and connect it to a database.

Definition

HRESULT _ShippingMethodManager::Initialize(
VARIANT* connection_string
);

Parameters

connection_string

[in] A pointer to a VARIANT containing a BSTR with the connection string.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Splitter

Shipping Object

ShippingDiscountAdjust

ShippingManagerCache

ShippingMethodManager Object

ShippingMethodRouter

StepwiseShipping


_ShippingMethodManager::LoadMethodInstance

Use this method to load an instance of a given shipping method.

Definition

HRESULT _ShippingMethodManager::LoadMethodInstance(
VARIANT* methodid
);

Parameters

methodid

[in] A pointer to a VARIANT containing a BSTR that is the method ID of the shipping method.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

This method loads an instance of the requested shipping method as a single record in the current recordset.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Splitter

Shipping Object

ShippingDiscountAdjust

ShippingManagerCache

ShippingMethodManager Object

ShippingMethodRouter

StepwiseShipping


_ShippingMethodManager::SaveMethodConfig

Use this method to save the current shipping method information set with the SetMethodConfig method.

Definition

HRESULT __ShippingMethodManager::SaveMethodConfig(void);

Parameters

None.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The SaveMethodConfig method saves the current shipping method configuration data.

This method acts on the loaded shipping method. You must call LoadMethodInstance or CreateMethodInstance to load a shipping method into the ShippingMethodManager object before calling this method.

See Also

Splitter

Shipping Object

ShippingDiscountAdjust

ShippingManagerCache

ShippingMethodManager Object

ShippingMethodRouter

StepwiseShipping


_ShippingMethodManager::SetCachableComponentConfig

Use this method to set the configuration data for the pipeline component, and other component information.

Definition

HRESULT __ShippingMethodManager::SetCachableComponentConfig(
VARIANT* progid,
VARIANT* configdict,
VARIANT* action,
VARIANT* actionfriendlyname
);

Parameters

progid

[in] A pointer to a VARIANT containing a BSTR that is the ProgID of the pipeline component.

configdict

[in] A VARIANT containing a Dictionary object holding the configuration information for the component.

action

[in] A VARIANT containing a BSTR with the name of the ASP edit page for the shipping component.

actionfriendlyname

[in] A VARIANT containing a BSTR with a friendly name for the ASP edit page for the shipping component.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

This method acts on the loaded shipping method. You must call LoadMethodInstance or CreateMethodInstance to load a shipping method into the ShippingMethodManager object before calling this method.

This method takes the Configuration dictionary for the component and prepares it to be saved along with the current configuration. In addition, the method stores the ProgID, the edit page, and the page friendly names. The settings are not saved until the SaveMethodConfig method is called.

The configdict parameter is typically obtained using IPipelineComponentAdmin::GetConfigDictionary.

This method utilizes the IPipelineComponentAdmin interface; therefore all shipping components configurable by the ShippingMethodManager object must support the IPipelineComponentAdmin interface.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Splitter

Shipping Object

ShippingDiscountAdjust

ShippingManagerCache

ShippingMethodManager Object

ShippingMethodRouter

StepwiseShipping


_ShippingMethodManager::SetMethodConfig

Use this method to set properties such as name or description, on the current shipping method.

Definition

HRESULT _ShippingMethodManager::SetMethodConfig(
VARIANT* ParametersAndValues
);

Parameters

ParametersAndValues

[in] A pointer to a VARIANT containing a SAFEARRAY that contains name and value pairs in successive elements.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

This method acts on the loaded shipping method. You must call LoadMethodInstance or CreateMethodInstance to load a shipping method into the ShippingMethodManager object before calling this method.

The array parameter contains names and values in alternating elements. Odd subscripts contain the names of items, even subscripts contain the values.

Use the SaveMethodConfig method to save the configuration information entered with this method.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

Splitter

Shipping Object

ShippingDiscountAdjust

ShippingManagerCache

ShippingMethodManager Object

ShippingMethodRouter

StepwiseShipping


SimpleFindResultInfo Object

Use this object to specify search criteria when using the SimpleFind and SimpleDelete methods of the OrderGroupManager object.

ProgID: | Commerce.SimpleFindResultInfo (Externally creatable)
COM Class Name: | SimpleFindResultInfo
COM Interface Name: | _SimpleFindResultInfo
Interface ID Constant: | None
Header File: | None
Type Library Name: | Microsoft Commerce 2000 OrderGroup Type Library
DLL Name: | requisition.dll
Threading Model: | Apartment

In C++, use the _SimpleFindResultInfo interface to access the properties and methods of the SimpleFindResultInfo object.

Because this object is primarily intended for use within ASP script, access from C++ will not be common.

The properties of the SimpleFindResultInfo object are shown in the following table.

Property | Type | Description
Columns | VARIANT | Specifies a custom set of columns to be returned by the OrderGroupManager SimpleFind method.
JoinLineItemInfo | VARIANT_BOOLEAN | Specifies whether to join the OrderFormLineItems table with the results.
JoinOrderFormInfo | VARIANT_BOOLEAN | Specifies whether the OrderFormHeader table is joined in the results.
OrderGroupSortColumn | VARIANT | Specifies the column name to sort on.
PageNumber | Long | Specifies the page number of the resultset to show if the resultset exceeds the PageSize.
PageSize | Long | Specifies the page size.
SortDirection | VARIANT | Specifies the sort direction.

Remarks

The following table shows the data returned by the OrderGroupManager SimpleFind method when it has been passed to the SimpleFindResultInfo object with the JoinOrderFormInfo and JoinLineItemInfo properties set to the indicated values.

JoinOrderFormInfo | JoinLineItemInfo | SimpleFind Method Data Returned
False | False | One record for each OrderGroup that meets the search criteria. Returns OrderGroup data only. The default setting is False.
True | False | One record for each OrderForm that meets the search criteria. Returns OrderGroup and OrderForm data.
True | True | One record for each line item that meets the search criteria. Returns OrderGroup, OrderForm, and line item data.
False | True | One record for each line item that meets the search criteria. Returns OrderGroup, OrderForm, and line item data.

See Also

Business Process Objects

SimpleFindSearchInfo Object

OrderGroupManager Object

OrderGroup Object

OrderForm Object


_SimpleFindResultInfo::get_Columns, put_Columns

The Columns property is a read/write Variant that specifies a custom set of columns to be returned by the SimpleFind method. The columns property, if specified, should be a string of comma-separated column names. If the property is left Null, SimpleFind will return a standard set of columns.

Definition

Get method:

HRESULT _SimpleFindResultInfo::get_Columns(
VARIANT* Columns
);

Put method:

HRESULT _SimpleFindResultInfo::put_Columns(
VARIANT* Columns
);

Parameters

Columns

[in] When putting the property, a VARIANT that contains the names of the columns to return in addition to the default columns.
[out, retval] When getting the property, a VARIANT used to return the names of the columns in addition to the default columns.

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The Columns parameter contains valid data only if the property is accessed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Requirements for using this property are listed in SimpleFindResultInfo Object.

See Also

SimpleFindResultInfo Object


_SimpleFindResultInfo::get_JoinLineItemInfo, put_JoinLineItemInfo

The JoinLineItemInfo property is a read/write Boolean that indicates whether to join the OrderFormLineItems table with the results.

Definition

Get method:

HRESULT _SimpleFindResultInfo::get_JoinLineItemInfo(
VARIANT_BOOL* JoinLineItemInfo
);

Put method:

HRESULT _SimpleFindResultInfo::put_JoinLineItemInfo(
VARIANT_BOOL JoinLineItemInfo
);

Parameters

JoinLineItemInfo

[in] When putting the property, a VARIANT BOOLEAN that specifies whether the OrderFormLineItems table is to be joined with the results. A value of True specifies that the OrderFormLineItems table will be joined. A value of False specifies that it will not be joined.
[out, retval] When getting the property, a VARIANT BOOLEAN that indicates whether the OrderFormLineItems table is to be joined with the results. A value of True indicates that the OrderFormLineItems table will be joined. A value of False indicates that it will not be joined.

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The JoinLineItemInfo parameter contains valid data only if the property is accessed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Requirements for using this property are listed in SimpleFindResultInfo Object.

See Also

SimpleFindResultInfo Object


_SimpleFindResultInfo::get_JoinOrderFormInfo, put_JoinOrderFormInfo

The JoinOrderFormInfo property is a read/write Boolean that indicates whether the OrderFormHeader table is joined in the results.

Definition

Get method:

HRESULT _SimpleFindResultInfo::get_JoinOrderFormInfo(
VARIANT_BOOL* JoinOrderFormInfo
);

Put method:

HRESULT _SimpleFindResultInfo::put_JoinOrderFormInfo(
VARIANT_BOOL JoinOrderFormInfo
);

Parameters

JoinOrderFormInfo

[in] When putting the property, a VARIANT BOOLEAN that specifies whether the OrderFormHeader table is to be joined with the results. A value of True specifies that the OrderFormHeader table will be joined. A value of False specifies that it will not be joined.
[out, retval] When getting the property, a VARIANT BOOLEAN that indicates whether the OrderFormHeader table is to be joined with the results. A value of True indicates that the OrderFormHeader table will be joined. A value of False indicates that it will not be joined.

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The JoinOrderFormInfo parameter contains valid data only if the property is accessed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Requirements for using this property are listed in SimpleFindResultInfo Object.

See Also

SimpleFindResultInfo Object


_SimpleFindResultInfo::get_OrderGroupSortColumn, put_OrderGroupSortColumn

The OrderGroupSortColumn property is a read/write Variant that contains the column name on which to sort.

Definition

Get method:

HRESULT _SimpleFindResultInfo::get_OrderGroupSortColumn(
VARIANT* OrderGroupSortColumn
);

Put method:

HRESULT _SimpleFindResultInfo::put_OrderGroupSortColumn(
VARIANT* OrderGroupSortColumn
);

Parameters

OrderGroupSortColumn

[in] When putting the property, a VARIANT that contains the name of the column on which to sort.
[out, retval] When getting the property, a VARIANT used to return the name of the column on which to sort.

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The OrderGroupSortColumn parameter contains valid data only if the property is accessed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Requirements for using this property are listed in SimpleFindResultInfo Object.

See Also

SimpleFindResultInfo Object


_SimpleFindResultInfo::get_PageNumber, put_PageNumber

The PageNumber property is a read/write Long that contains the page number to jump to. This property setting must be coordinated with the PageSize property.

Definition

Get method:

HRESULT _SimpleFindResultInfo::get_PageNumber(
long* PageNumber
);

Put method:

HRESULT _SimpleFindResultInfo::put_PageNumber(
long PageNumber
);

Parameters

PageNumber

[in] When putting the property, a long that contains the page number.
[out, retval] When getting the property, a long used to return the page number.

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The PageNumber parameter contains valid data only if the property is accessed successfully.

Use this property to implement a paging mechanism that allows you to page through your orders. (These orders could be viewed in a List Sheet, for example.)

This property is initialized to 1.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Requirements for using this property are listed in SimpleFindResultInfo Object.

See Also

SimpleFindResultInfo Object


_SimpleFindResultInfo::get_PageSize, put_PageSize

The PageSize property is a read/write Long that contains the page size. This property setting must be coordinated with the PageNumber property.

Definition

Get method:

HRESULT _SimpleFindResultInfo::get_PageSize(
long* PageSize
);

Put method:

HRESULT _SimpleFindResultInfo::put_PageSize(
long PageSize
);

Parameters

PageSize

[in] When putting the property, a long that contains the page size.
[out, retval] When getting the property, a long used to return the page size.

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The PageSize parameter contains valid data only if the property is accessed successfully.

Use this property to implement a paging mechanism that allows you to page through your orders. (These orders could be viewed in a List Sheet, for example.)

This property defaults to 20.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Requirements for using this property are listed in SimpleFindResultInfo Object.

See Also

SimpleFindResultInfo Object


_SimpleFindResultInfo::get_SortDirection, put_SortDirection

The SortDirection property is a read/write Variant that contains the sort direction. The value of this field can be "asc" for ascending or "desc" for descending.

Definition

Get method:

HRESULT _SimpleFindResultInfo::get_SortDirection(
VARIANT* SortDirection
);

Put method:

HRESULT _SimpleFindResultInfo::put_SortDirection(
VARIANT* SortDirection
);

Parameters

SortDirection

[in] When putting the property, a VARIANT that contains the sort direction.
[out, retval] When getting the property, a VARIANT used to return the sort direction.

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The SortDirection parameter contains valid data only if the property is accessed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

Requirements for using this property are listed in SimpleFindResultInfo Object.

See Also

SimpleFindResultInfo Object


SimpleFindSearchInfo Object

Use this object to specify search criteria when conducting searching and deleting operations using the SimpleFind and SimpleDelete methods of the OrderGroupManager object.

ProgID: | Commerce.SimpleFindSearchInfo (Externally creatable)
COM Class Name: | SimpleFindSearchInfo
COM Interface Name: | _SimpleFindSearchInfo
Interface ID Constant: | None
Header File: | None
Type Library Name: | Microsoft Commerce 2000 OrderGroup Type Library
DLL Name: | requisition.dll
Threading Model: | Apartment

In C++, use the _SimpleFindSearchInfo interface to access the properties and methods of the SimpleFindSearchInfo object.

Because this object is primarily intended for use within ASP script, access from C++ will not be common.

The properties of the SimpleFindSearchInfo object are shown in the following table.

Property | Type | Description
description | VARIANT | Specifies the product description to search for; if left null, the product description does not become part of the search criteria. This property is read/write.
order_number | VARIANT | Specifies the order number to search for; if left null, the order number does not become part of the search criteria. This property is read/write.
ordergroup_id | VARIANT | Specifies the OrderGroup ID to search for; if left null, the OrderGroup ID does not become part of the search criteria. This property is read/write.
po_number | VARIANT | Specifies the OrderForm ID to search for; if left null, the OrderForm ID does not become part of the search criteria. This property is read/write.
product_id | VARIANT | Specifies the product ID to search for; if left null, the product ID does not become part of the search criteria. This property is read/write.
SearchDateTimeColumn | VARIANT | Specifies the DateTime column name to search for; if left null, the DateTime column name does not become part of the search criteria. This property is read/write.
SearchDateTimeEnd | VARIANT | Specifies the DateTime end value to search for; if left null, the DateTime end value does not become part of the search criteria. This property is read/write.
SearchDateTimeStart | VARIANT | Specifies the DateTime start value to search for; if left null, the DateTime start value does not become part of the search criteria. This property is read/write.
StatusFilter | long | Specifies the OrderGroup status. This property allows the user to filter the status (ie basket, template or new order). This property is read/write.
user_firstname | VARIANT | Specifies the first name of the user to search for; if left null, the first name of the user does not become part of the search criteria. This property is read/write.
user_id | VARIANT | Specifies the user ID to search for; if left null, the user ID does not become part of the search criteria. This property is read/write.
user_lastname | VARIANT | Specifies the last name of the user to search for; if left null, the last name of the user does not become part of the search criteria. This property is read/write.
user_org_id | VARIANT | Specifies the user organization ID to search for; if left null, the user organization ID does not become part of the search criteria. This property is read/write.
user_org_name | VARIANT | Specifies the user organization to search for; if left null, the user organization does not become part of the search criteria. This property is read/write.

See Also

Business Process Objects

SimpleFindResultInfo Object

OrderGroupManager Object

OrderGroup Object

OrderForm Object


_SimpleFindSearchInfo::get_description, put_description

The description property is a read/write Variant that specifies the product description to search for; if left null, the product description does not become part of the search criteria.

Definition

Get method:

HRESULT _SimpleFindSearchInfo::get_description(
VARIANT* description
);

Put method:

HRESULT _SimpleFindSearchInfo::put_description(
VARIANT* description
);

Parameters

description

[in] When putting the property, a VARIANT that contains the item description to search for.
[out, retval] When getting the property, a VARIANT used to return the item description to search for.

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The description parameter contains valid data only if the property is accessed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

SimpleFindSearchInfo Object

OrderGroupManager::SimpleDelete

OrderGroupManager::SimpleFind


_SimpleFindSearchInfo::get_order_number, put_order_number

The order_number property is a read/write Variant that specifies the order number to search for; if left null, the order number does not become part of the search criteria.

Definition

Get method:

HRESULT _SimpleFindSearchInfo::get_order_number(
VARIANT* order_number
);

Put method:

HRESULT _SimpleFindSearchInfo::put_order_number(
VARIANT* order_number
);

Parameters

order_number

[in] When putting the property, a VARIANT that contains the order number to search for.
[out, retval] When getting the property, a VARIANT used to return the order number to search for.

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The order_number parameter contains valid data only if the property is accessed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

SimpleFindSearchInfo Object

OrderGroupManager::SimpleDelete

OrderGroupManager::SimpleFind


_SimpleFindSearchInfo::get_ordergroup_id, put_ordergroup_id

The ordergroup_id property is a read/write Variant that contains the OrderGroup ID to search for; if left null, the OrderGroup ID does not become part of the search criteria.

Definition

Get method:

HRESULT _SimpleFindSearchInfo::get_ordergroup_id(
VARIANT* ordergroup_id
);

Put method:

HRESULT _SimpleFindSearchInfo::put_ordergroup_id(
VARIANT* ordergroup_id
);

Parameters

ordergroup_id

[in] When putting the property, a VARIANT that contains the OrderGroup ID to search for.
[out, retval] When getting the property, a VARIANT used to return the OrderGroup ID to search for.

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The ordergroup_id parameter contains valid data only if the property is accessed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

SimpleFindSearchInfo Object

OrderGroupManager::SimpleDelete

OrderGroupManager::SimpleFind


_SimpleFindSearchInfo::get_po_number, put_po_number

The po_number property is a read/write Variant that contains the OrderForm ID to search for; if left null, the OrderForm ID does not become part of the search criteria.

Definition

Get method:

HRESULT _SimpleFindSearchInfo::get_po_number(
VARIANT* po_number
);

Put method:

HRESULT _SimpleFindSearchInfo::put_po_number(
VARIANT* po_number
);

Parameters

po_number

[in] When putting the property, a VARIANT that contains the OrderForm ID to search for.
[out, retval] When getting the property, a VARIANT used to return the OrderForm ID to search for.

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The po_number parameter contains valid data only if the property is accessed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

SimpleFindSearchInfo Object

OrderGroupManager::SimpleDelete

OrderGroupManager::SimpleFind


_SimpleFindSearchInfo::get_product_id, put_product_id

The product_id property is a read/write Variant that contains the product ID to search for; if left null, the product ID does not become part of the search criteria.

Definition

Get method:

HRESULT _SimpleFindSearchInfo::get_product_id(
VARIANT* product_id
);

Put method:

HRESULT _SimpleFindSearchInfo::put_product_id(
VARIANT* product_id
);

Parameters

product_id

[in] When putting the property, a VARIANT that contains the product ID to search for.
[out, retval] When getting the property, a VARIANT used to return the product ID to search for.

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The product_id parameter contains valid data only if the property is accessed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

SimpleFindSearchInfo Object

OrderGroupManager::SimpleDelete

OrderGroupManager::SimpleFind


_SimpleFindSearchInfo::get_SearchDateTimeColumn, put_SearchDateTimeColumn

The SearchDateTimeColumn property is a read/write Variant that contains the name of the DateTime column to use in the search. If left null, the DateTime column name does not become part of the search criteria.

Definition

Get method:

HRESULT _SimpleFindSearchInfo::get_SearchDateTimeColumn(
VARIANT* SearchDateTimeColumn
);

Put method:

HRESULT _SimpleFindSearchInfo::put_SearchDateTimeColumn(
VARIANT* SearchDateTimeColumn
);

Parameters

SearchDateTimeColumn

[in] When putting the property, a VARIANT that contains the name of the DateTime column to use in the search.
[out, retval] When getting the property, a VARIANT used to return the name of the DateTime column to use in the search.

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The SearchDateTimeColumn parameter contains valid data only if the property is accessed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

SimpleFindSearchInfo Object

OrderGroupManager::SimpleDelete

OrderGroupManager::SimpleFind


_SimpleFindSearchInfo::get_SearchDateTimeEnd, put_SearchDateTimeEnd

The SearchDateTimeEnd property is a read/write Variant that contains the DateTime end value to search for; if left null, the DateTime end value does not become part of the search criteria. Use this property in conjunction with the SearchDateTimeColumn property.

Definition

Get method:

HRESULT _SimpleFindSearchInfo::get_SearchDateTimeEnd(
VARIANT* SearchDateTimeEnd
);

Put method:

HRESULT _SimpleFindSearchInfo::put_SearchDateTimeEnd(
VARIANT* SearchDateTimeEnd
);

Parameters

SearchDateTimeEnd

[in] When putting the property, a VARIANT that contains the DateTime end value to search for.
[out, retval] When getting the property, a VARIANT used to return the DateTime end value to search for.

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The SearchDateTimeEnd parameter contains valid data only if the property is accessed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

SimpleFindSearchInfo Object

OrderGroupManager::SimpleDelete

OrderGroupManager::SimpleFind


_SimpleFindSearchInfo::get_SearchDateTimeStart, put_SearchDateTimeStart

The SearchDateTimeStart property is a read/write Variant that contains the DateTime start value to search for; if left null, the DateTime start value does not become part of the search criteria. Use this property in conjunction with the SearchDateTimeColumn property.

Definition

Get method:

HRESULT _SimpleFindSearchInfo::get_SearchDateTimeStart(
VARIANT* SearchDateTimeStart
);

Put method:

HRESULT _SimpleFindSearchInfo::put_SearchDateTimeStart(
VARIANT* SearchDateTimeStart
);

Parameters

SearchDateTimeStart

[in] When putting the property, a VARIANT that contains the DateTime start value to search for.
[out, retval] When getting the property, a VARIANT used to return the DateTime start value to search for.

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The SearchDateTimeStart parameter contains valid data only if the property is accessed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

SimpleFindSearchInfo Object

OrderGroupManager::SimpleDelete

OrderGroupManager::SimpleFind


_SimpleFindSearchInfo::get_StatusFilter, put_StatusFilter

The StatusFilter property is a read/write Variant that contains the OrderGroup status.

Definition

Get method:

HRESULT _SimpleFindSearchInfo::get_StatusFilter(
long* StatusFilter
);

Put method:

HRESULT _SimpleFindSearchInfo::put_StatusFilter(
long StatusFilter
);

Parameters

StatusFilter

[in] When putting the property, a long that contains the OrderGroup status.
[out, retval] When getting the property, a long used to return the OrderGroup status.

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The StatusFilter parameter contains valid data only if the property is accessed successfully.

The value of the StatusFilter parameter determines whether a search is being made for a basket, an order, a template, or a combination of these. A bit field is used to determine this. The following table shows the meaning of the individual bits.

Status Type | Value
Basket | 1
Template | 2
New Order | 4
Custom | 8
Custom | 16

Note

  • Because the contents of baskets and templates are held in one table, and the contents of OrderGroups with all other status codes (codes 4 and greater) are held elsewhere, only certain values are permissible for searches.

    The following values are permissible:

    • 1 (basket search)

    • 2 (template search)

    • 3 (basket or template)

    • 4 (new order)

    • 12 ( 4 & 8)

    • 24 (8 & 16)

    The following values are not permissible:

    • 5 (basket or new order)

    • 6 (template or new order)

    • 9 (1 & 8)

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

SimpleFindSearchInfo Object

OrderGroupManager::SimpleDelete

OrderGroupManager::SimpleFind


_SimpleFindSearchInfo::get_user_firstname, put_user_firstname

The user_firstname property is a read/write Variant that contains the first name of the user to search for; if left null, the first name of the user does not become part of the search criteria.

Definition

Get method:

HRESULT _SimpleFindSearchInfo::get_user_firstname(
VARIANT* user_firstname
);

Put method:

HRESULT _SimpleFindSearchInfo::put_user_firstname(
VARIANT* user_firstname
);

Parameters

user_firstname

[in] When putting the property, a VARIANT that contains the first name of the user to search for.
[out, retval] When getting the property, a VARIANT used to return the first name of the user to search for.

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The user_firstname parameter contains valid data only if the property is accessed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

SimpleFindSearchInfo Object

OrderGroupManager::SimpleDelete

OrderGroupManager::SimpleFind


_SimpleFindSearchInfo::get_user_id, put_user_id

The user_id property is a read/write Variant that contains the user ID to search for; if left null, the user ID does not become part of the search criteria.

Definition

Get method:

HRESULT _SimpleFindSearchInfo::get_user_id(
VARIANT* user_id
);

Put method:

HRESULT _SimpleFindSearchInfo::put_user_id(
VARIANT* user_id
);

Parameters

user_id

[in] When putting the property, a VARIANT that contains the user ID to search for.
[out, retval] When getting the property, a VARIANT used to return the user ID to search for.

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The user_id parameter contains valid data only if the property is accessed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

SimpleFindSearchInfo Object

OrderGroupManager::SimpleDelete

OrderGroupManager::SimpleFind


_SimpleFindSearchInfo::get_user_lastname, put_user_lastname

The user_lastname property is a read/write Variant that contains the last name of the user to search for; if left null, the last name of the user does not become part of the search criteria.

Definition

Get method:

HRESULT _SimpleFindSearchInfo::get_user_lastname(
VARIANT* user_lastname
);

Put method:

HRESULT _SimpleFindSearchInfo::put_user_lastname(
VARIANT* user_lastname
);

Parameters

user_lastname

[in] When putting the property, a VARIANT that contains the last name of the user to search for.
[out, retval] When getting the property, a VARIANT used to return the last name of the user to search for.

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The user_lastname parameter contains valid data only if the property is accessed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

SimpleFindSearchInfo Object

OrderGroupManager::SimpleDelete

OrderGroupManager::SimpleFind


_SimpleFindSearchInfo::get_user_org_id, put_user_org_id

The user_org_id property is a read/write Variant that contains the user organization ID to search for; if left null, the user organization ID does not become part of the search criteria.

Definition

Get method:

HRESULT _SimpleFindSearchInfo::get_user_org_id(
VARIANT* user_org_id
);

Put method:

HRESULT _SimpleFindSearchInfo::put_user_org_id(
VARIANT* user_org_id
);

Parameters

user_org_id

[in] When putting the property, a VARIANT that contains the user organization ID to search for.
[out, retval] When getting the property, a VARIANT used to return the user organization ID to search for.

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The user_org_id parameter contains valid data only if the property is accessed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

SimpleFindSearchInfo Object

OrderGroupManager::SimpleDelete

OrderGroupManager::SimpleFind


_SimpleFindSearchInfo::get_user_org_name, put_user_org_name

The user_org_name property is a read/write Variant that contains the user organization name to search for; if left null, the user organization name does not become part of the search criteria.

Definition

Get method:

HRESULT _SimpleFindSearchInfo::get_user_org_name(
VARIANT* user_org_name
);

Put method:

HRESULT _SimpleFindSearchInfo::put_user_org_name(
VARIANT* user_org_name
);

Parameters

user_org_name

[in] When putting the property, a VARIANT that contains the user organization name to search for.
[out, retval] When getting the property, a VARIANT used to return the user organization name to search for.

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The user_org_name parameter contains valid data only if the property is accessed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

SimpleFindSearchInfo Object

OrderGroupManager::SimpleDelete

OrderGroupManager::SimpleFind


SimpleList Object

Use this object to create an array of variants that supports enumeration.

ProgID: | Commerce.SimpleList (Externally creatable)
COM Class Name: | CSimpleList
COM Interface Name: | ISimpleList
Interface ID Constant: | IID_ISimpleList
Header File: | commerce.h, mspu_guids.h
Type Library Name: | Microsoft Commerce 2000 Core Components Type Library
DLL Name: | MscsCore.dll
Threading Model: | Both

In C++, use the ISimpleList interface to access the properties and methods of the SimpleList object.

The properties of the SimpleList object are shown in the following table.

Property | Type | Description
Count | long | Returns the number of elements in the SimpleList object. This property is read-only.
Item | VARIANT | Stores an element of the SimpleList object. This property is read/write.

The methods of the SimpleList object are shown in the following table.

Method | Description
Add | Adds the specified item to a SimpleList object.
Delete | Deletes a specified item from the SimpleList object.

See Also

General Purpose Objects

Dictionary Object


ISimpleList::Add

Use this method to add the specified item to this SimpleList object.

Definition

HRESULT ISimpleList::Add(
VARIANT* pVar
);

Parameters

pVar

[in] A pointer to the VARIANT to add to the SimpleList.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

SimpleList Object

ISimpleList::Delete


ISimpleList::get_Count

Use this property to return the number of elements in the SimpleList object.

Definition

HRESULT ISimpleList::get_Count(
long* Count
);

Parameters

Count

[out, retval] A pointer to a long used to return the number of items in the SimpleList.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The Count parameter points to valid data only if the method completes successfully.

The caller should always call this method before calling a SimpleList method that requires an array index in-value as a parameter (such as the Delete method).

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

SimpleList Object


ISimpleList::Delete

Use this method to delete the specified item from the SimpleList object.

Definition

HRESULT ISimpleList::Delete(
long Index
);

Parameters

Index

[in] A long that contains the index value of the item to delete.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Description
DISP_E_BADINDEX | The Index parameter references an out-of-range value. This means that Index contains a value either larger than the SimpleList or less than zero.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

SimpleList Object

ISimpleList::Add

ISimpleList::get_Count


ISimpleList::get_Item, put_Item

The Item property is a read/write Variant that contains an element of the SimpleList object. An initialized Variant is stored at a specified array index. If an item is already stored at the specified index, that item is overwritten by the put procedure.

Definition

Get method:

HRESULT ISimpleList::get_Item(
long Index,
VARIANT* Item
);

Put method:

HRESULT ISimpleList::put_Item(
long Index,
VARIANT Item
);

Putref method:

HRESULT ISimpleList::putref_Item(
long Index,
VARIANT Item
);

Parameters

Index

[in] A long that contains the index of the item.

Item

[in] When putting the property, a Variant that contains the new item.
[out, retval] When getting the property, a Variant used to return the item.

Return Values

These methods return an HRESULT indicating whether or not they completed successfully. See the Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and either standard or custom COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors.

The following table shows the custom COM errors that this method can return.

Constant | Description
DISP_E_BADINDEX | The Index parameter references an out-of-range value. This means that Index contains a value either larger than the SimpleList or less than zero.

Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The Item parameter contains valid data only if the method completes successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

When putting a value, use the putref_Item method if you are setting an object reference; use the put_Item method if you are setting a scalar value.

See Also

SimpleList Object


SiteConfig Object

Use this object to accomplish the following:

  • Create or delete site configuration information

  • Save any updated site configuration information to the Administration database

  • Load site configuration information from the Administration database

  • Import resource configuration data to a site and export resource configuration data from a site
ProgID: | Commerce.SiteConfig (Externally creatable)
COM Class Name: | SiteConfig
COM Interface Name: | _SiteConfig
Interface ID Constant: | None
Header File: | None
Type Library Name: | Microsoft Commerce 2000 Configuration Type Library
DLL Name: | MSCSCfg.dll
Threading Model: | Apartment

In C++, use the _SiteConfig interface to access the properties and methods of the SiteConfig object.

The single property of the SiteConfig object is shown in the following table.

Property | Type | Description
Fields | Fields | Returns configuration fields, some of which hold configuration settings of resources. This property is read-write.

The methods of the SiteConfig object are shown in the following table.

Method | Description
AddRefToGroupComponent | Adds a reference to a global resource so that a site can access that resource.
CreateComponentConfig | Creates and writes configuration information for the specified resource to the Administration database.
DeleteComponentConfig | Deletes configuration information for the specified resource.
DeleteSQLScript | Deletes the specified SQL script file from the Administration database.
ExportResource | Writes the specified resource, resource properties, and attributes to the specified file.
GetAppsInSite | Gets a list of Commerce Server 2000 applications for the specified site.
GetIfCollection | Use this method to convert values read from the Fields property, if appropriate, into either a SimpleList object or a Variant Array.
GetResourcePropAttrib | Gets a dictionary of key/value pairs that denote the attributes of the specified property of the specified resource.
GetSQLScript | Gets the specified SQL script file from the Administration database.
ImportResource | Reads the specified resource, resource properties, and attributes from the specified file, and writes them to the Commerce Server 2000 database.
Initialize | Loads the site configuration data from the Administration database.
MakeArrayFromSimpleList | Converts the specified SimpleList object into an Array.
MakeArrayFromString | Converts values read from the Fields property into an Array.
MakeSimpleListFromArray | Converts an Array into a SimpleList object.
MakeStringFromArray | Converts an Array into an encoded string that can be written to the Fields property.
MakeStringFromSimpleList | Converts a SimpleList object into an encoded string that can be written to the Fields property.
PutSQLScript | Puts the specified SQL script file into the Administration database.
SaveConfig | Saves the site configuration settings to the Administration database.

Remarks

Depending on how you add your own custom resource, you should be able to use this object to access configuration settings from the Administration database.

See Also

Configuration Objects

Integrating Cutom Resources

GlobalConfig Object

SiteConfigReadOnly Object


_SiteConfig::AddRefToGroupComponent

Use this method to add a reference to a global resource so that a site can access that resource. If you use this method to create a global resource, in order to read the correct property values, use the SiteConfigReadOnly object methods. To set the correct property values, use the GlobalConfig object on the global resource that is referenced by this site level resource.

Definition

HRESULT _SiteConfig::AddRefToGroupComponent(
BSTR bstrSiteResourceName,
BSTR bstrGroupResourceName
);

Parameters

bstrSiteResourceName

[in] A BSTR that contains the name of the resource configuration object to be added to the site.

bstrGroupResourceName

[in] A BSTR that contains the name of the global resource configuration object to which a reference is being added.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The Initialize method must be called before this method can be used.

If you use this method to create a global resource, use the SiteConfigReadOnly object methods to read the correct property values. Use the GlobalConfig object on the global resource that is referenced by this site level resource to set the correct property values.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

SiteConfig Object


_SiteConfig::CreateComponentConfig

Use this method to create an instance of a configuration schema class, and load it into the site recordset.

Definition

HRESULT _SiteConfig::CreateComponentConfig(
BSTR bstrConfigComponentName,
BSTR bstrConfigSchemaClass
);

Parameters

bstrConfigComponentName

[in] A BSTR that contains the new name for the resource configuration object instance.

bstrConfigSchemaClass

[in] A BSTR that contains the resource configuration schema class name.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The Initialize method must be called before this method can be used.

This method creates an instance of the class specified in the bstrConfigSchemaClass parameter, and sets the Name property of the instance to the name specified in the bstrConfigComponentName parameter. It loads the instance into the site recordset.

This method calls the SaveConfig method.

The following table contains a list of schema classes for this method.

Admininstration Database Class Name | Resource Name
MSCS_Catalog | Product Catalog
MSCS_AppConfigDefault | App Default Config
MSCS_TransactionConfig | Transaction Config
MSCS_Transactions | Transactions
MSCS_Content | (No longer used)
MSCS_Campaigns | Campaigns
MSCS_AuthManager | Site CS Authentication
MSCS_DirectMailer | Direct Mailer
MSCS_Predictor | Predictor
MSCS_Predictor_Site | (No longer used)
MSCS_Datawarehouse_Group | Global Data Warehouse
MSCS_Datawarehouse_Site | Site Data Warehouse
MSCS_BizDataStore | Profiles Resource
MSCS_Address | IIS Applications (such as Retail, RetailBizDesk)
MSCS_UPMDtsTask | Profiling System DTS Task Information

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

SiteConfig Object

_SiteConfig::DeleteComponentConfig


_SiteConfig::DeleteComponentConfig

Use this method to delete the Administration database information for the specified resource.

HRESULT _SiteConfig::DeleteComponentConfig(
BSTR bstrConfigComponentName
);

Parameters

bstrConfigComponentName

[in] A BSTR that contains the name of the resource associated with the Administration database information to delete.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The Initialize method must be called before this method can be used.

This delete does not remove any resource-specific data other than the configuration information. For instance, deleting the Product Catalog resource will not remove the Product Catalog tables from the database, just the configuration information.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

SiteConfig Object

_SiteConfig::CreateComponentConfig


_SiteConfig::DeleteSQLScript

Use this method to delete the specified SQL script file from the Administration database.

Definition

HRESULT _SiteConfig::DeleteSQLScript(
BSTR sResource,
BSTR sScriptName
);

Parameters

sResource

[in] A BSTR that contains the name of the resource that is associated with the SQL script file that is to be deleted.

sScriptName

[in] A BSTR that contains the name of the SQL script file to delete.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The Initialize method must be called before this method can be used.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

SiteConfig Object


_SiteConfig::ExportResource

Use this method to write the specified resource, resource properties, and attributes to the specified file.

Definition

HRESULT _SiteConfig::ExportResource(
BSTR bstrResourceName,
BSTR bstrFileName
);

Parameters

bstrResourceName

[in] A BSTR that contains the resource name.

bstrFileName

[in] A BSTR that contains the destination file name for the resource export.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The Initialize method must be called before this method can be used.

This method and the ImportResource method are complements of each other. This method creates the file that ImportResource consumes.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

SiteConfig Object


_SiteConfig::get_Fields

The Fields property is a read/write Fields object. The Fields object contents include recordsets that hold the configuration settings of resources. A Fields object is an ADO disconnected recordset.

Definition

HRESULT _SiteConfig::get_Fields(
Fields** Fields
);

Parameters

Fields

[out] The address into which this method writes the pointer to the Fields object used to return resource configuration information.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This property returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The Fields parameter contains valid data only if the method completes successfully.

You update the data in the Fields object to change your configuration information. You then call SaveConfig to commit those changes back to the database.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

SiteConfig Object


_SiteConfig::GetAppsInSite

Use this method to get a list of Commerce Server 2000 applications for the specified site.

Definition

HRESULT _SiteConfig::GetAppsInSite(
BSTR* strSiteName,
VARIANT* vtAppNames
);

Parameters

strSiteName

[in] A pointer to the BSTR that contains the name of the site for which you want the list of Commerce Server 2000 applications that are currently running.

vtAppNames

[out, retval] A pointer to a Variant used to return the list of Commerce Server 2000 applications.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The Initialize method must be called before this method can be used.

The vtAppNames parameter points to valid data only if the method completes successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

SiteConfig Object


_SiteConfig::GetIfCollection

Use this method to convert values read from the Fields property into the appropriate object such as a SimpleList object or Variant Array.

Definition

HRESULT _SiteConfig::GetIfCollection(
VARIANT* strList,
VARIANT* retVal
);

Parameters

strList

[in] A pointer to the VARIANT that contains the encoded string to be converted.

retVal

[out, retval] A pointer to a VARIANT used to return the converted data in the appropriate data type.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The retVal parameter points to valid data only if the method completes successfully.

If the encoding in the string contained in the Fields property indicates a SimpleList object, then a SimpleList object is returned. If the encoding indicates a Variant Array, then a Variant Array is returned. If no collection object is indicated, then the method returns the original encoded input string.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

SiteConfig Object


_SiteConfig::GetResourcePropAttrib

Use this method to get a Dictionary object of key/value pairs that denote the attributes of the specified property of the specified resource.

Definition

HRESULT _SiteConfig::GetResourcePropAttrib(
BSTR strResourceName,
BSTR strPropName,
IDictionary** idictResPropAttrib
);

Parameters

strResourceName

[in] A BSTR that contains the resource name.

strPropName

[in] A BSTR that contains the resource property name.

idictResPropAttrib

[out, retval] The address of a pointer to receive an IDictionary interface, used to return the key/value pairs that denote the attributes of the specified property of the specified resource.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The Initialize method must be called before this method can be used.

The idictResPropAttrib parameter contains valid data only if the method completes successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

SiteConfig Object


_SiteConfig::GetSQLScript

Use this method to get the specified SQL script file from the Administration database.

Definition

HRESULT _SiteConfig::GetSQLScript(
BSTR sResource,
BSTR sScriptName,
BSTR* strScriptContents
);

Parameters

sResource

[in] A BSTR that contains the resource associated with the required SQL script file.

sScriptName

[in] A BSTR that contains the file name of the required SQL script file.

strScriptContents

[out, retval] A pointer to a BSTR used to return the SQL script file contents.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The Initialize method must be called before this method can be used.

The strScriptContents parameter points to valid data only if the method completes successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

SiteConfig Object


_SiteConfig::ImportResource

Use this method to read the specified resource, resource properties, and attributes from the specified file, and write them to the Commerce Server 2000 database.

Definition

HRESULT _SiteConfig::ImportResource(
BSTR bstrFileName
);

Parameters

bstrFileName

[in] A BSTR that contains the file name.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The Initialize method must be called before this method can be used.

This method is the complement of the ExportResource method. It consumes the file that ExportResource creates.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

SiteConfig Object


_SiteConfig::Initialize

Use this method to load the site configuration from the Administration database.

Definition

HRESULT _SiteConfig::Initialize(
BSTR bstrSiteName
);

Parameters

bstrSiteName

[in] A BSTR that contains the site name.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

SiteConfig Object


_SiteConfig::MakeArrayFromSimpleList

Use this method to convert the specified SimpleList object into an Array.

Definition

HRESULT _SiteConfig::MakeArrayFromSimpleList(
IDispatch** list,
VARIANT* vtArray
);

Parameters

list

[in] An IDispatch interface pointer to the SimpleList object that you want to convert into an Array.

vtArray

[out, retval] A pointer to a VARIANT used to return the converted Array.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The vtArray parameter points to valid data only if the method completes successfully.

Important

  • A special group of methods is used with multivalued arrays. These methods are the only approved and recommended way of storing and retrieving multivalued arrays in the Administration database. You must use the following methods with any property that has the structure of a multivalued array:
    • MakeArrayFromSimpleList

    • MakeSimpleListFromArray

    • MakeArrayFromString

    • MakeStringFromArray

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

SiteConfig Object


_SiteConfig::MakeArrayFromString

Use this method to convert an encoded string read from the Fields property into an Array. If the encoded string does not indicate Array properties, then the method returns the original string that was passed into it.

Definition

HRESULT _SiteConfig::MakeArrayFromString(
VARIANT strList,
VARIANT* vtArray
);

Parameters

strList

[in] A VARIANT that contains the encoded string.

vtArray

[out, retval] A pointer to a VARIANT used to return the converted Array or unconverted String.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The vtArray parameter points to valid data only if the method completes successfully.

Important

  • A special group of methods is used with multivalued arrays. These methods are the only approved and recommended way of storing and retrieving multivalued arrays in the Administration database. You must use the following methods with any property that has the structure of a multivalued array:
    • MakeArrayFromSimpleList

    • MakeSimpleListFromArray

    • MakeArrayFromString

    • MakeStringFromArray

Note

  • This method can only be used on values exposed by the Fields object. The client-side disconnected ADO recordset has no support for Variants, Arrays, or objects as Fields columns. Therefore, the SiteConfig object resorts to storing data in an encoded string format.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

SiteConfig Object


_SiteConfig::MakeSimpleListFromArray

Use this method to convert an Array into a SimpleList object.

Definition

HRESULT _SiteConfig::MakeSimpleListFromArray(
VARIANT* varArray,
IDispatch** iSimpleList
);

Parameters

varArray

[in] A pointer to the VARIANT that contains the Array to convert.

iSimpleList

[out, retval] The address of an IDispatch interface pointer used to return the converted SimpleList object.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The iSimpleList parameter contains valid data only if the method completes successfully.

Important

  • A special group of methods is used with multivalued arrays. These methods are the only approved and recommended way of storing and retrieving multivalued arrays in the Administration database. You must use the following methods with any property that has the structure of a multivalued array:
    • MakeArrayFromSimpleList

    • MakeSimpleListFromArray

    • MakeArrayFromString

    • MakeStringFromArray

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

SiteConfig Object


_SiteConfig::MakeStringFromArray

Use this method to convert an Array object into an encoded string that can be written to the Fields property.

Definition

HRESULT _SiteConfig::MakeStringFromArray(
VARIANT* varArray,
VARIANT* vtEncodedString
);

Parameters

varArray

[in] A pointer to the VARIANT that contains the Array to encode.

vtEncodedString

[out, retval] A pointer to a VARIANT used to return the encoded string.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The vtEncodedString parameter points to valid data only if the method completes successfully.

Important

  • A special group of methods is used with multivalued arrays. These methods are the only approved and recommended way of storing and retrieving multivalued arrays in the Administration database. You must use the following methods with any property that has the structure of a multivalued array:
    • MakeArrayFromSimpleList

    • MakeSimpleListFromArray

    • MakeArrayFromString

    • MakeStringFromArray

Note

  • This method can only be used when updating values exposed by the Fields object. The client-side disconnected ADO recordset has no support for Variants, Arrays, or objects as Fields columns. Therefore, the SiteConfig object resorts to storing data in an encoded string format.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

SiteConfig Object


_SiteConfig::MakeStringFromSimpleList

Use this method to convert a SimpleList object into an encoded string that can be written to the Fields property.

Definition

HRESULT _SiteConfig::MakeStringFromSimpleList(
IDispatch** slist,
BSTR* strEncodedString
);

Parameters

slist

[in] An IDispatch interface pointer to the SimpleList object that you wish to convert into an encoded string.

strEncodedString

[out, retval] A pointer to a BSTR used to return the encoded string.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The strEncodedString parameter points to valid data only if the method completes successfully.

Important

  • A special group of methods is used with multivalued arrays. These methods are the only approved and recommended way of storing and retrieving multivalued arrays in the Administration database. You must use the following methods with any property that has the structure of a multivalued array:
    • MakeArrayFromSimpleList

    • MakeSimpleListFromArray

    • MakeArrayFromString

    • MakeStringFromArray

Note

  • This method can only be used when updating values exposed by the Fields object. The client-side disconnected ADO recordset has no support for Variants, Arrays, SimpleLists or objects as Fields columns. Therefore, the SiteConfig object resorts to storing data in an encoded string format.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

SiteConfig Object


_SiteConfig::PutSQLScript

Use this method to put the specified SQL script file into the Administration database.

Definition

HRESULT _SiteConfig::PutSQLScript(
BSTR sResource,
BSTR sScriptName,
BSTR sScriptContents
);

Parameters

sResource

[in] A BSTR that contains the name of the resource associated with the SQL script file.

sScriptName

[in] A BSTR that contains the name of the SQL script file.

sScriptContents

[in] A BSTR that contains the SQL script file contents.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The Initialize method must be called before this method can be used.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

SiteConfig Object


_SiteConfig::SaveConfig

Use this method to save any site configuration settings that have been changed or updated.

Definition

HRESULT _SiteConfig::SaveConfig(
);

Parameters

None.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The Initialize method must be called before this method can be used.

This method saves the entire configuration for a site. If two users are trying to update different parts of the site configuration at the same time, the last one to save will overwrite the changes made by the first user updating the site configuration.

See Also

SiteConfig Object


SiteConfigReadOnly Object

Use this object to load site configuration information from the Administration database.

ProgID: | Commerce.SiteConfigReadOnly (Externally creatable)
COM Class Name: | SiteConfigReadOnly
COM Interface Name: | _SiteConfigReadOnly
Interface ID Constant: | None
Header File: | None
Type Library Name: | Microsoft Commerce 2000 Configuration Type Library
DLL Name: | MSCSCfg.dll
Threading Model: | Apartment

In C++, use the _SiteConfigReadOnly interface to access the properties and methods of the SiteConfigReadOnly object.

The single property of the SiteConfigReadOnly object is shown in the following table.

Property | Type | Description
Fields | Fields | Returns configuration settings of the site and the site resources. This property is read-only.

The methods of the SiteConfigReadOnly object are shown in the following table.

Method | Description
GetAppsInSite | Gets a list of Commerce Server 2000 applications for the specified site.
GetIfCollection | Use this method to convert values read from the Fields property, if appropriate, into either a SimpleList object or a Variant Array.
Initialize | Loads the site configuration data from the Administration database.
MakeArrayFromSimpleList | Converts the specified SimpleList object into an Array.
MakeArrayFromString | Converts values read from Fields property into an Array.
MakeSimpleListFromArray | Converts an Array into a SimpleList object.
MakeStringFromArray | Converts an Array into an encoded string, which can be written to the Fields property.
MakeStringFromSimpleList | Converts a SimpleList object into an encoded string, which can be written to the Fields property.

Remarks

The SiteConfigReadOnly object allows access to more configuration data than does the SiteConfig object. With the SiteConfigReadOnly object, group resource values are returned when you access references to resources. In contrast, with the SiteConfig object, only references to the names of the resources are returned.

Depending on how you add your own custom resource, you should be able to use this object to access configuration settings from the Administration database.

See Also

Configuration Objects

Integrating Cutom Resources

GlobalConfig Object

SiteConfig Object


_SiteConfigReadOnly::get_Fields

The Fields property is a read-only Fields object. The Fields object contents hold the configuration settings of the site and its resources.

Definition

HRESULT _SiteConfigReadOnly::get_Fields(
Fields** Fields
);

Parameters

Fields

[out] The address into which this method will write a pointer to the Fields object used to return site and resource configuration information.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This property returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The Initialize method must be called before this method can be used.

The Fields parameter contains valid data only if the property is accessed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

SiteConfigReadOnly Object

_SiteConfigReadOnly::Initialize


_SiteConfigReadOnly::GetAppsInSite

Use this method to get a list of Commerce Server 2000 applications for the specified site.

Definition

HRESULT _SiteConfig::GetAppsInSite(
BSTR* strSiteName,
VARIANT* vtAppNames
);

Parameters

strSiteName

[in] A pointer to the BSTR that contains the name of the site for which you want the list of Commerce Server 2000 applications that are currently running.

vtAppNames

[out, retval] A pointer to a VARIANT used to return the list of Commerce Server 2000 applications.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The Initialize method must be called before this method can be used.

The vtAppNames parameter points to valid data only if the method completes successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

SiteConfigReadOnly Object


_SiteConfigReadOnly::GetIfCollection

Use this method to convert values read from the Fields property into the appropriate object such as a SimpleList object or Variant Array.

Definition

HRESULT _SiteConfig::GetIfCollection(
VARIANT* strList,
VARIANT* retVal
);

Parameters

strList

[in] A pointer to the VARIANT that contains the encoded string to be converted.

retVal

[out, retval] A pointer to a VARIANT used to return the converted data in the appropriate data type.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The retVal parameter points to valid data only if the method completes successfully.

If the encoding in the string contained in the Fields property indicates a SimpleList object, then a SimpleList object is returned. If the encoding indicates a Variant Array, then a Variant Array is returned. If no collection object is indicated, then the method returns the original encoded input string.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

SiteConfigReadOnly Object


_SiteConfigReadOnly::Initialize

Use this method to load the site configuration from the Administration database.

Definition

HRESULT _SiteConfigReadOnly::Initialize(
BSTR bstrSiteName
);

Parameters

bstrSiteName

[in] A BSTR that contains the site name.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The Initialize method must be called before the object can be used.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

SiteConfigReadOnly Object


_SiteConfigReadOnly::MakeArrayFromSimpleList

Use this method to convert the specified SimpleList object into an Array.

Definition

HRESULT _SiteConfig::MakeArrayFromSimpleList(
IDispatch** list,
VARIANT* vtArray
);

Parameters

list

[in] A IDispatch interface pointer to the SimpleList object that you want to convert into an Array.

vtArray

[out, retval] A pointer to a VARIANT used to return the converted Array.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The vtArray parameter points to valid data only if the method completes successfully.

Important

  • There is a special group of methods used with multivalued arrays. These methods are the only approved and recommended way of storing and retrieving multivalued arrays in the Administration database. You must use the following methods with any property that has the structure of a multivalued array:
    • MakeArrayFromSimpleList

    • MakeSimpleListFromArray

    • MakeArrayFromString

    • MakeStringFromArray

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

SiteConfigReadOnly Object


_SiteConfigReadOnly::MakeArrayFromString

Use this method to convert an encoded string read from the Fields property into an Array. If the encoded string does not indicate Array properties, then the method returns the original string that was passed into it.

Definition

HRESULT _SiteConfig::MakeArrayFromString(
VARIANT strList,
VARIANT* vtArray
);

Parameters

strList

[in] A VARIANT that contains the encoded string.

vtArray

[out, retval] A pointer to a VARIANT used to return the converted Array or unconverted String.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The vtArray parameter points to valid data only if the method completes successfully.

Important

  • There is a special group of methods used with multivalued arrays. These methods are the only approved and recommended way of storing and retrieving multivalued arrays in the Administration database. You must use the following methods with any property that has the structure of a multivalued array:
    • MakeArrayFromSimpleList

    • MakeSimpleListFromArray

    • MakeArrayFromString

    • MakeStringFromArray

Note

  • This method can only be used on values exposed by the Fields object. The client-side disconnected ADO recordset has no support for Variants, Arrays, or objects as Fields columns. Therefore, the SiteConfigReadOnly object resorts to storing data in an encoded string format.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

SiteConfigReadOnly Object


_SiteConfigReadOnly::MakeSimpleListFromArray

Use this method to convert an Array into a SimpleList object.

Definition

HRESULT _SiteConfig::MakeSimpleListFromArray(
VARIANT* varArray,
IDispatch** iSimpleList
);

Parameters

varArray

[in] A pointer to the VARIANT that contains the Array to convert.

iSimpleList

[out, retval] The address of a IDispatch interface pointer used to return the converted SimpleList object.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The iSimpleList parameter contains valid data only if the method completes successfully.

Important

  • There is a special group of methods used with multivalued arrays. These methods are the only approved and recommended way of storing and retrieving multivalued arrays in the Administration database. You must use the following methods with any property that has the structure of a multivalued array:
    • MakeArrayFromSimpleList

    • MakeSimpleListFromArray

    • MakeArrayFromString

    • MakeStringFromArray

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

SiteConfigReadOnly Object


_SiteConfigReadOnly::MakeStringFromArray

Use this method to convert an Array object into an encoded string, which can be written to the Fields property.

Definition

HRESULT _SiteConfig::MakeStringFromArray(
VARIANT* varArray,
VARIANT* vtEncodedString
);

Parameters

varArray

[in] A pointer to the VARIANT that contains the Array to encode.

vtEncodedString

[out, retval] A pointer to a Variant used to return the encoded string.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The vtEncodedString parameter points to valid data only if the method completes successfully.

Important

  • There is a special group of methods used with multivalued arrays. These methods are the only approved and recommended way of storing and retrieving multivalued arrays in the Administration database. You must use the following methods with any property that has the structure of a multivalued array:
    • MakeArrayFromSimpleList

    • MakeSimpleListFromArray

    • MakeArrayFromString

    • MakeStringFromArray

Note

  • This method can only be used when updating values exposed by the Fields object. The client-side disconnected ADO recordset has no support for Variants, Arrays, or objects as Fields columns. Therefore, the SiteConfigReadOnly object resorts to storing data in an encoded string format.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

SiteConfigReadOnly Object


_SiteConfigReadOnly::MakeStringFromSimpleList

Use this method to convert a SimpleList object into an encoded string, which can be written to the Fields property.

Definition

HRESULT _SiteConfig::MakeStringFromSimpleList(
IDispatch** slist,
BSTR* strEncodedString
);

Parameters

slist

[in] An IDispatch interface pointer to the SimpleList object that you wish to convert into an encoded string.

strEncodedString

[out, retval] The address of a BSTR used to return the encoded string.

Return Values

This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

All ADO, SQL, and ODBC errors will also be returned by this method.

Remarks

The strEncodedString parameter points to valid data only if the method completes successfully.

Important

  • There is a special group of methods used with multivalued arrays. These methods are the only approved and recommended way of storing and retrieving multivalued arrays in the Administration database. You must use the following methods with any property that has the structure of a multivalued array:
    • MakeArrayFromSimpleList

    • MakeSimpleListFromArray

    • MakeArrayFromString

    • MakeStringFromArray

Note

  • This method can only be used when updating values exposed by the Fields object. The client-side disconnected ADO recordset has no support for Variants, Arrays, SimpleLists or objects as Fields columns. Therefore, the SiteConfigReadOnly object resorts to storing data in an encoded string format.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

SiteConfigReadOnly Object


StandardSManager Object

Use this object to facilitate the run time creation and retrieval of shopper IDs.

ProgID: | Commerce.StandardSManager (Externally creatable)
COM Class Name: | MSCSStandardSManager_3_0
COM Interface Name: | IMSCSStandardSManager_3_0
Interface ID Constant: | IID_IMSCSStandardSManager_3_0
Header File: | mspu_guids.h
Type Library Name: | Commerce 1.0 Type Library
DLL Name: | Commerce.dll
Threading Model: | Both

In C++, use the IMSCSStandardSManager_3_0 interface to access the properties and methods of the StandardSManager object.

Because this object is primarily intended for use within ASP script, access from C++ will not be common.

The single property of the StandardSManager object is shown in the following table.

Property | Type | Description
Mode | Integer | Determines how the GetShopperID and PutShopperID methods of the Page object retrieve and store shopper IDs.

The methods of the StandardSManager object are shown in the following table.

Method | Description
CreateShopperId | Creates a unique shopper ID for the current user.
GetShopperId | Returns the unique shopper ID for the current user.
InitManager | Initializes the StandardSManager object.
PutShopperId | Writes the specified shopper ID to a cookie and/or stores it for use in a URL or SURL, depending on the initialization mode of the StandardSManager object for the site.

Remarks

This object is only included for purposes of backward compatibility with Site Server 3.0 Commerce Edition; it has been replaced by the AuthManager object.

See Also

Backward Compatibility Objects

AuthManager Object


IMSCSStandardSManager_3_0::CreateShopperId

Use this method to create a unique shopper ID for the current user.

Definition

HRESULT IMSCSStandardSManager_3_0::CreateShopperId(
BSTR* pbstrRet
);

Parameters

pbstrRet

[out, retval] A pointer to a BSTR used to return the new shopper ID.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pbstrRet parameter points to valid data only if the method completes successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

StandardSManager Object

IMSCSStandardSManager_3_0::InitManager

IMSCSStandardSManager_3_0::GetShopperId

IMSCSStandardSManager_3_0::PutShopperId


IMSCSStandardSManager_3_0::GetShopperId

Use this method to retrieve the shopper ID for the current user. The shopper ID is returned from a URL query string or a cookie, depending on the initialization mode of the StandardSManager object for the site.

Definition

HRESULT IMSCSStandardSManager_3_0::GetShopperId(
IDispatch* pdispContext,
VARIANT* pvtRet
);

Parameters

pdispContext

[in] A pointer to the IDispatch interface that contains the ASP scripting context.

pvtRet

[out, retval] A pointer to a VARIANT used to return the shopper ID.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The pvtRet parameter points to valid data only if the method completes successfully.

If no shopper ID is found, the GetShopperID method returns an empty string.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

StandardSManager Object

IMSCSStandardSManager_3_0::get_Mode, put_Mode

IMSCSStandardSManager_3_0::PutShopperId


IMSCSStandardSManager_3_0::InitManager

Use this method to initialize the StandardSManager object to the specified site name and mode.

Definition

HRESULT IMSCSStandardSManager_3_0::InitManager(
BSTR bstrStoreKey,
BSTR bstrMode
);

Parameters

bstrStoreKey

[in] A BSTR that contains the name of the site.

bstrMode

[in] A BSTR that indicates how user information is to be stored. For more information about initialization modes, see the Remarks section.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

The bstrMode parameter can take the following values:

Mode | Behavior
Cookie | The PutShopperID method stores the shopper ID in a cookie on the client system. The GetShopperID method retrieves this cookie.
url | The PutShopperID method appends the shopper ID to the URL, using MCSSIDUrlKey as the name part of the URL variable. The GetShopperID method retrieves the shopper ID from the URL.
Cookieurl | The PutShopperID method stores the shopper ID in a cookie on the client system and in the URL. The GetShopperID method first attempts to retrieve the shopper ID from the cookie, and then from the URL.
Urlcookie | The PutShopperID method stores the shopper ID in a URL, and stores it as a cookie on the client system. The GetShopperID method first attempts to retrieve the shopper ID from the URL, then from the cookie.

This object is only included for purposes of backward compatibility with Site Server 3.0 Commerce Edition.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

StandardSManager Object

IMSCSStandardSManager_3_0::get_Mode, put_Mode

IMSCSStandardSManager_3_0::PutShopperId


IMSCSStandardSManager_3_0::get_Mode, put_Mode

The Mode property is a read/write Integer that determines how the GetShopperID and PutShopperID methods of the Page object retrieve and store shopper IDs.

Definition

Get method:

HRESULT IMSCSStandardSManager_3_0::get_Mode(
int* Mode
);

Put method:

HRESULT IMSCSStandardSManager_3_0::put_Mode(

 int Mode

);

Parameters

Mode

[in] When putting the property, an Integer that contains the mode.

[out, retval] When getting the property, an Integer used to return the mode.

Return Values

These methods return an HRESULT indicating whether they completed successfully. See the Error Values section for more details.

Error Values

These methods return S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

After creating a StandardSManager object, but before calling the GetShopperID or PutShopperID methods, you must initialize the StandardSManager object. To do this, call the InitManager method of the StandardSManager object, specifying the site name and the initialization mode.

The following table shows the values that the mode property integer can take.

Mode | Behavior
0 | Look only at cookie
1 | Look only at URL
2 | Look at cookie and then URL
3 | Look at URL and then cookie

The Mode parameter contains valid data only if the property is accessed successfully.

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

StandardSManager Object

Page Object

IMSCSStandardSManager_3_0::InitManager


IMSCSStandardSManager_3_0::PutShopperId

Use this method to store a shopper ID for the current user. After the object has been initialized, the shopper ID will be stored in a cookie or as part of the URL.

Definition

HRESULT IMSCSStandardSManager_3_0::PutShopperId(
IDispatch* pdispContext,
BSTR bstrShopperID
);

Parameters

pdispContext

[in] A pointer to the IDispatch interface used to retrieve the ASP scripting context.

bstrShopperID

[in] A BSTR that contains the shopper ID to be stored.

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

Remarks

For more information about memory ownership issues related to COM property and method parameters, see Managing COM Parameter Memory.

See Also

StandardSManager Object

IMSCSStandardSManager_3_0::get_Mode, put_Mode

IMSCSStandardSManager_3_0::GetShopperId


Interface Reference

Microsoft Commerce Server 2000 can be extended programmatically by building Component Object Model (COM) objects that support specific interfaces. This allows them to be called in a standard fashion. Such objects fall into the following two categories:

  1. Pipeline Components

    Pipeline components implement one or more specific interfaces, allowing them to be executed in the context of Commerce Server pipelines, and to be configured and included in pipeline configurations through the Pipeline Editor. For more information about pipelines and their various uses within Commerce Server, see Working with Pipelines.

  2. Site Packager Components

    Site packager components implement the IPuP interface, allowing them to be invoked by Commerce Server Site Packager so that they can package and unpack custom data. Typically, this is configuration information for custom resources that store their data somewhere other than the Administration database (MSCS_Admin).

    For general information about the integration of custom resources, see Integrating Custom Resources.

    For more specific information about packaging and unpacking data stored somewhere other than the Administration database, see Packaging Other Data.

The generic persistence interfaces are a third category of standard COM interfaces that can be implemented by Commerce Server COM objects. Pipeline components often implement one or more of these interfaces. Some of these persistence interfaces are implemented by other COM objects supplied with Commerce Server. For example, the Dictionary object implements the IPersistXML interface, allowing the contents of a Dictionary object to be persisted as an XML-formatted string in a specific format, and conversely, to be initialized based on the contents of an XML-formatted string in a particular format.

This section provides the details of these interfaces so that they can be implemented by new COM objects of the relevant types.

This section contains:

  • Pipeline Component Interfaces. Describes the pipeline component interfaces through which a COM component can serve as a Commerce Server pipeline component.

  • Site Packager Interface. Describes the site packager interface through which a COM object can be told to package or unpack custom data.

  • Generic Persistence Interfaces. Describes the generic persistence interfaces through which a COM object can be told to save its data as an XML-formatted string, a Dictionary object, or to a stream.


Pipeline Component Interfaces

Microsoft Commerce Server 2000 defines a set of Component Object Model (COM) interfaces known as pipeline interfaces. In addition, pipeline components often implement one or more generic persistence interfaces defined by Commerce Server, as well as the standard OLE interfaces ISpecifyPropertyPages and IPersistStreamInit.

Every pipeline component must support the IPipelineComponent interface. Without this interface, a Commerce Server pipeline will not be able to execute the component. The remaining interfaces are optional. They expose various types of functionality that allow new components to fit smoothly into the Commerce Server architecture.

The following table lists the required IPipelineComponent interface and the other optional interfaces.

Interface | Description
IPipelineComponent | Executes the component. This interface is required.
IPipelineComponentAdmin | Sets and retrieves the properties on a component using a Dictionary object. This interface is optional.
IPipelineComponentDescription | Uses a SAFEARRAY to identify the OrderForm object and PipeContext object elements that a component reads and writes. This interface is optional.
IPipelineComponentUI | Displays a dialog box for configuring a pipeline component. This interface is optional.
ISpecifyPipelineComponentUI | Determines the object that will be invoked through the IPipelineComponentUI interface to display the dialog box for the component. This interface is optional.
ISpecifyPropertyPages | Indicates that the object supports property pages. This is a standard OLE interface. This interface is optional.
IPersistStreamInit | Persists the data associated with an object to a stream. This is the form of persistence used in the Active Template Library (ATL) Pipeline Wizard. This is a standard OLE interface. This interface is optional.
IPersistDictionary | Persists the data associated with an object to a Dictionary object. This is a generic persistence interface defined by Commerce Server. This interface is optional.


IPipelineComponent Interface

All pipeline components must implement the IPipelineComponent interface, passing an OrderForm object interface pointer between each component. If a component returns an error, the pipeline may terminate execution and return an error to the caller.

The IPipelineComponent interface supports the following methods:

Method | Description
Execute | The entry point at which the pipeline begins executing the component.
EnableDesign | Sets the design mode on the component.

Remarks

For more information about IPipelineComponent interface code generated by the Active Template Library (ATL) Pipeline Component Wizard, see Implementing the IPipelineComponent Interface.

Header: pipecomp.h

Type Library: Microsoft Commerce 2000 Order Pipeline Type Library (pipeline.dll)

IDL File: Pipecomp.idl


IPipelineComponent::Execute

Use this method to execute a pipeline component.

Definition

HRESULT Execute(
..IDispatch* pDispOrder,
..IDispatch* pDispContext,
..long lFlags,
..long* plErrorLevel
);

Parameters

pDispOrder

[in] A pointer to the OrderForm object.

pDispContext

[in] A pointer to the Context object. This is a Dictionary object that contains pointers to the MessageManager object, Content object, and language information.

lFlags

[in] Reserved. This parameter should be zero (0).

plErrorLevel

[out, retval] A flag that indicates what level of errors is tolerated. See the Remarks section for information about the legal values for this parameter.

This error information is meant to supplement the HRESULT information that is returned. The pipeline maps errors returned from components (E_xxxx errors) to an error level of 2.

Remarks

The plErrorLevel parameter can be one of the following values:

Value | Meaning
0 | No errors, component executed successfully.
1 | Basket or purchase errors for this operation.
2 | Serious errors in execution of this component.

For more information about IPipelineComponent interface code generated by the Active Template Library (ATL) Pipeline Component Wizard, see Implementing the IPipelineComponent Interface.

Return Values

The method returns an HRESULT value.

See Also

IPipelineComponent Interface


IPipelineComponent::EnableDesign

Use this method to prepare the component for execution in one of two modes: design mode or execution mode. In design mode, which is useful for running the Pipeline Editor, errors are more easily tolerated. Execution mode (the default) is analogous to production mode.

Definition

HRESULT EnableDesign(
BOOL fEnable
);

Parameters

fEnable

[in] Indicates whether the component should be run in design mode (True) or execution mode (False).

Return Values

The method returns an HRESULT value.

Remarks

For more information about IPipelineComponent interface code generated by the Active Template Library (ATL) and the Pipeline Component Wizard, see Implementing the IPipelineComponent Interface.

See Also

IPipelineComponent Interface


IPipelineComponentAdmin Interface

To support third-party components in the Pipeline Editor, components must provide their own user interface code. The IPipelineComponentAdmin interface, in combination with the IPipelineComponentUI and IPipelineComponentSpecifyUI interfaces, provides an alternative to using the ISpecifyPropertyPages interface.

The IPipelineComponentAdmin interface supports the following methods:

Method | Description
GetConfigData | Returns a Dictionary object that contains the configuration settings for a component.
SetConfigData | Sets the configuration settings on a component using the contents of a Dictionary object.

Remarks

For more information, see Deciding Which Interface to Expose.

Header: pipecomp.h

Type Library: Microsoft Commerce Pipeline StdRetComp Type Library (stdretcomp.dll)

IDL File: Pipecomp.idl


IPipelineComponentAdmin::GetConfigData

This method returns an IDictionary pointer for the user interface to read the configuration data for the component.

Definition

HRESULT GetConfigData(
IDispatch** ppDict
);

Parameters

ppDict

[out] A pointer to an object from which the user interface can read the configuration data (typically using the IDictionary interface).

Return Values

The method returns an HRESULT value.

Remarks

For more information, see Deciding Which Interface to Expose.

See Also

IPipelineComponentAdmin Interface

IPipelineComponentAdmin::SetConfigData


IPipelineComponentAdmin::SetConfigData

This method takes a pointer to an object containing the configuration information for the component. This object must implement the IDictionary interface.

Definition

HRESULT SetConfigData(
IDispatch* pDict
);

Parameters

pDict

[in] An interface pointer to the object containing the configuration information.

Return Values

The method returns an HRESULT value.

Remarks

For more information, see Deciding Which Interface to Expose.

See Also

IPipelineComponentAdmin Interface

IPipelineComponentAdmin::GetConfigData


IPipelineComponentDescription Interface

The IPipelineComponentDescription interface makes it possible for pipeline components to identify the values that they read from the pipeline context, and the keys and values that they read from or write to the OrderForm object.

Although pipeline components are not required to implement the IPipelineComponentDescription interface, implementing this interface makes it possible for the Pipeline Editor to identify and display the elements that your component reads or writes. This information can help developers who are troubleshooting a pipeline configuration.

The IPipelineComponentDescription interface supports the following methods:

Method | Description
ContextValuesRead | Returns a SAFEARRAY VARIANT that identifies the pipeline context values that the component reads.
ValuesRead | Returns a SAFEARRAY VARIANT that identifies the values that the component reads.
ValuesWritten | Returns a SAFEARRAY VARIANT that identifies the values that the component writes.

The methods defined in the IPipelineComponentDescription interface all take a single parameter: the address of a VARIANT out-value. The VARIANT that the IPipelineComponentDescription methods store in this address must contain a SAFEARRAY of VARIANTs that contain a BSTR variable. These BSTR variables identify the values read from or written to the pipeline context or the OrderForm object. Because the VARIANTs in this SAFEARRAY contain simple BSTR variables, you can conceivably store any kind of string information in these BSTR variables. However, for the sake of aiding developers who are attempting to troubleshoot their pipeline configurations, it is recommended that you initialize these BSTR variables to reference only elements of the PipeContext object or the OrderForm object.

Remarks

For more information about IPipelineComponentDescription interface code generated by the Active Template Library (ATL) and the Pipeline Component Wizard, see Enhancing Component Usability.

Header: pipecomp.h

Type Library: Microsoft Commerce Pipeline StdRetComp Type Library (stdretcomp.dll)

IDL File: Pipecomp.idl


IPipelineComponentDescription::ContextValuesRead

This method returns a VARIANT that contains a SAFEARRAY of VARIANTs. Each of the VARIANTs in this SAFEARRAY contains a BSTR that identifies the PipeContext object elements that the component reads.

Definition

HRESULT ContextValuesRead(
VARIANT* pVar
);

Parameters

pVar

[out, retval] The address to which the method returns a VARIANT. This VARIANT contains a SAFEARRAY of VARIANTs, each of which contains a BSTR that identifies the elements that a component reads from the PipeContext object.

Return Values

If the function implementation does not return S_OK, the Pipeline Editor ignores the contents of the returned VARIANT variable.

Remarks

For more information about IPipelineComponentDescription interface code generated by the Active Template Library (ATL) and the Pipeline Component Wizard, see Enhancing Component Usability.

See Also

IPipelineComponentDescription Interface


IPipelineComponentDescription::ValuesRead

This method identifies the keys and values that a component reads from the OrderForm object.

Definition

HRESULT ValuesRead(
VARIANT* pVar
);

Parameters

pVar

[out, retval] The address to which the method returns a VARIANT. This VARIANT contains a SAFEARRAY of VARIANTs, each of which contains a BSTR that identifies the keys and values that a component reads from the OrderForm object.

Return Values

If the function implementation does not return S_OK, the Pipeline Editor ignores the contents of the returned VARIANT.

Remarks

For more information about IPipelineComponentDescription interface code generated by the Active Template Library (ATL) and the Pipeline Component Wizard, see the Enhancing Component Usability.

See Also

IPipelineComponentDescription Interface

IPipelineComponentDescription::ValuesWritten


IPipelineComponentDescription::ValuesWritten

This method identifies the keys and values that a component modifies in the OrderForm object.

Definition

HRESULT ValuesWritten(
VARIANT* pVar
);

Parameters

pVar

[out, retval] The address to which the method returns a VARIANT. This VARIANT contains a SAFEARRAY of VARIANTs, each of which contains a BSTR that identifies the modified keys and values.

Return Values

If the function implementation does not return S_OK, the Pipeline Editor ignores the contents of the returned VARIANT.

Remarks

For more information about IPipelineComponentDescription interface code generated by the Active Template Library (ATL) and the Pipeline Component Wizard, see Enhancing Component Usability.

See Also

IPipelineComponentDescription Interface

IPipelineComponentDescription::ValuesRead


IPipelineComponentUI Interface

The IPipelineComponentUI interface is implemented to allow a pipeline component to display a dialog box for configuration values. The interface is implemented by a separate Component Object Model (COM) object that displays the dialog box.

The IPipelineComponentUI interface supports the following method:

Method | Description
ShowProperties | Called by the Pipeline Editor to display the dialog box for the component.

Remarks

Header: pipecomp.h

Type Library: Microsoft Commerce 2000 Order Pipeline Type Library (pipeline.dll)

IDL File: Pipecomp.idl


IPipelineComponentUI::ShowProperties

This method is called to display the configuration dialog box for a pipeline component.

Definition

HRESULT ShowProperties(
IDispatch* pdispComponent
);

Parameters

pdispComponent

[in] A pointer to an IPipelineComponentAdmin interface.

Return Values

Returns S_OK if the dialog box was displayed and configuration values set.

Remarks

The object implementing this interface first gets the configuration Dictionary object using the IPipelineComponentAdmin::GetConfigData method. It then uses these values to fill in the dialog box. When the user is finished with the dialog box, the object sets the configuration values using the IPipelineComponentAdmin::SetConfigData method.

See Also

IPipelineComponentUI Interface

ISpecifyPipelineComponentUI Interface


ISpecifyPipelineComponentUI Interface

The ISpecifyPipelineComponentUI interface is used by a pipeline component to specify the Component Object Model (COM) object that implements the IPipelineComponentUI interface that gets and sets configuration values.

The ISpecifyPipelineComponentUI interface supports the following method:

Method | Description
GetPipelineComponentUIProgID | Used by the pipeline component to specify the component that displays the configuration dialog box by implementing the IPipelineComponentUI interface.

Remarks

Header: pipecomp.h

Type Library: Microsoft Commerce 2000 Order Pipeline Type Library (pipeline.dll)

IDL File: Pipecomp.idl


ISpecifyPipelineComponentUI::GetPipelineComponentUIProgID

This method is used by the pipeline component to specify the component that displays the configuration dialog box by implementing the IPipelineComponentUI interface.

Definition

HRESULT GetPipelineComponentUIProgID(
BSTR* pbstrProgID
);

Parameters

pbstrProgID

[out, retval] A pointer to a BSTR string used to return the programmatic identifier (ProgID) of the component that displays the configuration dialog box of the component.

Return Values

Returns S_OK if the ProgID was retrieved.

See Also

ISpecifyPipelineComponentUI Interface

IPipelineComponentUI Interface


ISpecifyPropertyPages Interface

The ISpecifyPropertyPages interface is a standard Win32 OLE interface. You implement this interface to allow the pipeline administration tool to invoke the property page user interface of the component. For more information about the ISpecifyPropertyPages interface, see the OLE Programmer's Reference.

The ISpecifyPropertyPages interface supports the following method:

Method | Description
GetPages | Fills in an array of class identifiers (CLSID) where each CLSID is the CLSID of a property page that can be displayed in the property sheet for this object.

Remarks

For more information about ISpecifyPropertyPages interface code generated by the Active Template Library (ATL) and the Pipeline Component Wizard, see ATL MinMaxShip Component Sample.

Header: ocidl.h

IDL File: ocidl.idl


ISpecifyPropertyPages::GetPages

This method fills a counted array of universally unique identifier (UUID) values where each UUID specifies the class identifier (CLSID) of a particular property page that can be displayed in the property sheet for this object.

The CAUUID structure is caller-allocated, but is not initialized by the caller. The ISpecifyPropertyPages::GetPages method fills the cElements field in the CAUUID structure. This method also allocates memory for the array pointed to by the pElems field in the CAUUID structure using the CoTaskMemAlloc method. Then, it fills the newly allocated array. After this method returns successfully, the structure contains a counted array of UUIDs, each UUID specifying a property page CLSID.

Definition

HRESULT GetPages(
CAUUID* pPages
);

Parameters

pPages

[out] A pointer to a caller-allocated CAUUID structure that must be initialized and filled before returning. The pElems field in the CAUUID structure is allocated by the callee with the CoTaskMemAlloc method and freed by the caller with the CoTaskMemFree method.

Return Values

The method returns an HRESULT value.

Remarks

The CAUUID structure is defined as follows:

typedef struct tagCAUUID
{
    ULONG       cElems;
    GUID FAR *  pElems;
} CAUUID;

cElems

The size of the array pointed to by the pElems array.

pElems

A pointer to an array of UUID values, each of which specifies a CLSID of a particular property page. This array is allocated by the callee using the CoTaskMemAlloc method and is freed by the caller using the CoTaskMemFree method.

For more information about ISpecifyPropertyPages interface code generated by the Active Template Library (ATL) and the Pipeline Component Wizard, see MinMaxShip Sample Pipeline Component.

See Also

ISpecifyPropertyPages Interface


Site Packager Interface

Custom resources can be packaged into a file. A package is a specially formatted Commerce Server file. Each package is identified with a .pup extension. A package always contains a single site, which includes resource configuration data and the applications of a Commerce site. It can also include whatever files each resource chooses to package, though no special processing (such as DLL registration) will be performed during unpacking.

Custom resources do not necessarily need to do anything to be included in the packaging process. If the custom resource stores its data in the Commerce Server Administration database, that data will automatically be packaged. For more information about this low development effort approach, see Levels of Intregration.

If your custom resource stores its configuration data outside of the Administration database, or if you want other files to be included in the package, you must generally develop a custom Component Object Model (COM) component that participates in the packaging and unpacking process. For example, if your resource depends on data being placed in the Site Configuration Store, the custom COM component you develop will perform that function.

In limited circumstances, the GenericPuP object can be used instead of a newly developed COM component. For more information about using this object, see Using the GenericPuP Object.

If you must develop a custom COM component to participate in the packaging process, it must implement the IPuP interface.

The ProgIDs of custom COM components that implement the IPuP interface must be placed in the appropriate tables within the Administration database in order to be invoked.

The methods of the IPuP interface to be implemented by your custom COM component are shown in the following table.

Method | Description
CreateGroupResource | Called to create the connection between a global resource and the site-level reference to that resource. Called in conjunction with the Import method if the resource is a global resource.
Delete | Called by the Commerce Server Manager to delete custom site resource data from a computer. It also removes the configuration data for this resource from the Administration database. This method should perform whatever is required to properly delete data associated with the corresponding site resource.
DeleteGroupResource | Called to delete custom global resource data from a computer. It also removes the configuration data for this resource from the Administration database. This method should perform whatever is required to properly delete data associated with the corresponding global resource.
Export | Called to allow the custom COM component to place the files to be packaged into a specified location.
Import | Called to allow the custom COM component to retrieve the files that were packaged from a specified location.


IPuP::CreateGroupResource

If your custom resource is a global resource, you must implement this method. Since the packaged site is, by definition, using your global resource, the site must be provided with a site-level object that refers to your global resource. This method must perform the necessary processing.

When the f_ResourceFlags column indicates a global resource (the corresponding bit mask constant is IS_REFTOGROUPRES), this method is called before the Import method is called. This method is not called for site resources.

Site Packager will call this method, indicating the site name and the name of the custom resource, as it is known at the site level. Your implementation must create the global resource, and then return its name. Site Packager can then create the link between the site-level representation of the global resource, and the actual global resource. Then Site Packager will call the Import method to import any data associated with the custom global resource.

Definition

HRESULT CreateGroupResource(
BSTR szSiteName,
BSTR szResourceName,
BSTR szConnStr,
BSTR szPath,
BOOL bSilent,
BSTR* szGroupResourceName
);

Parameters

szSiteName

[in] A BSTR that contains the name of the site being unpacked.

szResourceName

[in] A BSTR that contains the name of the custom resource.

szConnStr

[in] A BSTR that contains the connection string.

szPath

[in] A BSTR that contains the path and name of a file for error logging.

bSilent

[in] A BOOLEAN value used to indicate whether any user interaction is allowed. A value of TRUE suppresses user interaction, allowing for unattended operation.

szGroupResourceName

[out, retval] A pointer to a BSTR to be used to return the name of the corresponding global resource.

Return Values

This method must return an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method must return S_OK (0x00000000) to indicate success and a COM HRESULT error value to indicate failure. For more information about the standard COM error values that can be used, see Standard COM Errors. Additional information may be made available using the global Err object, which can be accessed by the caller using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface can be called to retrieve a text description of the error, which you can supply.

Remarks

If this method is designed to allow user interaction, the user interface used to accomplish this interaction must be capable of being suppressed. The bSilent parameter is used to indicate whether such suppression should occur. If the bSilent parameter is set to TRUE the user interface must be suppressed. If the bSilent parameter is set to FALSE, it is permissible to display the user interface and seek user interaction. This aspect of the method invocation allows for unattended operation.

The connection string includes the Data Source Name (DSN), the database login ID, and the database password for the database used by this resource. Any custom database tables must be created by the implementation of this method. Since the resource may be sharing the database with other resources, unique table names should be chosen.

See Also

Site Packager Interface

IPuP::Import


IPuP::Delete

If your custom resource is a site resource, and you want to perform custom clean up of resource data, you must implement this method.

Commerce Server Manager calls this method when it is removing a site resource from a computer. This provides an opportunity for clean up that is specific to this custom resource to be performed. After this method returns, Commerce Server Manager will continue by removing references to the custom resource, and any corresponding configuration data, from the Administration database.

Definition

HRESULT Delete(
BSTR szSiteName,
BSTR szResourceName,
BOOL bKeepData,
BOOL bSilent
);

Parameters

szSiteName

[in] A BSTR that contains the name of the site.

szResourceName

[in] A BSTR that contains the name of the custom resource.

bKeepData

[in] A BOOLEAN value used to indicate whether site resource data should be deleted or not. A value of TRUE indicates that the data should be retained, and a value of FALSE indicates that the data should be deleted.

bSilent

[in] A BOOLEAN value used to indicate whether any user interaction is allowed. A value of TRUE suppresses user interaction, allowing for unattended operation.

Return Values

This method must return an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method must return S_OK (0x00000000) to indicate success and a COM HRESULT error value to indicate failure. For more information about the standard COM error values that can be used, see Standard COM Errors. Additional information may be made available using the global Err object, which can be accessed by the caller using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface can be called to retrieve a text description of the error, which you can supply.

Remarks

If this method is designed to allow user interaction, the user interface used to accomplish this interaction must be capable of being suppressed. The bSilent parameter is used to indicate whether such suppression should occur. If the bSilent parameter is set to TRUE the user interface must be suppressed. If the bSilent parameter is set to FALSE, it is permissible to display the user interface and seek user interaction. This aspect of the method invocation allows for unattended operation.

The system administrator should be able to indicate whether resource data should be retained or deleted through the user interface. The bKeepData parameter is set to TRUE or FALSE, in accordance with user input.

This method could be called from a custom script to clean up the data associated with a custom site resource.

See Also

Site Packager Interface

IPuP::DeleteGroupResource


IPuP::DeleteGroupResource

If your custom resource is a global resource, and you want to perform custom clean up of resource data, you must implement this method.

Commerce Server Manager calls this method when it is removing a global resource from a computer. This provides an opportunity for clean up that is specific to this custom resource to be performed. After this method returns, Commerce Server Manager will continue by removing references to the custom resource, and any corresponding configuration data, from the Administration database.

Definition

HRESULT DeleteGroupResource(
BSTR szSiteName,
BSTR szResourceName,
BOOL bKeepData,
BOOL bSilent
);

Parameters

szSiteName

[in] A BSTR that contains the name of the site.

szResourceName

[in] A BSTR that contains the name of the custom resource.

bKeepData

[in] A BOOLEAN value used to indicate whether site resource data should be deleted or not. A value of TRUE indicates that the data should be retained, and a value of FALSE indicates that the data should be deleted.

bSilent

[in] A BOOLEAN value used to indicate whether any user interaction is allowed. A value of TRUE suppresses user interaction, allowing for unattended operation.

Return Values

This method must return an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method must return S_OK (0x00000000) to indicate success and a COM HRESULT error value to indicate failure. For more information about the standard COM error values that can be used, see Standard COM Errors. Additional information may be made available using the global Err object, which can be accessed by the caller using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface can be called to retrieve a text description of the error, which you can supply.

Remarks

If this method is designed to allow user interaction, the user interface used to accomplish this interaction must be capable of being suppressed. The bSilent parameter is used to indicate whether such suppression should occur. If the bSilent parameter is set to TRUE the user interface must be suppressed. If the bSilent parameter is set to FALSE, it is permissible to display the user interface and seek user interaction. This aspect of the method invocation allows for unattended operation.

The system administrator should be able to indicate whether resource data should be retained or deleted through the user interface. The bKeepData parameter is set to TRUE or FALSE, in accordance with user input.

This method could be called from a custom script to clean up the data associated with a custom global resource.

See Also

Site Packager Interface

IPuP::Delete


IPuP::Export

This method is call when Site Packager creates a Commerce Server Site Package. In order for your custom resource to place one or more files of its choice into this package, you must implement this method.

Definition

HRESULT Export(
BSTR szSiteName,
BSTR szResourceName,
BSTR szPath,
BOOL bExportData,
BOOL bSilent
);

Parameters

szSiteName

[in] A BSTR that contains the name of the site.

szResourceName

[in] A BSTR that contains the name of the custom resource.

szPath

[in] A BSTR that contains the path where the custom resource is expected to place one or more files of its choice. For more information, see the Remarks section.

bExportData

[in] A BOOLEAN flag used to turn data export on or off.

bSilent

[in] A BOOLEAN value used to indicate whether any user interaction is allowed. A value of TRUE suppresses user interaction, allowing for unattended operation.

Return Values

This method must return an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method must return S_OK (0x00000000) to indicate success and a COM HRESULT error value to indicate failure. For more information about the standard COM error values that can be used, see Standard COM Errors. Additional information may be made available using the global Err object, which can be accessed by the caller using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface can be called to retrieve a text description of the error, which you can supply.

Remarks

Site Packager calls this method, specifying either a file name or a folder name, based on the value of f_PupFlags column in the Resource table of the Administration database. This bit field column currently has only one bit defined for use: bit 1. If bit 1 is set to zero (0), the szPath parameter specifies a temporary file name, and if bit 1 is set to one (1), the szPath parameter specifies a temporary folder name.

If a file name is specified, this method is expected to place the data to be packaged into a single file, named as specified by the szPath parameter. After this method returns, Site Packager will add that file to the package and then delete it.

If a folder name is specified, this method is expected to place the data to be packaged into one or more files, located within the folder specified by the szPath parameter. After this method returns, Site Packager will add those files to the package and then delete them.

If this method is designed to allow user interaction, the user interface used to accomplish this interaction must be capable of being suppressed. The bSilent parameter is used to indicate whether such suppression should occur. If the bSilent parameter is set to TRUE the user interface must be suppressed. If the bSilent parameter is set to FALSE, it is permissible to display the user interface and seek user interaction. This aspect of the method invocation allows for unattended operation.

See Also

Site Packager Interface

IPuP::Import


IPuP::Import

This method is call when Site Packager unpacks a Commerce Server Site Package. In order for your custom resource to make use of one or more files from this package, you must implement this method.

Definition

HRESULT Import(
BSTR szSiteName,
BSTR szResourceName,
BSTR szPath,
BOOL bSilent
);

Parameters

szSiteName

[in] A BSTR that contains the name of the site.

szResourceName

[in] A BSTR that contains the name of the custom resource.

szPath

[in] A BSTR that contains the path where the Site Packager has deposited one or more files packaged for this resource. For more information, see the Remarks section.

bSilent

[in] A BOOLEAN value used to indicate whether any user interaction is allowed. A value of TRUE suppresses user interaction, allowing for unattended operation.

Return Values

This method must return an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.

Error Values

This method must return S_OK (0x00000000) to indicate success and a COM HRESULT error value to indicate failure. For more information about the standard COM error values that can be used, see Standard COM Errors. Additional information may be made available using the global Err object, which can be accessed by the caller using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface can be called to retrieve a text description of the error, which you can supply.

Remarks

Site Packager calls this method, specifying either a file name or a folder name, based on the value of f_PupFlags column in the Resource table of the Administration database. This bit field column currently has only one bit defined for use: bit 1. If bit 1 is set to zero (0), the szPath parameter specifies a temporary file name, and if bit 1 is set to one (1), the szPath parameter specifies a temporary folder name.

If a file name is specified, this method is expected to retrieve the packaged data from a single file, named as specified by the szPath parameter. Before this method returns, the data must be retrieved from that file, or the file moved to some other location known only to the custom resource. After this method returns, Site Packager will delete the temporary file.

If a folder name is specified, this method is expected to retrieve the packaged data from one or more files, located within the folder specified by the szPath parameter. Before this method returns, the data must be retrieved from these files, or the files moved to some other location known only to the custom resource. After this method returns, Site Packager will delete the temporary files.

If this method is designed to allow user interaction, the user interface used to accomplish this interaction must be capable of being suppressed. The bSilent parameter is used to indicate whether such suppression should occur. If the bSilent parameter is set to TRUE the user interface must be suppressed. If the bSilent parameter is set to FALSE, it is permissible to display the user interface and seek user interaction. This aspect of the method invocation allows for unattended operation.

See Also

Site Packager Interface

IPuP::Export

IPuP::CreateGroupResource


Generic Persistence Interfaces

Microsoft Commerce Server 2000 defines a set of generic Component Object Model (COM) interfaces related to object persistence.

The following table lists the generic interfaces.

Interface | Description
IPersistXML | Saves data to an XML-formatted string, and loads data from an XML-formatted string.
IPersistDictionary | Saves data to a Dictionary object, and loads data from a Dictionary object.
IPersistStreamInit | Saves data to a stream, and loads data from a stream. This is the form of persistence used in the ATL Pipeline Wizard.


IPersistXML Interface

The IPersistXML interface is implemented by an object that needs to read or write its data as XML-formatted text. For example, in the context of the Order Processing pipeline (OPP), it is used to map the contents of a business data object to its Extensible Markup Language (XML) equivalent.

The Dictionary object also implements this interface, allowing the entries in a Dictionary object to be converted into an XML-formatted string, and back again.

The IPersistXML interface supports the following methods:

Method | Description
LoadXML | Loads data from a string that contains the data in its XML representation.
SaveXML | Saves data in its XML representation, writing the result to a string.

Remarks

Header: commerce.h

IDL File: commerce.idl


IPersistXML::LoadXML

This method should load XML-formatted data from a BSTR.

Definition

HRESULT LoadXML(
long Reserved,
BSTR bstrXML
);

Parameters

Reserved

[in] Reserved for future use.

bstrXML

[in] A BSTR that contains object data in the XML representation expected by the object.

Return Values

This method must return the HRESULT value S_OK to indicate success, and should generally return one of the standard COM error values to indicate failure.

See Also

IPersistXML Interface

IPersistXML::SaveXML


IPersistXML::SaveXML

This method should save data in an XML-formatted BSTR.

Definition

HRESULT SaveXML(
long Reserved,
BSTR* bstrXML
);

Parameters

Reserved

[in] Reserved for future use.

bstrXML

[out, retval] The address of a BSTR used to return object data in its XML representation.

Return Values

This method must return the HRESULT value S_OK to indicate success, and should generally return one of the standard COM error values to indicate failure.

See Also

IPersistXML Interface

IPersistXML::LoadXML


IPersistDictionary Interface

The IPersistDictionary interface is implemented by an object that needs to read or write its data as a Dictionary object.

The IPersistDictionary interface supports the following methods:

Method | Description
GetProgID | Returns the ProgID of the object.
InitNew | Allows the object to initialize values before saved values are loaded.
IsDirty | Indicates whether the values to be saved have changed since the last save.
Load | Loads saved data from a Dictionary object.
Save | Saves data to a Dictionary object.

Remarks

Header: commerce.h

IDL File: commerce.idl


IPersistDictionary::GetProgID

This method should return the ProgID of the object.

Definition

HRESULT GetProgID(
BSTR* pbstrProgID
);

Parameters

pbstrProgID

[out, retval] The address of a BSTR used to return the ProgID of the object.

Return Values

This method must return the HRESULT value S_OK to indicate success, and should generally return one of the standard COM error values to indicate failure.

See Also

IPersistDictionary Interface


IPersistDictionary::InitNew

This method provides an opportunity for an object to initialize its state before any persisted values are loaded. You can initialize the IsDirty flag of the component within this method.

Definition

HRESULT InitNew(void);

Parameters

None.

Return Values

This method must return the HRESULT value S_OK to indicate success, and should generally return one of the standard COM error values to indicate failure.

See Also

IPersistDictionary Interface


IPersistDictionary::IsDirty

This method should report whether the values of an object have changed since they were last saved. It returns the value of the IsDirty flag of the object. The flag should be cleared by the object in its implementation of the IPersistDictionary::Save method.

Definition

HRESULT IsDirty(
long* pfDirty
);

Parameters

pfDirty

[out, retval] A pointer to a long used to return the value of the IsDirty flag.

Return Values

This method must return the HRESULT value S_OK to indicate success, and should generally return one of the standard COM error values to indicate failure.

See Also

IPersistDictionary Interface


IPersistDictionary::Load

This method should load data from a Dictionary object.

Definition

HRESULT Load(
IDispatch* pdispDict
);

Parameters

pdispDict

[in] A pointer to the IDictionary interface of the Dictionary object from which the data should be loaded.

Return Values

This method must return the HRESULT value S_OK to indicate success, and should generally return one of the standard COM error values to indicate failure.

Remarks

The object typically uses the get_Value method on the IDictionary interface to retrieve VARIANT values. For more information about the IDictionary interface, see Dictionary Object.

See Also

IPersistDictionary Interface

IPersistDictionary::Save


IPersistDictionary::Save

This method should save data to a Dictionary object.

Definition

HRESULT Save(
IDispatch* pdispDict,
long fSameAsLoad
);

Parameters

pdispDict

[in] A pointer to the IDictionary interface of the Dictionary object in which the data should be saved.

fSameAsLoad

[in] A long that is set to TRUE if the Dictionary object pointed to by the pdispDict parameter is the same as the one from which the persisted values of the component were loaded.

Return Values

This method must return the HRESULT value S_OK to indicate success, and should generally return one of the standard COM error values to indicate failure.

Remarks

The object typically uses the put_Value method on the IDictionary interface to save VARIANT values. For more information about the IDictionary interface, see Dictionary Object.

See Also

IPersistDictionary Interface

IPersistDictionary::Load


IPersistStreamInit Interface

The IPersistStreamInit interface is a standard Win32 OLE interface. This interface is typically implemented on any object that needs to support initialized stream-based persistence, regardless of whatever else the object does.

In the context of the Order Processing pipeline (OPP), it is used to load or save the component configuration in the pipeline configuration file (the pipeline calls this interface as appropriate). For more information about the IPersistStreamInit interface, see the OLE Programmer's Reference. Variables of type CComVariant can save and read their values from a stream and can be used to hold the values of a component that need to be saved.

The IPersistStreamInit interface supports the following methods:

Method | Description
GetClassID | Returns the class identifier (CLSID) of the object.
GetSizeMax | Returns the size needed to save the persisted values.
InitNew | Allows the object to initialize values before saved values are loaded.
IsDirty | Indicates whether the data to be saved has changed since the last save.
Load | Loads data from a stream.
Save | Saves data to a stream.

Header: ocidl.h

IDL File: ocidl.idl


IPersistStreamInit::GetClassID

This method should return the class identifier (CLSID) of the object.

Definition

HRESULT GetClassID(
CLSID* pClassID
);

Parameters

pClassID

[out] The address of a CLSID variable used to return the class identifier of the object.

Returns

This method must return the HRESULT value S_OK to indicate success, and should generally return one of the standard COM error values to indicate failure.

Remarks

The GetClassID method is a method of the IPersist interface from which the IPersistStreamInit interface inherits.

See Also

IPersistStreamInit Interface


IPersistStreamInit::GetSizeMax

This method should return the maximum size, in bytes, required in the stream to save the data to be persisted.

Definition

HRESULT GetSizeMax(
ULARGE_INTEGER* pCbSize
);

Parameters

pCbSize

[out] The address of a ULARGE_INTEGER used to return the number of bytes the object needs in the stream to save values.

Return Values

This method must return the HRESULT value S_OK to indicate success, and should generally return one of the standard COM error values to indicate failure.

See Also

IPersistStreamInit Interface


IPersistStreamInit::InitNew

This method provides an opportunity for the object to initialize its state before any persisted values are loaded. You should initialize the IsDirty flag of the object within this method.

Definition

HRESULT InitNew(void);

Parameters

None.

Return Values

This method must return the HRESULT value S_OK to indicate success, and should generally return one of the standard COM error values to indicate failure.

See Also

IPersistStreamInit Interface


IPersistStreamInit::IsDirty

This method should report whether the values of an object have changed since they were last saved. It returns the value of the IsDirty flag of the object. The flag should be cleared by the object in its implementation of the IPersistStreamInit::Save method.

Definition

HRESULT IsDirty(void);

Parameters

None.

Return Values

This method must return the HRESULT value S_OK to indicate that the data has changed, and must return a value of S_FALSE to indicate that the data has not changed since the last Save operation.

See Also

IPersistStreamInit Interface


IPersistStreamInit::Load

This method should load object data from the specified stream.

Definition

HRESULT Load(
LPSTREAM pStm
);

Parameters

pStm

[in] A pointer to the stream from which to load the object data.

Return Values

This method must return the HRESULT value S_OK to indicate success, and should generally return one of the standard COM error values to indicate failure.

Remarks

The seek pointer is set as it was in the most recent IPersistStreamInit::Save method. This method can seek and read from the stream, but cannot write to it.

On exit, the seek pointer must be in the same position it was in on entry, immediately past the end of the data.

See Also

IPersistStreamInit Interface

IPersistStreamInit::Save


IPersistStreamInit::Save

This method should save object data to the specified stream.

Definition

HRESULT Save(
LPSTREAM pStm,
BOOL fClearDirty
);

Parameters

pStm

[in] A pointer to a stream in which to save the object data.

fClearDirty

[in] A BOOL value indicating whether or not to clear the IsDirty flag. If TRUE, the flag should be cleared. If FALSE, the flag should be left unchanged.

Return Values

This method must return the HRESULT value S_OK to indicate success, and should generally return one of the standard COM error values to indicate failure.

Remarks

The seek pointer is positioned at the location in the stream at which the object should begin writing its data. The object calls the IStream::Write method to write its data.

On exit, the seek pointer must be positioned immediately past the object data. The position of the seek pointer is undefined if an error returns.

See Also

IPersistStreamInit Interface

IPersistStreamInit::Load


Pipeline Component Reference

This section contains the reference material for the following pipeline components supplied with Commerce Server.

Pipeline Component Name | Description
AddAttachments | Adds attachments to a direct mail message.
AdvertisingNeedOfDelivery | Ensures advertisements are selected often enough to meet business commitments.
ComposeDMLMessage | Creates the body of a direct mail message.
CreateUPMCookie | Collects cookie data to pass to an Active Server Pages (ASP) page creating a personalized direct mail message.
CSFLoadAdvertisements | Loads advertising data for the Content Selection Framework through the CacheManager object.
CSFLoadDiscounts | Loads discount data for the Content Selection Framework through the CacheManager object.
CSFWriteEvents | Used with the CacheManager object to log Content Selection Framework events.
DBOrderPromoADO | Retrieves data about price promotions from the database and adjusts item prices accordingly.
DefaultHandlingCy, DefaultHandling | Used as placeholder handling components. They initialize the total handling for the order to zero (0).
DefaultItemPriceCy, DefaultItemPrice | Set the regular price of an item to the list price returned by components such as QueryCatalogInfo or QueryProdInfoADO.
DefaultOrderSubTotalCy, DefaultOrderSubTotal | Calculates the subtotal for the order.
DefaultPayment | Assigns a default value to the payment authorization code. This component is usually replaced by a third-party payment component.
DefaultShippingCy, DefaultShipping | Placeholder shipping components. They set the shipping cost to zero (0).
DefaultShopperInfo | Moves information from the Shopper dictionary in the Context dictionary of the pipeline to the OrderForm object.
DefaultTaxCy, DefaultTax | Set the tax fields of the order to zero (0). These components are usually replaced by third-party tax components.
DefaultTotalCy, DefaultTotal | Calculates the order total from the subtotals.
EvalTargetGroups | Used to target particular groups for advertising, content selection, and discounts. This component evaluates a list of expressions for each item in a list and adjusts item selection scores.
ExecuteProcess | Runs an external executable file.
FilterContent | Applies provided filters to a content list in a Content Selection pipeline (CSP).
FixedHandling | Adds a fixed handling charge to the order.
FixedShipping | Applies a fixed shipping charge to the order.
FlagInventory | Determines whether any items on the order form are out of stock.
FormatTemplate | Merges data from selected items and their associated templates to form formatted strings. These are usually Hypertext Markup Language (HTML) strings ready for display on the page.
HistoryPenalty | Applies penalties to content items based on how recently they have been selected.
IISAppendToLog | Records information about content selection results in the QueryString field of the Internet Information Service (IIS) log file.
InitCSFPipeline | Used at the beginning of a Content Selection pipeline (CSP) to initialize the values needed in the rest of the pipeline.
ItemPromo | Applies a promotional price adjustment to an item on the order form.
LinearHandling | Sets the handling total on the order by multiplying a field on the order form by a fixed rate.
LinearShipping | Calculates the shipping total on the order form using a fixed rate.
LoadHistory | Retrieves a history string from a user profile, an item in the ASP session collection, or a cookie.
LocalInventory | Sets the number of items backordered on the order form.
MakePO | Produces a formatted purchase order (PO) text string by merging information from the order form with a purchase order template.
MoneyConverter | Converts OrderForm keys and values from integers to the new currency type, or from the new currency type to integer.
OrderDiscount | Applies discounts scheduled in the Campaign Manager module in Commerce Server Business Desk to the shopping basket.
POtoFile | Sends a purchase order or other textual data to a file.
QueryCatalogInfo | Retrieves catalog information for every item in the order form.
QueryProdInfoADO | Retrieves product information from a database.
RecordEvent | Records event delta counts for the selected content items (the winners) in the Performance dictionary.
RecordHistory | Records the identifiers of the winning content items in the history list string.
RequiredHandlingCy, RequiredHandling | Verifies that the handling total is present in the order.
RequiredItemAdjustPriceCy, RequiredItemAdjustPrice | Ensures that the current price for each item in the order is set and that it has not been changed since the last time the basket was viewed.
RequiredItemPriceCy, RequiredItemPrice | Verifies that each item in the order form has a regular price assigned to it. Regular prices are assigned by the DefaultItemPrice component and similar components.
RequiredOrderAdjustPriceCy, RequiredOrderAdjustPrice | Adjusts the total cost of each item in the order after applying any discounts.
RequiredOrderCheck | Verifies that the order form contains at least one item.
RequiredOrderInitCy, RequiredOrderInit | Initializes the payment authorization code, order ID, totals, and subtotals in the order form.
RequiredOrderSubtotalCy, RequiredOrderSubtotal | Ensures that a subtotal exists on the order form.
RequiredPayment | Verifies that the payment authorization code exists in the order form (is not NULL).
RequiredProdInfo | Deletes items flagged for deletion by a previous Product Info stage component.
RequiredShippingCy, RequiredShipping | Verifies that the shipping total has been set.
RequiredTaxCy, RequiredTax | Verifies that the total tax and tax included appear in the order form.
RequiredTotalCy, RequiredTotal | Verifies that values on a page have not been tampered with or reset. The components compare values in the order against values in the _Verify_With dictionary.
SaleAdjust | Applies a sale price to an item. This pipeline component is used for backward compatability only. This pipeline component has been replaced by the OrderDiscount component.
SampleRegionalTax | Use this component for calculating taxes using the multiple shipment features of Commerce Server 2000.
SaveHistory | Records the history string in one of three locations: the User Profile object, the ASP Session Collection, or the Hypertext Transfer Protocol (HTTP) Cookie.
SaveReceipt | Saves the order in a database table.
ScoreDiscounts | Adjusts scores of discount items to promote discounts most relevant to the current user.
Scriptor | Executes a script in a Microsoft ActiveX scripting language.
SelectWinners | Selects items based on their final scores in the Content Selection pipeline.
SendPrecomposedMessage | Sends a direct mail message composed in earlier stages in the pipeline.
SendSMTP | Sends an e-mail message to a specified recipient.
ShippingDiscountAdjust | Applies shipping discounts to the order.
ShippingManagerCache | Loads shipping data for the multiple shipments shipping architecture through the CacheManager object.
ShippingMethodRouter | The ShippingMethodRouter component looks up and runs the components to calculate shipping costs for individual shipments, it then calculates the shipping total for the entire order.
SimpleCanadaTax | Calculates the Canadian Goods and Services Tax (GST) and Provincial Sales Tax (PST).
SimpleJapanTax | Computes taxes according to the Japanese tax model.
SimpleUSTax | Applies taxes on any order sent to a specified state in the United States.
SimpleVATTax | Calculates a Value Added Tax (VAT).
Splitter | Divides the order into groups based on a list of item keys. Frequently used to divide the order into multiple shipments.
SQLItemADO | Runs a query for each item in the order form.
SQLOrderADO | Runs a single SQL query on the order, passing order parameters to the query.
StepwiseShipping | Calculates shipping costs for shipments in the multiple-shipment shipping architecture. This component is never directly used in a pipeline; it is run by the ShippingMethodRouter component.
TableHandlingADO | Sets the handling total on the order based on values retrieved from the database.
TableShippingADO | Sets the total shipping on the order by using values retrieved from the database.
ThrottleDMLPerformance | Controls the speed with which direct mail messages are processed by the pipeline.
ValidateCCNumber | Checks the expiration date of a credit card and to performs a checksum test on the number.
VerifyMessageBody | Checks the body of a direct mail message according to the user flags.
VerifyRecipientData | Checks the data about the recipient of a direct mail message.


AddAttachments

Use this component to add attachments to a direct mail message.

Although the component appears as AddAttachments in the Pipeline Editor, its ProgID is Commerce.DMLAddAttachments.

Intended use: Direct Mailer pipeline, Compose E-mail stage.

Configuration Values

None.

Values Read

The AddAttachments component reads the following values from the indicated dictionaries.

Key | Dictionary | Description
rcp_bypass | Order | Boolean. The component bypasses (skips) processing if True.
cdo_result | Order | The result code (an HRESULT) from the most recent Collaboration Data Objects (CDO) operation.
attachments | Order | A SimpleList of Uniform Resource Locators (URL) pointing to attachments.
cdo_message | Context | A reference to the CDO message object (CDO.Message).

Values Written

The AddAttachments component writes the following values to the Order dictionary.

Key | Description
cdo_result | The result code (an HRESULT) from the most recent CDO operation.
cdo_error | Optional. An error string from the most recent CDO operation, if any. NULL if there is no error.

Remarks

The AddAttachments component uses the CDO for Microsoft Windows 2000 to add the attachments to the message.

The component skips processing if the bypass flag (rcp_bypass) is True or if the last CDO operation did not succeed (cdo_result not equal to S_OK).

The message body should already exist before this component runs.

See Also

ComposeDMLMessage

CreateUPMCookie

SendPrecomposedMessage

ThrottleDMLPerformance

VerifyMessageBody

VerifyRecipientData


AdvertisingNeedOfDelivery

Use this component to ensure advertisements are selected often enough to meet business commitments.

Although this component appears as AdvertisingNeedOfDelivery in the Pipeline Editor, its ProgID is Commerce.CSFAdvertisingNeedofDelivery.

Intended use: Content Selection pipeline, Initial Score stage.

Configuration Values

None.

Values Read

The AdvertisingNeedOfDelivery component reads the following values from the indicated dictionaries.

Key | Dictionary | Description
_content | Order | A reference to the ContentList object containing the content items.
_performance | Order | A reference to the Performance dictionary retrieved from the cache by the InitCSFPipeline component.
_cache._LastNODRecalc | Context | The _LastNODRecalc key value is read from _cache key, a reference to the current dictionary containing advertising information. The _LastNODRecalc value is the time that the AdvertisingNeedOfDelivery component last recomputed the need of delivery for all ads in the ContentList object.
Trace | Context | Optional. A Boolean indicating whether score adjustment tracing is enabled. This component will not produce trace strings unless this flag is set to True.

The AdvertisingNeedOfDelivery component reads the following values for each item in the ContentList object referred to by _content.

Key | Description
need_of_delivery | The need of delivery for the item — the initial score of the item.
invalid_nod | A Boolean flag. If True, the need of delivery will be recalculated for the item.
ad_type | The type of the ad:1 for paid, 2 for house.
ad_weight | The current weight assigned to the ad. Used for house ads or paid ads in a campaign-level goaled campaign. Specified in the Campaign Manager module in Commerce Server Business Desk.
event_name | The name of the event.
events_scheduled | The total number of events scheduled for the item.
events_served | The total number of events served to date.
prev_events_served | The number of events served before the effective date.
eff_date_start | The effective item start date.
date_end | The item end date.
time_of_day_start | The time of day the event starts.
time_of_day_end | The time of day the event ends.
days_of_week | The days of the week bit flags.

Values Written

The AdvertisingNeedOfDelivery component writes the following values to the indicated dictionaries.

Key | Dictionary | Description
_content | Order | Specifically, the component writes to the following fields of the content items: need_of_delivery The calculated need of delivery for the ad. invalid_nod Reset to False because the need of delivery has been calculated. score The score for the item. Initialized to the need of delivery for the item or, for house ads, the ad_weight key.
_cache._LastNODRecalc | Context | The time that the AdvertisingNeedOfDelivery component last recomputed the need of delivery for all ads in the ContentList object.

Remarks

This component calculates the Need of Delivery (NOD) for ad items in the ContentList object and assigns these as the initial scores for the items. The NOD for each item is recalculated periodically or when the invalid_nod flag for that item is True. For more information about columns in the ContentList object, see CSFLoadAdvertisements.

The AdvertisingNeedOfDelivery component uses the SetScore method of the ContentList object for setting the initial scores.

The NOD value for paid advertisements is not calculated in this component. Rather, for efficiency, it is calculated in the LoadAdvertisements cache loader component, and in the RecordEvent pipeline component. For paid ads, this component merely copies the value in the need_of_delivery field into the score field.

The NOD for house ads is set to be equal to the weight of the house ad. The decision as to whether or not to serve house ads is made by the SelectWinners pipeline component. House ads compete only against other house ads. The run percentage for a house ad is equal to the weight of the ad divided by the sum of the weights for all house ads.

Note that this scoring strategy is different than that used in the Site Server 3.0 Commerce Edition AdServer component. In the Site Server 3.0 Commerce Edition AdServer component each house ad was scored and selected just like paid ads, only starting at a fixed need of delivery score of 0.95.

Commerce Server 2000 uses a new NOD formula for paid ads. It is designed to give each ad a fair chance of selection when the entire ad schedule is lagging. Under this formula, all ads appear at rates proportional to their goals.

The new formula is:

NOD = ( Events Scheduled / Time Total ) / ( Events Served / Time Elapsed )

With the formula used, an ad meeting its delivery goals will have a NOD equal to 1.0. An ad that is lagging will have an NOD greater than 1.0. The farther behind an ad is in its delivery goal, the greater the NOD. Ads that have exceeded their delivery goals have an NOD of less than 1.0.

See Also

SelectWinners


ComposeDMLMessage

Use this component to create the body of a direct mail message.

Although the component appears as ComposeDMLMessage in the Pipeline Editor, its ProgID is Commerce.DMLComposeMessage.

Intended use: DirectMailer pipeline, Compose E-mail stage.

Configuration Values

None.

Values Read

The ComposeDMLMessage component reads the following values from the indicated dictionaries.

Key | Dictionary | Description
rcp_bypass | Order | Boolean. The component bypasses (skips) processing if True.
use_precomposed_body | Order | Boolean. If True, the component creates the message from the plain-text body assigned to the precomposed_body key.
precomposed_body | Order | Optional. The plain-text message body. This key defaults to an empty string.
rcp_url | Order | Optional. The Uniform Resource Locator (URL) used to retrieve the mailing content. This takes precedence over default_url key.
rcp_url_isfile | Order | Optional. This is True if the URL for the content (rcp_url) is a file and not an http:// address.
rcp_url_content | Order | Optional. The content of the file pointed to by the rcp_url key if the rcp_url_isfile key is True.
from_field | Order | The "From" field for the message.
replyto_field | Order | The "Reply-to" field for the message.
rcp_email | Order | The e-mail address of the recipient.
subj_field | Order | The "Subject" field for the message.
rcp_formatting | Order | Determines the format of the message. The options are: 0 Default formatting 1 Plain text 2 MIME 3 MHTML This key overrides the default formatting.
rcp_personalize | Order | Use this key to indicate whether or not to personalize the message for this recipient. The options are: 0 Do not personalize 1 Personalize This key defaults to 1 (personalize).
rcp_locale | Order | The locale code to use for the recipient.
default_locale | Order | Optional. The locale code to use if there is no recipient locale code (rcp_locale).
cookie | Order | The dictionary containing the cookie data.
cdo_message | Context | A reference to the Collaboration Data Objects (CDO) message object (CDO.Message).
cdo_config | Context | A reference to the CDO configuration object (CDO.Configuration).
default_url | Context | Optional. The Uniforml Resource Locator (URL) used to retrieve the mailing content.
default_url_isfile | Context | Optional. This is True if the default URL is a file path and not an http:// path.
default_url_content | Context | Optional. The content of the file pointed to by the default_url key if the default_url_isfile key is True.
default_formatting | Context | Optional. The default format for the message. The options are: 0 Default formatting 1 Plain text 2 MIME 3 MHTML

Values Written

The ComposeDMLMessage component writes the following values to the Order dictionary.

Key | Description
cdo_result | The result code (an HRESULT) from the most recent CDO operation.
cdo_error | Optional. An error string from the most recent CDO operation, if any. NULL if there is no error.

Remarks

The ComposeDMLMessage component skips processing if the bypass flag (rcp_bypass) is True. Otherwise, it uses the Collaboration Data Objects (CDO) for Microsoft Windows 2000 to create the mail message. The component checks for errors after each CDO operation.

For non-personalized messages using a simple flat file, you may set the use_precomposed_body key to True. The component will load the message body from the precomposed_body key.

For personalized messages, the ComposeDMLMessage component uses the information gathered by the CreateUPMCookie component to create the cookie string.

The ComposeDMLMessage component can process multi-lingual messages using locale values from the Order dictionary (the rcp_locale key or the default_locale key). The locale values are passed to CDO without checking. If no locale code is given, the CDO default locale is used.

If a file path is used for the rcp_url key or the default_url key, Direct Mailer preloads the content of the file (into the rcp_url_content key or the default_url_content key) in order to improve performance. In this case, message content is limited to 2 megabytes for plain ASCII text and to 1 megabyte for Unicode text.

See Also

AddAttachments

CreateUPMCookie

SendPrecomposedMessage

ThrottleDMLPerformance

VerifyMessageBody

VerifyRecipientData


CreateUPMCookie

Use this component to collect cookie data to pass to an Active Server Pages (ASP) page generating a personalized message.

Although the component appears as CreateUPMCookie in the Pipeline Editor, its ProgID is Commerce.DMLCreateUPMCookie.

Intended use: DirectMailer pipeline, Create Cookies stage.

Configuration Values

None.

Values Read

The CreateUPMCookie component reads the following values from the indicated dictionaries.

Key | Dictionary | Description
rcp_bypass | Order | Boolean. The component bypasses (skips) processing if True.
rcp_personalize | Order | Optional. Numeric. Use this key to indicate whether or not to personalize the message for this recipient: 0 Do not personalize 1 Personalize This key defaults to 1 (personalize).
cookie | Order | Optional. A reference to a dictionary to hold the created cookie. This key is created if it is not present.
rcp_guid | Order | Optional. The globally unique identifier (GUID) uniquely identifying this recipient, taken from the user profile.
rcp_email | Order | The e-mail address of the recipient.
css_site | Context | The site ID string.
campaign_item | Context | Optional. The campaign item ID.
campaign_item_name | Context | Optional. The name of the campaign item.
default_url_isfile | Context | This key is True if the default Uniform Resource Locator (URL) is a file path and not an http:// path.

Values Written

The CreateUPMCookie component writes the following values to the Order dictionary.

Key | Description
Cookie | A dictionary containing the information that will be used in the cookie.

Remarks

The CreateUPMCookie component does nothing if the rcp_bypass key is True, if the default_url_isfile key is True, or if the rcp_personalize key is zero (0).

The CreateUPMCookie component keeps the cookie information in a dictionary. The cookie string is produced by the ComposeDMLMessage component.

If the message is not personalized, the component creates a cookie entry (assigns YES to the key Microsoft_DirectMailer) to prevent CDO from using a locally stored cookie.

The cookie string created from the data has the following format:

MSCSProfile='encryptedstring';CampaignItemID=string;CampaignItemName=string;UserEmail=string

The items in the cookie have the following meanings.

Abbreviation | Description
MSCSProfile | String. The user profile ID, which is needed for personalizing the message.
CampaignItemID | String. The Campaign item ID, which is necessary for click tracking.
CampaignItemNames | String. The Campaign item name, which allows labeling the message for the user.
UserEmail | String. The e-mail address of the user.

Note that the abbreviations in the table are also the keys used in the Cookie dictionary.

The user profile ID is encrypted only when the mail is sent as part of the campaign. In a stand-alone Direct Mailer job, the user profile ID is unencrypted.

See Also

AddAttachments

ComposeDMLMessage

SendPrecomposedMessage

ThrottleDMLPerformance

VerifyMessageBody

VerifyRecipientData


CSFLoadAdvertisements

Use this component with the CacheManager object to load advertising content from a database.

Note

  • Although the CSFLoadAdvertisements component implements two pipeline component interfaces (IPipelineComponent and IPipelineComponentAdmin), it is not a pipeline component, it does not appear in the Pipeline Editor, and it cannot be used or configured from the Editor.

Configuration Values

None.

Values Read

None.

Values Written

None.

Remarks

You can use the CSFLoadAdvertisements component with the CacheManager object to load advertising content for use later in your application.

When executed by the CacheManager object, the CSFLoadAdvertisements component uses two pipeline dictionaries (Order and Context) to determine how to run and how to return information to the CacheManager object.

The CSFLoadAdvertisements component first opens a connection to the database and gets the list of ads. The component uses a ContentListFactory object to populate a ContentList object with the data. The component then breaks the retrieved data into templates, target groups, and page groups.

Columns in the ContentList

The following table describes the columns in the ContentList object returned by the CSFLoadAdvertisements component. Column names appear in alphabetical order.

Column Name | Type | Flags
ad_type | short (CLCOL_I2) | 1 (CLCOL_READONLY)
ad_weight | int (CLCOL_I4) | 1 (CLCOL_READONLY)
campaign_id | int (CLCOL_I4) | 1 (CLCOL_READONLY)
customer_id | int (CLCOL_I4) | 1 (CLCOL_READONLY)
date_end | date/time (CLCOL_DATE) | 1 (CLCOL_READONLY)
date_start | date/time (CLCOL_DATE) | 1 (CLCOL_READONLY)
days_of_week | short (CLCOL_I2) | 1 (CLCOL_READONLY)
eff_date_start | date/time (CLCOL_DATE) | 1 (CLCOL_READONLY)
event_name | String (CLCOL_STRING) | 1 (CLCOL_READONLY)
events_scheduled | int (CLCOL_I4) | 1 (CLCOL_READONLY)
events_served | int (CLCOL_I4) | 1 (CLCOL_READONLY)
exposure_limit | int (CLCOL_I4) | 1 (CLCOL_READONLY)
height | short (CLCOL_I2) | 1 (CLCOL_READONLY)
industry | String (CLCOL_STRING) | 1 (CLCOL_READONLY)
invalid_nod | Boolean (CLCOL_BOOL) | 0 (DEFAULT)
item_id | int (CLCOL_I4) | 1 (CLCOL_READONLY)
name | String (CLCOL_STRING) | 1 (CLCOL_READONLY)
need_of_delivery | real (CLCOL_R4) | 0 (DEFAULT)
prev_events_served | int (CLCOL_I4) | 1 (CLCOL_READONLY)
score | real (CLCOL_R4) | 6 (CLCOL_PRIVATE | CLCOL_SCORE_COLUMN)
size | String (CLCOL_STRING) | 1 (CLCOL_READONLY)
target_groups | SafeArray (CLCOL_VARIANTARRAY) | 1 (CLCOL_READONLY)
template | String (CLCOL_STRING) | 1 (CLCOL_READONLY)
time_of_day_end | short (CLCOL_I2) | 1 (CLCOL_READONLY)
time_of_day_start | short (CLCOL_I2) | 1 (CLCOL_READONLY)
values | IDispatch (CLCOL_DISPATCH) | 1 (CLCOL_READONLY)
width | short (CLCOL_I2) | 1 (CLCOL_READONLY)

Abbreviations in the table above are enumerated values for the ContentList object. For more information, see the Remarks section of ContentListSchema.ColumnType.

Example

See the example in CacheManager Object.


CSFLoadDiscounts

Use this component with the CacheManager object to load discounts for the Content Selection Framework.

Note

  • Although the CSFLoadDiscounts component implements two pipeline component interfaces (IPipelineComponent and IPipelineComponentAdmin), it is not a pipeline component, it does not appear in the Pipeline Editor, and cannot be used or configured from the Editor.

Configuration Values

None.

Values Read

None.

Values Written

None.

Remarks

You can use the CSFLoadDiscounts component with the CacheManager object to load discounts for use later in your application.

When executed by the CacheManager object, the CSFLoadDiscounts component uses two pipeline dictionaries (Order and Context) to determine how to run and how to return information to the CacheManager object.

The CSFLoadDiscounts component first opens a connection to the database and gets the list of discounts. The component uses a ContentListFactory object to populate a ContentList object with the data. The component then extracts templates, target groups, and page groups from the retrieved information.

Columns in the ContentList

The following table describes the columns in the ContentList object returned by the CSFLoadDiscounts component. Column names appear in alphabetical order.

Column Name | Type | Flags
award_expr | int (CLCOL_I4) | 1 (CLCOL_READONLY)
award_max | int (CLCOL_I4) | 1 (CLCOL_READONLY)
campaign_id | int (CLCOL_I4) | 1 (CLCOL_READONLY)
click_required | Boolean (CLCOL_BOOL) | 1 (CLCOL_READONLY)
condition_basis | int (CLCOL_I4) | 1 (CLCOL_READONLY)
condition_expr | int (CLCOL_I4) | 1 (CLCOL_READONLY)
condition_mny_min | Currency (CLCOL_CY) | 1 (CLCOL_READONLY)
condition_qty_min | int (CLCOL_I4) | 1 (CLCOL_READONLY)
date_end | date/time (CLCOL_DATE) | 1 (CLCOL_READONLY)
date_modified | date/time (CLCOL_DATE) | 1 (CLCOL_READONLY)
date_start | date/time (CLCOL_DATE) | 1 (CLCOL_READONLY)
description | String (CLCOL_STRING) | 1 (CLCOL_READONLY)
disc_id | int (CLCOL_I4) | 1 (CLCOL_READONLY)
disjoint | Boolean (CLCOL_BOOL) | 1 (CLCOL_READONLY)
exposure_limit | int (CLCOL_I4) | 1 (CLCOL_READONLY)
expressions_used_for_display | Boolean (CLCOL_BOOL) | 1 (CLCOL_READONLY)
height | short (CLCOL_I2) | 1 (CLCOL_READONLY)
item_id | int (CLCOL_I4) | 1 (CLCOL_READONLY)
limit | int (CLCOL_I4) | 1 (CLCOL_READONLY)
name | String (CLCOL_STRING) | 1 (CLCOL_READONLY)
offer_type | int (CLCOL_I4) | 1 (CLCOL_READONLY)
offer_value | Currency (CLCOL_CY) | 1 (CLCOL_READONLY)
order_level | Boolean (CLCOL_BOOL) | 1 (CLCOL_READONLY)
pagegroups | SafeArray (CLCOL_VARIANTARRAY) | 1 (CLCOL_READONLY)
rank | int (CLCOL_I4) | 1 (CLCOL_READONLY)
required_exprs | SafeArray (CLCOL_VARIANTARRAY) | 1 (CLCOL_READONLY)
score | real (CLCOL_R4) | 6 (CLCOL_PRIVATE | CLCOL_SCORE_COLUMN)
size | String (CLCOL_STRING) | 1 (CLCOL_READONLY)
special_offer_type | String (CLCOL_STRING) | 1 (CLCOL_READONLY)
target_groups | SafeArray (CLCOL_VARIANTARRAY) | 1 (CLCOL_READONLY)
template | String (CLCOL_STRING) | 1 (CLCOL_READONLY)
width | short (CLCOL_I2) | 1 (CLCOL_READONLY)

Abbreviations in the table above are enumerated values for the ContentList object. For more information, see the Remarks section of ContentListSchema.ColumnType.

Example

See the example in CacheManager Object.


CSFWriteEvents

Use this component with the CacheManager object to log events content from the Content Selection Framework.

Note

  • Although the CSFWriteEvents component implements two pipeline component interfaces (IPipelineComponent and IPipelineComponentAdmin), it is not a pipeline component, it does not appear in the Pipeline Editor, and cannot be used or configured from the Editor.

Configuration Values

You can determine how the CSFWriteEvents component runs by setting component properties. Use the following boxes on the CSFWriteEvents tab of the Component Properties dialog box to determine this information.

Box | Description
Connection String | The connection string to connect to the database. This may be a full connection string or a name in a connection map. If blank, the default connection string is passed through.

Values Read

The CSFWriteEvents component reads the following values from the indicated dictionaries.

Key | Dictionary | Description
_performance | Order | The previous event delta count for the various content items.

Values Written

None.

Remarks

You can use the CSFWriteEvents component with the CacheManager object to save event information in the database for later adjustment of advertising and other campaign schedules.

When run by the CacheManager object, the CSFWriteEvents component uses two pipeline dictionaries (Order and Context) to determine how to run and how to return information to the CacheManager object.

The CSFWriteEvents component first opens a connection to the database. It then writes the event data out to the database using information stored in the Performance dictionary.

Example

See the example in CacheManager Object.


DBOrderPromoADO

Use this component to run a query to retrieve data about price promotions from the database and adjust item prices accordingly.

Intended use: Order Processing pipeline, Order Adjust Price stage.

Note

  • The DBOrderPromoADO component should not be used for future development. The discount features of the Content Selection pipeline provide a more powerful and general mechanism for applying product discounts. For more information, see Discount Objects.

Configuration Values

You can determine where the DBOrderPromoADO component retrieves the document and where it writes the result by setting component properties. Use the following boxes on the DB Order Promo (ADO) tab of the Component Properties dialog box to determine this information.

Box | Description
Query | Type either the full SQL text of the query executed by this component or the name of a query whose full SQL text is defined in the Global.asa file.
Connection string | Type the connection string to connect to the database. This may be a full data source name (DSN) or a name in a connection map. If blank, the default connection string is used.

Values Read

The DBOrderPromoADO component reads the following values from the indicated dictionaries.

Key | Dictionary | Description
item._iadjust_currentprice | Order | The current price of the item before promotion is applied.
item._product_* | Order | Optional.
_shopper_* | Order | Optional.
item._n_unadjusted | Order | The quantity of this item that have not been discounted.
item.quantity | Order | The quantity of the item ordered.
DefaultConnectionString | Context | Optional. The key in the Application dictionary containing the default query string.
ConnectionStringMap | Context | Optional. The map in which to look up the name of a mapped connection string.
QueryMap | Context | Optional. A reference to a dictionary containing a query map.

Values Written

The DBOrderPromoADO component writes the following values to the Order dictionary.

Key | Description
item._oadjust_adjustedprice | The total cost for an item. May have been adjusted by the application of a promotion.
item._n_unadjusted | The quantity of this item that have not been discounted. May have been adjusted by the application of a promotion.

Remarks

The DBOrderPromoADO component executes a query to determine if the promotional conditions defined in a database table have been met by items in the OrderForm. If they have, the DBOrderPromoADO component applies the promotion to the OrderForm object by initializing item._oadjust_adjustedprice and item._n_unadjusted keys for the item affected by the promotion.

The item._oadjust_adjustedprice key reflects the total cost of a given item, adjusted for promotions. The item._n_unadjusted key contains the number of items that were not affected by the promotion.

Suppose, for example, that you define a promotion in which a user who purchases one of Item A gets one of Item B at half-price. Suppose further that the following conditions exist:

  • The user has purchased one of Item A.

  • The user has purchased three of Item B.

  • Item B has a regular price of 1.00.

When the DBOrderPromoADO component is run, the user will, by the terms of the promotion, get two of the items at the regular price of 1.00. However, the user will get the third item at fifty percent off. Thus, the item._oadjust_adjustedprice key for Item B will be 2.50.

In addition, because only one of the three Item B products will have been promotionally adjusted, the item._n_unadjusted key will be set to two. This is critical, because once an item has had its price adjusted, the price cannot be adjusted again.

In this example, one of Item B had its price adjusted. The other two Item B items did not. Consequently, no matter how many of the three items qualify for a promotional adjustment under a later DBOrderPromoADO component, only the two previously unadjusted Item B items can be adjusted.

The Promotions Table

Because the DBOrderPromoADO component expects the query that you supply to reference a specific group of table columns, the table in which you store promotions must have a given structure.

The database query must return at least the following columns:

Database Column | Description
cond_column | This column contains the name of the item attribute against which the promotion condition is checked.
cond_op | A comparison operator that compares cond_column to cond_value; for example = or <>.
cond_value A value that identifies the item being promoted. For example, if the cond_column is _product_pfid, the cond_op is "=" and the cond_value is 22; then an item in the items list with a _product_pfid that evaluates to 22 meets the condition set.

If this value is a number, it must be an integer value; floating-point numbers (for example, 10.0) are not accepted.
cond_all | Optional. If set to 1 (True), any product in the set of products to be purchased will trigger this promotion. Otherwise, this promotion will be triggered only by products that meet the criteria defined in cond_column, cond_op, and cond_value (the condition set). Products are removed from the condition and award sets after they have been involved in a promotion to prevent a single product from being a participant in multiple promotions.
award_column | The award_column, coupled with the award_op and award_value columns, define the award set for the promotion. The award column contains a value indicating the key and value that defines the award criteria.
award_op | A comparison operator that compares award_column with award_value; for example = or <>.
award_value | This column indicates the value of the element referenced by the award_column column.
award_all | Optional. If set to 1 (True), then the award can be applied to any product. Otherwise, this award will be applied only to products that meet the criteria defined in the award_column, award_op, and award_value columns (the award set).
shopper_column | A value indicating the user-specific information. This can be a wildcard value (@) that indicates all users are eligible for the promotion.
shopper_op | This column should be set to = if a user is specified; otherwise, it is a wildcard value (@).
shopper_value | A value indicating the type of user; if it is any user, set it to a wildcard value (@).
shopper_all | Optional. This column indicates whether this promotion is available to all users. If this value is 0 (False), the promotion is available only to users who meet the criteria defined in the shopper_column, shopper_op, and shopper_value columns.
cond_min | This column contains a value, in cents (or other currency unit), or the number of units of the minimum purchase necessary to be eligible for the promotion. The interpretation of the cond_min column depends on the value referenced in the cond_basis column. For example, if the cond_basis column contains "P", the cond_min column is assumed to measure price. If the cond_basis column contains "Q", the cond_min column is assumed to measure quantity.
cond_basis | A value indicating whether the cond_min column is measured in price or quantity (P or Q, respectively).
award_max | The size of the award set.
disjoint_cond_award The column contains a number (1 or 0) indicating whether the award can be "disjointed." If the value is 0, the award is disjointed; otherwise, it is not. The term disjointed, in this context, refers to whether or not an item can promote itself. Where the condition set and the award set do not refer to the same item, this value is ignored.

Suppose, for example, that you have a promotion that dictates that if you purchase one of Item A, you get one of Item A at fifty percent off.

If the award is not disjointed (the column disjoint_cond_award is equal to 0), then a user needs to purchase only one of Item A to get that item at fifty percent off. If the award is disjointed (the column disjoint_cond_award is equal to 1), then a user purchasing Item A will get a second Item A at fifty percent off, but will receive no discount until the second item is added to the basket.
disc_value | A number indicating the amount of the discount.
disc_type | A type of discount, either a percent (%) or a currency ($) symbol.
date_start | Optional field. The date the promotion begins, at one second after midnight.
date_end | Optional field. The date the promotion ends, at one second after midnight. Because the date_start and date_end columns are actually date-time pairs that specify midnight, the date_end column excludes the date specified.
Connection String | The DSN connection string to be used to connect to the database.

An order promotion has three criteria: the user criterion, a condition criterion, and an award criterion. If the user does not match the user criterion, the promotion is not applied. If the user does match the user criterion, then the other two criteria are applied to all the items in the order, producing two sets: the condition set (those matching the condition criterion) and the award set (those matching the award criterion).


DefaultHandlingCy, DefaultHandling

Use these components as placeholder handling components. They initialize the total handling for an order to zero (0).

The DefaultHandling componet is for backward compatibility only. The DefaultHandlingCy component operates in both Site Server 3.0 Commerce Edition compatibility mode and in Commerce Server 2000 mode pipelines. For more information, see Currency Enhancements.

Intended use: Order Processing pipeline, Handling stage.

Configuration Values

None.

Values Read

None.

Values Written

The DefaultHandlingCy component assigns a value to the following key in the Order dictionary. The DefaultHandling component assigns a value to the same key but without cy_.

Key | Description
order._cy_handling_total | The total cost for handling the order.

Remarks

The DefaultHandlingCy and DefaultHandling components assign zero (0) to the total handling cost in the Order dictionary. They are placeholder components that are replaced by other handling components in actual use.


DefaultItemPriceCy, DefaultItemPrice

Use these components to set the regular price of an item to the list price returned by components such as QueryCatalogInfo or QueryProdInfoADO.

The DefaultItemPrice component is for backward compatibility only. The DefaultItemPriceCy component operates in both Site Server 3.0 Commerce Edition compatibility mode and in Commerce Server 2000 mode pipelines. For more information, see Currency Enhancements.

Intended use: Order Processing pipeline, Item Price stage.

Configuration Values

None.

Values Read

The DefaultItemPriceCy component reads the following values from the indicated dictionaries. The DefaultItemPrice component reads the same value but without cy_.

Key | Dictionary | Description
item._product_cy_list_price | Order | The list price for the item as returned by a component such as QueryCatalogInfo or QueryProdInfoADO.

Values Written

The DefaultItemPriceCy component assigns a value to the following key in the Order dictionary. The DefaultItemPrice component assigns a value to the same key but without cy_.

Key | Description
item._cy_iadjust_regularprice | The regular price of the item.

Remarks

The DefaultItemPriceCy and DefaultItemPrice components perform the same actions although on different dictionary keys. The following discussion uses the keys for DefaultItemPriceCy.

To set the regular price to a price other than the list price, replace these components in the pipeline.

For each item in the order form (each item in the items collection), the DefaultItemPriceCy component assigns the _iadjust_regularprice key to the value stored in the _cy_product_list_price key for the item. The regular price is typically set by the QueryCatalogInfo or QueryProdInfoADO components in the Product Info stage.

If the QueryCatalogInfo or QueryProdInfoADO components do not retrieve the list price, the Item dictionary will not contain the _product_list_price key. In this case, you need to add a component (a Scriptor, for example) to retrieve the list prices so that the DefaultItemPrice component can initialize the _iadjust_regularprice key.

Stages that follow the Item Price stage in the pipeline contain components that depend on the _iadjust_regularprice key being set. If this key does not have a value, these components fail. The RequiredItemPrice component ensures that the values exist.

See Also

QueryCatalogInfo

QueryProdInfoADO

RequiredItemPriceCy, RequiredItemPrice


DefaultOrderSubTotalCy, DefaultOrderSubTotal

Use these components to calculate the subtotal for an order.

The DefaultOrderSubTotal component is for backward compatibility only. The DefaultOrderSubTotalCy component operates in both Site Server 3.0 Commerce Edition compatibility mode and in Commerce Server 2000 mode pipelines. For more information, see Currency Enhancements.

Intended use: Order Processing pipeline, Order Subtotal stage.

Configuration Values

None.

Values Read

The DefaultOrderSubTotalCy component reads the following values from the indicated dictionaries. The DefaultOrderSubTotal component reads the same key but without cy_.

Key | Dictionary | Description
item._cy_oadjust_adjustedprice | Order | The total cost of an item.

Values Written

The DefaultOrderSubTotalCy component assigns a value to the following key in the Order dictionary. The DefaultOrderSubTotal component assigns to the same key but without cy_.

Key | Description
_cy_oadjust_subtotal | The subtotal of all the items.

Remarks

The subtotal is calculated by summing the total cost for each item in the items SimpleList object in the OrderForm object.


DefaultPayment

Use this component to assign a default value to the payment authorization code. This component is usually replaced by a third-party payment component.

Note

  • The DefaultPayment component does not follow the component coordination rules. The component always sets the payment authorization code.

Intended use: Order Processing pipeline, Payment stage.

Configuration Values

None.

Values Read

None.

Values Written

The DefaultPayment component assigns a value to the following key in the Order dictionary.

Key | Description
_payment_auth_code | The payment authorization code.

Remarks

The DefaultPayment component assigns the value FAITH, a string, as the default authorization code.


DefaultShippingCy, DefaultShipping

Use these components as placeholder shipping components. The components set the shipping cost to zero (0).

The DefaultShipping component is for backward compatibility only. The DefaultShippingCy component operates in both Site Server 3.0 Commerce Edition compatibility mode and in Commerce Server 2000 mode pipelines. For more information, see Currency Enhancements.

Note

  • The DefaultShippingCy and DefaultShipping components do not follow the component coordination rules. The components always zero the shipping total.

Intended use: Order Processing pipeline, Shipping stage.

Configuration Values

None.

Values Read

None.

Values Written

The DefaultShippingCy component assigns a value to the following key in the Order dictionary. DefaultShipping assigns a value to the same key but without cy_.

Key | Description
_cy_shipping_total | The total cost for shipping the order.

Remarks

The DefaultShippingCy and DefaultShipping components set the shipping total to zero (0).


DefaultShopperInfo

Use this component to move information from the Shopper dictionary in the Context dictionary of the pipeline to the OrderForm.

Intended use: Order Processing pipeline, Shopper Information stage.

Configuration Values

None.

Values Read

The DefaultShopperInfo component reads the following value from the indicated dictionary.

Key | Dictionary | Description
Shopper | Context | The dictionary containing user information.

Values Written

The DefaultShopperInfo component reads the values of all keys in the Shopper dictionary and creates corresponding keys, prefixed with _shopper_ and with the same values, in the OrderForm object.

Remarks

If there is no Shopper dictionary in the Context dictionary, the component does nothing.


DefaultTaxCy, DefaultTax

Use these components to set the tax fields of the order to zero (0). These components are usually replaced by third-party tax components.

The DefaultTax component is for backward compatibility only. The DefaultTaxCy component operates in both Site Server 3.0 Commerce Edition compatibility mode and in Commerce Server 2000 mode pipelines. For more information, see Currency Enhancements.

Note

  • The DefaultTaxCy and DefaultTax components do not follow the component coordination rules. The components always sets the total tax and the tax included in the order subtotal to zero (0).

Intended use: Order Processing pipeline, Tax stage.

Configuration Values

None.

Values Read

None.

Values Written

The DefaultTaxCy component assigns values to the following keys in the Order dictionary. The DefaultTax component assigns a value to the same keys but without cy_.

Key | Description
_cy_tax_total | The total tax for the order.
_cy_tax_included | The amount of tax already included in the subtotal of the order.

Remarks

The components set the tax fields to zero (0).


DefaultTotalCy, DefaultTotal

Use these components to calculate the order total from the subtotals.

The DefaultTotal component is for backward compatibility only. The DefaultTotalCy component operates in both Site Server 3.0 Commerce Edition compatibility mode and in Commerce Server 2000 mode pipelines. For more information, see Currency Enhancements.

Intended use: Order Processing pipeline, Order Total stage.

Configuration Values

None.

Values Read

The DefaultTotalCy component reads the following values from the indicated dictionaries. The DefaultTotal component reads the same keys but without cy_.

Key | Dictionary | Description
_cy_oadjust_subtotal | Order | The subtotal of all of the items in the items list. Set by the DefaultSubTotal component.
_cy_shipping_total | Order | The total shipping cost for the items.
_cy_tax_total | Order | The total tax for the order.
_cy_handling_total | Order | The total cost for handling the order.

Values Written

The DefaultTotalCy component assigns a value to the following key in the Order dictionary. The DefaultTotal component assigns a value to the same key but without cy_.

Key | Description
_cy_total_total | The complete total for the order.

Remarks

These components verify that all four totals on the order have been set.

If all four values exist, they are added together and assigned to the complete total in the Order dictionary.

If any value is missing, the component stops and returns an error.


EvalTargetGroups

Use this component to target particular groups for advertising, content selection, and discounts. The component evaluates a list of expressions for each item in a list and adjusts item selection scores.

Intended use: Content Selection pipeline, Score stage.

Configuration Values

You can determine how the EvalTargetGroups component evaluates targeting expressions by setting component properties. Use the following boxes on the Eval Expressions tab of the Component Properties dialog box evaluate this information.

Row | Column | Description
Target | Match | The multiplier applied when a target expression evaluates to "True." The default is 1.2.
 | Mismatch | The multiplier applied when a target expression evaluates to "False." The default is 1.
Require | Match | The multiplier applied when a require expression evaluates to "True." The default is 1.
 | Mismatch | The multiplier applied when a require expression evaluates to "False." The default is 0 (zero).
Exclude | Match | The multiplier applied when an exclude expression evaluates to "True." The default is 0 (zero).
 | Mismatch | The multiplier applied when an exclude expression evaluates to "False." The default is 1.

Values Read

The EvalTargetGroups component reads the following values from the indicated dictionaries.

Key | Dictionary | Description
_content | Order | A reference to a ContentList object. Specifically, the target_groups field of the content items are read. The target_groups field contains an array of IDs of the target groups associated with each content item.
TargetGroups | Context | A dictionary of SimpleList objects. The keys are target group identifiers. Each SimpleList object contains expression name and action pairs, stored in alternating entries: the first expression name at index 0, first action at index 1; second expression name at index 2, second action at index 3; and so on. Actions are numbers with the following meanings: 1 Target 2 Require 3 Exclude 4 Exclusive (Sponsorship)
Evaluator | Context | A reference to the ExpressionEval component to use.
ContextProfile | Context | Optional. The ContentSelector object (a dictionary) for use in expression evaluation. The dictionary contains values to test against context profile expressions entered through Commerce Server Business Desk.
UserProfile | Context | Optional. A reference to a ProfileObject object containing the profile for the current user. Used as the "UserObject" profile in evaluating the expressions.
Trace | Context | Optional. A Boolean indicating whether score adjustment tracing is enabled. This component will not produce trace strings unless this key is set to True.

Values Written

The EvalTargetGroups component writes the following values to the Order dictionary.

Key | Description
_content | A reference to a ContentList object with any required adjustments made to the score fields of content items.

Remarks

The EvalTargetGroups component evaluates all of the listed target expressions for each of the content items in the list. If the expression is True, then it will apply the Match value for the indicated action, one of Target, Require, or Exclude. Similarly, if the expression is False, then it applies the Mismatch multiplier for the specified action.

A content item may have more than one target expression that applies to it. Because of this, all target expressions are evaluated for a content item but only the expression that produces the largest multiplier is applied.

Each action corresponds to a pair of multipliers. One of the multipliers is applied to the score of content items in the ContentList object. A multiplier in the pair is chosen based on the outcome of the expression: True or False.

Sponsorship is handled differently. The Sponsorship action is not a score multiplier. Rather, if any target group contains a Sponsorship expression that evaluates to True, then all target groups that do not contain a Sponsorship expression that evaluates to True are disqualified.

If an expression produces an undefined value, then the multiplier applied depends on the action associated with the expression:

Action | Multiplier Applied
Target | Mismatch multiplier
Require | Mismatch multiplier
Exclude | Match multiplier
Sponsorship | 0

An example of an undefined expression value would be an expression that depends on the age of the user when the age of the user is unknown.

The EvalTargetGroups and ExpressionEval components both use result caching for high performance. If multiple target groups reference the same expression, the expression is evaluated only once and subsequently the cached result is used. Similarly, if multiple content items reference the same target group, the target group is evaluated only once and subsequently the cached results are used.

This component uses the ExpressionEval object to evaluate expressions.

The behavior of the PenalizeUnmatchedTargets property of the Site Server 3.0 Commerce Edition AdServer component can be replicated by changing the multiplier for Target/Mismatch to 0.95.

See Also

ExpressionEval Object


ExecuteProcess

Use this component to run an external executable file.

Intended use: Any pipeline, any stage.

Configuration Values

You can determine where the ExecuteProcess component retrieves the document and where it writes the result by setting component properties. Use the following boxes on the Execute Process tab of the Component Properties dialog box to determine this information:

Box | Description
Path Name of the executable | The complete path to the executable file to be run by this component. To locate the file, click Browse.
Arguments to the executable | The arguments to pass to the executable file. The argument may contain %1 which is replaced by the value in the OrderForm object whose name appears in the Field Name of substitutable parameter box.
Field Name of substitutable parameter | (Optional) The key in the OrderForm whose value is substituted for the %1 argument and passed to the executable file.

Values Read

The value in the Order dictionary whose key is specified in the Field Name of substitutable parameter box.

Values Written

None.

Remarks

The ExecuteProcess component runs an executable file.


FilterContent

Use this component to apply provided filters to a content list in a Content Selection pipeline (CSP).

Intended use: Content Selection pipeline, Filter stage.

Configuration Values

None.

Values Read

The FilterContent pipeline component reads the following values from the indicated dictionaries.

Key | Dictionary | Description
FilterRequire | Order | A Dictionary object specifying fields (as keys) and corresponding values that a content item must have in order to avoid having its score set to zero (0).
FilterExclude | Order | A Dictionary object specifying fields (as keys) and corresponding values that a content item must not possess in order to avoid having its score set to zero (0).
_content | Order | A key whose value is a reference to a ContentList object. The Filter method accesses various fields in the content items in the ContentList object in the course of filtering the content items.

Values Written

The FilterContent pipeline component writes the following value to the Order dictionary.

Key | Description
_content | A key whose value is a reference to a ContentList object. The Filter method may set the score field of various content items in the ContentList object to zero (0), thus eliminating them from the selection process.

Remarks

The FilterContent component applies filters to a content list in a Content Selection pipeline. The filters to apply are retrieved from FilterRequire and FilterExclude dictionaries in the Order dictionary.

This component uses the Filter method of the ContentList object. Content items may be eliminated from the selection process either by failing to meet a required condition or by meeting an exclusion condition. The Filter method is called once for each key in the dictionaries referenced by the FilterRequire and FilterExclude entries. The keys in these dictionaries should correspond to column names in the ContentList object; the values stored under the keys correspond to the values to be tested for.

Filtering is much faster than expression evaluation and it occurs at an earlier stage in CSF pipelines. The ContentList object builds indexes on any fields that are filtered. Because of this indexing, it is more efficient to do as much targeting as possible in the filter stage using the FilterContent component. PageGroup targeting in the Campaign Manager is an example of how a typical CSF pipeline takes advantage of this.

The list of content is contained in the ContentList object identified by the _content entry in the Order dictionary.

See Also

ContentList.Filter


FixedHandling

Use this component to add a fixed handling charge to an order.

The FixedHandling component is supplied for backward compatibility with Site Server 3.0 Commerce Edition only. For more information, see Currency Enhancements

Intended use: Order Processing pipeline, Handling stage.

Configuration Values

You can determine how the FixedHandling component applies the handling cost and the cost itself by setting component properties. Use the following boxes on the Fixed Handling tab of the Component Properties dialog box to determine this information.

Box | Description
Apply when Determines when to apply the handling charge specified in the Cost box. The values are:

Always

Default. Specifies that the handling charge is always set to the value of the Cost box.

Equal to method

Specifies that the handling cost should be applied when the value of the shipping_method key in the Order dictionary is the same as the string specified for the Method box.

Has any value

Specifies that the handling cost is applied when the shipping_method key of the order has any non-null value.
Method | The shipping method to match against the value of the shipping_method key in the Order dictionary. Used when value in the Apply when box is set to Equal to method.
Cost | This box specifies the handling charge.

Values Read

The FixedHandling component reads the following value from the indicated dictionary.

Key | Dictionary | Description
shipping_method | Order | This key is read when the value in the Apply when box is set to Equal to method or Has any value.

Values Written

The FixedHandling component writes the following value to the Order dictionary:

Key | Description
_handling_total | The handling total for the entire order.

Remarks

The FixedHandling component sets the value of the _handling_total key on the order form to the fixed amount specified in the Cost box.

Programmatic Use

To use the FixedHandling component outside a pipeline, you must configure it by assigning values to keys in the Configuration dictionary. The keys correspond to the indicated fields in the Component Properties dialog box.

The FixedHandlingCy component does not require configuration values when used outside of a pipeline.

For more information about using pipeline components outside of pipelines, see MicroPipe in C++ for components written in C++, or Micropipe in Visual Basic for components written in Visual Basic.


FixedShipping

Use this component to apply a fixed shipping charge to an order.

Note

  • The FixedShipping component is for backward compatibility with Site Server 3.0 only and does not support the new, extended Currency datatype.

Intended use: Order Processing pipeline, Shipping stage.

Configuration Values

You can determine how the FixedShipping component applies the shipping cost by setting component properties. Use the following boxes on the Fixed Shipping tab of the Component Properties dialog box to determine this information.

Box | Description
Apply when Determines when to apply the shipping charge specified in the Cost box. The values are:

Always

Default. Specifies that the shipping charge is always set to the value of the Cost box.

Equal to method

Specifies that the shipping cost should be applied when the value of the shipping_method key in the Order dictionary is the same as the string specified for the Method box.

Has any value

Specifies that the shipping cost is applied when the shipping_method key of the order has any non-null value.
Method | The shipping method to match against the value of the shipping_method key in the Order dictionary. Used when the value in the Apply when box is set to Equal to method.
Cost | Specifies the shipping charge.

Values Read

The FixedShipping component reads the following value from the indicated dictionary.

Key | Dictionary | Description
shipping_method | Order | Read when the value in the Apply when box is set to Equal to method or Has any value.

Values Written

The FixedShipping component writes the following value to the Order dictionary:

Key | Description
_shipping_total | The shipping total for the entire order.

Remarks

The FixedShipping component sets the value of the _shipping_total key to the fixed amount specified in the Cost box.

You cannot specify more than one method per component. If you need to specify more than one shipping method, add a separate FixedShipping component for each method.

Example

The following example sets the shipping cost to $9.95, for items shipped by Carrier1.

Box | Value
Apply when | Equal to Method
Method | Carrier1
Cost | 995

When configuring the components in this stage, make sure that the components are in the order in which you want them executed so that charges are calculated and applied in the correct order.


FlagInventory

Use this component to determine if any items on the order form are out of stock.

Intended use: Order Processing pipeline, Inventory stage.

Configuration Values

You can determine how the FlagInventory component deals with back orders by setting component properties. Use the following boxes on the Flag Inventory tab of the Component Properties dialog box to determine this information.

Box | Description
Disallow Backorder | If selected, indicates back orders are not permitted. The component will add a message to the _Purchase_Errors list when there is a back order.

Values Read

The FlagInventory component reads the following values from the indicated dictionaries.

Key | Dictionary | Description
item._product_in_stock | Order | Optional. The quantity of this item in stock.
item.quantity | Order | The quantity of the item ordered.
MessageManager | Context | Dynamic. A reference to a MessageManager object. Used to retrieve the out-of-stock constant (pur_out_of_stock) in case of an error. Used only if the Disallow Backorder box is selected.

Values Written

The FlagInventory component writes the following values to the Order dictionary.

Key | Description
item._inventory_backorder | The amount back ordered to fulfill the order for this item.
_Purchase_Errors | Dynamic. Error messages are written to this SimpleList object only if the Disallow Backorder box is selected.

Errors

The component writes error messages to the _Purchase_Errors collection. The component uses a MessageManager object to retrieve user warning message text.

Constant | Condition
pur_out_of_stock | An item in the order is out of stock.

Remarks

When this component runs, it loops through the item list in the order form, checking the value of the _product_in_stock field for each item. If that value is zero (0), the component sets the _inventory_backorder key to the quantity ordered to indicate the shortage. In addition, if the Disallow Backorder box is selected, the component writes an out-of-stock message to the _Purchase_Errors list of the order form.

The _product_in_stock value corresponds to the in_stock column in the products database table.

This component verifies that none of the order items have the _product_in_stock value, which corresponds to the in_stock column in the products database table, set to zero (0). If any item does have this field set to zero, the FlagInventory component sets the_inventory_backorder key to the quantity ordered (indicating the shortage). If such a shortage occurs and the Disallow Backorder box is selected, the FlagInventory component will generate a pur_out_of_stock error in the _Purchase_Errors collection. This component interacts with a manual inventory control process; the product database must be updated to reflect the actual stock on hand.

If you include the FlagInventory component in your pipeline, the order form must contain a column named _product_in_stock. This value is placed in the order form by the query that is executed in the Product Information stage, usually by the QueryProdInfoADO component or the QueryCatalogInfo component. Usually, this value is selected from a database column named in_stock. You can also place _product_in_stock column on the order form by manipulating the query.

This component interacts with a manual inventory control process. The product database must be updated to reflect the actual stock on hand.


FormatTemplate

Use this pipeline component to merge data from selected items and their associated templates to form formatted strings. These are usually HTML strings ready for display on the page. Items may come from the Context dictionary as well as the ContentList object in the Order dictionary.

Although this component appears as the FormatTemplate component in the Pipeline Editor, its ProgID is Commerce.CSFFormatTemplate.

Intended use: Content Selection pipeline, Format stage.

Configuration Values

None.

Values Read

The FormatTemplate component reads the following values from the indicated dictionaries.

Key | Dictionary | Description
_winnerindexes | Order | A SimpleList object containing the ContentList object positions of the winning content items. If this key is present, the _winners key should not be present. If both are present, only this key is used.
_winners | Order | A SimpleList object containing the values from the item_id key of the winning content items. If this entry is present, the _winnerindexes key should not be present. If both are present, only the _winners_indexes key is used.
_content | Order | A reference to the ContentList object. Multiple values are read. See the Remarks section below.
<arbitrary entry> | Context | Optional. Any arbitrary property from the Context dictionary can be a source for a substituted value in a template.
FormatTemplate | Order | Optional. If present, this key overrides the default format template associated with each content item being formatted. The value of this key can be: A string The string contains the key in the Templates dictionary of the Context dictionary. The value associated with that key is a Format Template dictionary. A reference A reference to a Format Template dictionary.
templates | Context | Optional. A dictionary that maps names to Format Template dictionaries. Normally, the templates key of a content item would contain a name used as a key to this dictionary, giving the proper Format Template dictionary.
ContextProfile | Context | Optional. A reference to the ContentSelector object that can be named as a source for the template substitutions performed by this component.
RedirectUrl | Context | Optional. A string containing the URL of the redirector script. Note that most templates require this key.
CacheName | Context | Optional. A string containing the name of the current content cache. Note that most templates require this key.

The FormatTemplate component reads the following values for each item in the ContentList object referred to by the _content key:

Key | Description
item_id | The identifier for the various content items.
<arbitrary fields> | A field in the ContentList object specified by a Template dictionary. Acts as the source of a value used in the template.
values | A dictionary derived from the creative_property and creative_property_values tables in the marketing database. The values in the dictionary are specific to the creative type.
template | The name of a template in the Templates dictionary. Either this value or the FormatTemplate entry in the Order dictionary must be specified.

All of these keys are optional with the exception of the item_id key.

Values Written

The FormatTemplate component writes the following values to the Order dictionary.

Key | Description
_formatted | A SimpleList object containing the formatted strings.

Remarks

A template is a string that contains substitution variables. Substitution variables can consist of letters, numbers, the underscore character, and are identified in the template string by the delimiters {% and %}. For example, {%Book_Title%} is a valid substitution variable. If for some reason you need to have a literal {% in your document, append an ampersand (&) to the sequence ({%&).

The information that replaces the substitution variables can come from several sources, including the Values dictionary in the ContentList object, the actual content item fields in the ContentList object, and from arbitrary properties in the ContentSelector object (CSO) or the Context dictionary. In addition, a default value can be supplied in the event that no value is found elsewhere. The source of the value, the default value, and how the value should be encoded, are all contained with the template string in a Format Template dictionary.

The Values dictionary is used to store variable properties of a particular type of content. For example, image ads and text ads are both ads, and should be in the same ContentList object so that they can compete with each other. But some of their properties are unique and do not apply to ads of the other type. This presents problems in the fixed schema supported by the ContentList object. The solution is a CLCOL_DISPATCH column (named Values) containing values that are references to dictionaries that contain unique keys and values. The keys and values in these dictionaries come from the creative_property and creative_property_values tables.

Format Template dictionaries are created by the LoadAdvertisements and LoadDiscounts objects from information in the marketing database. A Format Template dictionary contains a single template and information about the substitution variables in the template. It contains an entry named "text" and the value for that entry is the template string. For each substitution variable in that string, the Format Template dictionary contains three additional entries that provide the value source, the default value, and the encoding scheme for that variable. The names of these additional entries are formed by the name of the variable appended with one of the strings "_default", "_source", and "_encoding." The following table describes these additional dictionary entries.

Dictionary Entries | Description of Dictionary Entry Value
Text | The text of the template, which may include substitution variables. The other entries in the dictionary provide information about how values for the substitution variables are retrieved and formatted.
<variable>_default | A string that provides the default value, if any, for the substitution value. The default value is used if a value cannot be found in any of the specified sources.
<variable>_source A number indicating sources for the value. The name of the variable is searched for in a variety of places, indicated by one of the following numbers:

1

Looks for a value in the content item. First, the Values dictionary in the ContentList object is used, if it is present. Next, the columns of the ContentList object are examined.

2

Uses an intrinsic value, if one matches. The only currently supported intrinsic value is "unique," which causes a unique number to be generated.

3

Looks for a value in the Context dictionary. First the ContextProfile entry (the CSO) in that dictionary is examined for a matching entry name, and then the Context dictionary is examined for a matching entry name.

NULL or zero (0)

Examines all of the above sources in the order shown, stopping when the first match is found.

If no value can be found in the specified sources, the default value is used.
<variable>_encoding A number indicating the type of encoding, if any, to apply to the value. The options are:

NULL or zero

No encoding.

1

Performs full URL-encoding. An example of when this encoding is required would be a ClickUrl entry passed to the redirector.

2

Limits encoding in which space characters are encoded as plus characters. As an example, this type of encoding is useful in would-be URLs that do not go through the redirector, such as image URLs.

The resulting strings are returned in a SimpleList object assigned to the _formatted key in the Order dictionary.

See Also

CSFLoadAdvertisements

CSFLoadDiscounts


HistoryPenalty

Use this component to apply penalties to content items based on how recently they have been selected.

Although this component appears as HistoryPenalty in the Pipeline Editor, its ProgID is Commerce.CSFHistoryPenalty.

Intended use: Content Selection pipeline, Score stage.

Configuration Values

You can determine how the HistoryPenalty component applies penalties and the range of penalties by setting component properties. Use the following boxes on the History Penalty tab of the Component Properties dialog box to determine this information.

Box | Description
Apply Penalties in the range of | The minimum penalty. The default is 0.9.
To | The maximum penalty. The default is 0.5.
Number of most recent items to penalize | The number of most recent items to penalize. The default is 10.

Penalty values range between zero (0) and one (1).

Values Read

The HistoryPenalty component reads the following values from the indicated dictionary.

Key | Dictionary | Description
_content | Order | A reference to the ContentList object containing the content items that may have penalties applied to their scores. In particular the, item_id and exposure_limit keys are read.
_history | Order | The key containing the history string retrieved by the LoadHistory component.
trace | Context | A Boolean indicating whether score adjustment tracing is enabled. This component will not produce trace strings unless this key is set to True.

Values Written

The HistoryPenalty component writes the following values to the Order dictionary.

Key | Description
_content | A reference to the ContentList object containing the content items that may have their scores subjected to penalties.

Remarks

This component applies penalties to the scores of content items based on how recently the items have been selected, as well as on exposure limits the items may have. Penalties are values between zero (0) and one (1), which are multiplied by the current score of an item. This tends to reduce a score and thus reduces the possibility that the item is selected.

For example, a user could configure the nine most recently selected items to be subject to penalties ranging from 0.90 to 0.1. In this example, the most recently shown item would have its current score multiplied by 0.1, reducing its score and drastically decreasing the likelihood of being selected. The second most recently shown item would have its current score multiplied by 0.2, reducing its score slightly less.

The HistoryPenalty component reads the exposure_limit and item_id keys of each item in the ContentList object referenced by the _content entry. The exposure_limit key is a hard limit on how many times a user is shown an item. Once the limit is met, the score of the item is multiplied by zero (0.0). The adjusted score of an item is assigned to the score field of the content item.


IISAppendToLog

Use this component to record information about content selection results in the QueryString key of the Internet Information Server (IIS) log file.

Although this component appears as IISAppendToLog in the Pipeline Editor, its ProgID is Commerce.CSFIISAppendToLog.

Intended use: Event Processing pipeline, Record stage.

Configuration Values

None.

Values Read

The IISAppendToLog component reads the following values from the indicated dictionaries.

Key | Dictionary | Description
_event | Order | A string containing the name of the event to log.
_eventcount | Order | Optional. A SimpleList object containing the number of events to record for each winning content item. It must contain the same number of elements as the list of winners. If this key is not present, one event will be recorded for each winning content item.
_winnerindexes | Order | A SimpleList object containing the ContentList object indexes of the winning content items. If this key is present, the _winners key should not be present. If both are present, only the _winnerindexes key is used.
_winners | Order | A SimpleList object containing the values from the item_id key of the winning content items. If this entry is present, the _winnerindexes key should not be present. If both are present, only the _winnersindexes key will be used.
ContextProfile.PageGroup | Context | The PageGroup key from the ContentSelection object stored in the dictionary referenced by the ContextProfile object.
PageGroups | Context | A dictionary that maps page group names to IDs from the identity column in the page_groups database table.

Values Written

None for the Order or Context dictionaries.

Remarks

This component appends information about the result of the content selection process in the QueryString key of the IIS log file. This log file can be imported into the Data Warehouse for use with reporting and analysis. This component can only be used in the context of IIS because it uses the AppendToLog method of the IIS Response object.

The logging format is:

&CVET={T=class, property=value, property=value1+value2}

The components and their descriptions for this logging format are listed in the following table.

Component | Description
&CEVT={ | The start of a Commerce event entry in the URI_Query object.
} | The end of a Commerce event in the URI_Query object.
T=class | The event class as defined in the Data Warehouse event class definitions, where class is the name of the corresponding definition. The value of class is always CAMP.
Property=value | A value associated with a particular property. Both property and value strings must be URL-encoded (the space character and the following characters are subject to encoding: { } , = & +).Typical properties include CI (campaign item), CNT (count), and EVT (event).
Property=value1+value2 | Multiple values that are associated with a particular property. Both property and value strings are URL-encoded.
, (comma) | Used as the separator between elements.

The following lines are examples of possible log formatted strings and a description of their contents:

&CEVT={T=CAMP,CI=3,EVT=REQUEST,PG=2}

Campaign event, campaign item 3, event name=REQUEST, page group id =2

&CEVT={T=CAMP,CI=1,CNT=3,EVT=CLICK}

Campaign event, campaign item 1, count=3, event name=CLICK

&CEVT={T=CAMP,CI=3,EVT=DOWNLOAD}

Campaign event, campaign item 3, event name=DOWNLOAD


InitCSFPipeline

Use this component at the beginning of a Content Selection pipeline (CSP) to initialize the values needed in the rest of the pipeline.

Although this component appears as InitCSFPipeline in the Pipeline Editor, its ProgID is Commerce.CSFInitPipeline.

Intended use: Content Selection pipeline, LoadContext stage.

Configuration Values

None.

Values Read

The InitCSFPipeline component reads the following values from the indicated dictionary.

Key | Dictionary | Description
ContextProfile | Context | A reference to the ContentSelector object (CSO). This object can be assigned arbitrary properties and can be used to pass additional information into the pipeline. Two entries are required. For more information, see the Remarks section.

The InitCSFPipeline component reads the following values from the ContextProfile key.

Key | Description
CacheName | The name of the cache. Used to retrieve the cache from the CacheManager object.
CacheManager | A reference to the CacheManager object.
Trace | Optional. A Boolean providing the Trace setting for the entire pipeline. Set in the ContentSelector object. Use tracing only when debugging a pipeline — tracing degrades pipeline performance.
Evaluator | Optional. Reference to an expression evaluator that is copied to the Context dictionary if it is set.
PageGroup | Optional. If present, this key causes the Cache.PageGroup property to be copied into the Context dictionary. This key is also used as a key in the FilterRequire dictionary. For more information, see the Remarks secton.
Size | Optional. If present, this key is created as a key in the FilterRequire dictionary. For more information, see the Remarks secton.
NumRequested | Optional. The NumRequested property of the ContentSelector object: the number of content items requested. This key is copied to the Context dictionary if it is set.
UserProfile | Optional. This key is a reference to a user profile object. This key is copied to the Context dictionary if it is set.
FilterRequire | Optional. This key is copied to the Context dictionary if it is set set. For more information, see the Remarks secton.
FilterExclude | Optional. This key is copied the to Context dictionary if it is set. For more information, see the Remarks secton.

Values Written

The InitCSFPipeline component writes the following values in the indicated dictionaries.

Key | Dictionary | Description
_content | Order | A reference to a newly created and initialized ContentList object.
Performance | Order | A reference to the Performance dictionary, retrieved from the content cache. This key is used by the AdvertisingNeedOfDelivery component later in a pipeline to select content items. See RecordEvent for information about this dictionary.
NumRequested | Order | An optional entry created only if the ContextProfile object has a NumRequested property set. This key indicates the number of content items being requested. The pipeline returns only one content item when this key is not present.
FilterRequire | Order | This key is copied from the ContextProfile.FilterRequire object if present. When present, this key causes the FilterContent component to invoke the Filter method of the ContentList object for each entry in the dictionary. The FilterAction parameter will be set to FILTER_REQUIRE for these invocations. The dictionary has keys that are the names of content fields to search and values that are the values to match.
FilterExclude | Order | This key is copied from the ContextProfile.FilterExclude object if present. When present, this key will cause the FilterContent component to invoke the Filter method of the ContentList object for each entry in the dictionary. The FilterAction parameter is set to FILTER_EXCLUDE for these invocations. The dictionary has keys that are the names of content fields to search and values that are the values to match.
_cache | Context | A reference to the Dictionary object containing the items retrieved from the cache.
Templates | Context | The templates property of the cache. A Dictionary object.
Trace | Context | The trace setting from the ContextProfile object, if any. This value is used as the value for the TraceMode property in the ContentList object, turning tracing either on or off.
Evaluator | Context | The Evaluator object from the ContextProfile object.
RedirectUrl | Context | The Uniform Resource Locator (URL) to which to redirect users.
TargetGroups | Context | The TargetGroups entry from the cache.
PageGroups | Context | The PageGroups entry from the cache.
PageHistory | Context | The PageHistory entry from the ContextProfile object, if any.
UserProfile | Context | A reference to the user profile copied from the ContentSelector object (CSO).

Remarks

The InitCSFPipeline component is responsible for setting up numerous values in the Order and Context dictionaries for use by subsequent components in a Content Selection pipeline. In addition, the component automatically generates some content filters and allows you to use FilterInclude, FilterExclude, and PageGroups dictionaries to customize filtering without writing new pipeline components.

In general, the values the InitCSFPipeline component sets up in the Order and Context dictionaries are derived from the ContextProfile entry in the Context dictionary, or from the Cache dictionary retrieved from the CacheManager object. The ContextProfile entry in the Order dictionary contains a reference to the ContentSelector object, which provides much of the information required by the pipeline.

Also, by moving the various values from the ContextProfile to the Order and Context dictionary objects, the pipeline components farther down the pipeline have much more efficient access to this data.

Perhaps the most important task performed by the InitCSFPipeline component is the creation and initialization of the ContentList object. It is within this object that content scoring is tracked during execution of the pipeline.

The InitCSFPipeline component creates the ContentList object by following these steps:

  1. Retrieve the name of the cache from ContextProfile.

  2. Retrieve the CacheManager object from ContextProfile.CacheManager property.

  3. Get the cache from the CacheManager object.

  4. Obtain the ContentListFactory object from the cache.

  5. Call the CreateNewContentList method of the ContentListFactory object and assign the new content list to the _content key in the Order dictionary.

The FilterRequire and FilterExclude dictionaries allow custom filters to be set up without writing new pipeline components. For ease of use, the InitCSFPipeline component automatically sets up some commonly used filters for page group, ad size, and (for Discount Content Selection pipelines) NoDisplay templates. If no FilterRequire or FilterExclude dictionary is explicitly passed and one of these filters is applicable, the filter dictionary will automatically be created. If the InitCSFPipeline component detects existing filters for these keys already in a filter dictionary, it will not modify the filter.

The InitCSFPipeline component creates a filter for PageGroup (unless one already exists). This filter contains the special PageGroup "All" (Run of Site), which allows any content marked to run on the whole site to pass, and it also contains the value of the PageGroup property set on the ContentSelector object making the GetContent call (if set).

This component breaks the rule of never writing data to the Context dictionary. Nevertheless, the convention should be observed as it is by the vast majority of pipeline components.

See Also

ContentList.Filter


ItemPromo

Use this component to apply a promotional price adjustment to an item on the order form.

Note

  • The ItemPromo component should not be used for future development. The discount features of the Content Selection pipeline provide a more powerful and general mechanism for applying product discounts. For more information, see Discount Objects.

Use this component to apply a promotional price adjustment to an item on the items list for the order form. The ItemPromo component first determines whether the current date falls within the time period specified by the Start Date and End Date boxes. If it does, then the component evaluates the item to determine if it meets the conditions of the promotion (specified by the combination of the Condition Order Key, Condition Operator, and Condition Value boxes). If it does, then the ItemPromo component applies the specified discount and writes the new value to the _iadjust_currentprice key on the item order form, provided that the _iadjust_currentprice key has not been initialized by a previously run component.

Intended use: Order Processing pipeline, Adjust Price stage.

Configuration Values

You can determine the discount the ItemPromo component applies and the discount type by setting component properties. Use the following boxes on the Item Promo tab of the Component Properties dialog box to determine this information.

Box | Description
Condition Order Key | The name of the item attribute that identifies the condition to meet for a promotion to be applied (for example, _product_type).
Condition Operator | An operator (<, <=, =, >=, >, or <>) used to compare the value of the Condition Order Key box with the value in the Condition Value box. The default is the equal (=) operator.
Condition Value | The product or products that must be purchased before the promotion is applied. The value in this box is compared with the value in the column name specified in the Condition Order Key box. This value can be text, an integer, or a floating-point number.
Discount Type | Shows whether the discount is a percentage-off discount or a price discount. The default is percentage-off discount.
Discount Value | The discount amount. This must be an integer value; floating-point numbers (for example, .10) are not accepted. The default is zero (0).
Start Date | Optional. The date the promotion begins, starting at 12:00:01 a.m.
End Date | Optional. The date the promotion ends, ending at 12:00:01 a.m. For example, if you want the last day of a promotion to be 3/31, you would specify an End Date of 4/1.

Values Read

The ItemPromo component reads the following values from the indicated dictionaries.

Key | Dictionary | Description
item._iadjust_regularprice | Order | The regular price of the item.
item._iadjust_currentprice | Order | The current price of the item.
item.<name> | Order | Dynamic. The key specified in the Condition Order Key box.

Values Written

The ItemPromo component writes the following values to the Order dictionary.

Key | Description
item._iadjust_currentprice | The current price of the item with the discount applied.

Remarks

The ItemPromo component applies a promotional price adjustment to an item in the item list in the order form. The component performs the following steps in testing and applying the discount:

  1. The ItemPromo component first determines whether the current date falls within the period specified by the values in the Start Date and End Date boxes.

  2. If the current date is in range, the component evaluates the item to determine if it meets the condition for the promotion. The condition is specified by the combination of the values in the Condition Order Key, Condition Operator, and Condition Value boxes.

  3. If the item meets the condition, the ItemPromo component applies the specified discount and writes the new value to the _iadjust_currentprice key of the item in the order form, provided that the _iadjust_currentprice key has not been initialized by a previously run component.

The promotional comparisons specified in the Conditional Value box are case-sensitive. For example, a product ID of AW13-200 will be interpreted differently than a product ID of aw13-200.

In addition, because the Start Date and End Date boxes for a promotion specify midnight, the value in the End Date box excludes the day specified. For example, if you want the last day of a promotion to be 3/31, be sure to specify that the promotion ends on 4/1.


LinearHandling

Use this component to set the handling total on an order by multiplying a field on the order form by a fixed rate.

Note

  • The LinearHandling component is for backward compatibility only and does not support the new, extended Currency datatype.

Intended use: Order Processing pipeline, Handling stage.

Configuration Values

You can determine how the LinearHandling component applies the handling rate and the rate itself by setting component properties. Use the following boxes on the Linear Handling tab of the Component Properties dialog box to determine this information.

Box | Description
Apply when Determines when to apply the handling charge. The values are:

Always

Default. The handling charge is always applied to the order.

Equal to method

Specifies that the handling cost should be applied when the value of shipping_method key in the Order dictionary is the same as the string specified as the value for the Method box.

Has any value

Specifies that the handling charge is applied when the shipping_method key of the order has any non-null value.
Method | The shipping method to match against the value of the shipping_method key in the Order dictionary. Used when the value in the Apply when box is set to Equal to method.
Basis Item Key | The property of the item to use in computing the handling charge. Defaults to the sum.quantity key.
Rate | The handling rate, which is an integer value.

Values Read

The LinearHandling component reads the following value from the indicated dictionary.

Key | Dictionary | Description
item.sum_quantity | Order | Dynamic. Default shown. The property of the item to use in computing the handling charge. The key name is determined by the value in the Basis Item Key configuration box.

Values Written

The LinearHandling component writes the following value to the Order dictionary.

Key | Description
_handling_total | The handling total for the entire order.

Remarks

The LinearHandling component computes the handling charge by multiplying the value specified in the Rate box by the sum of the property specified for the Basis Item Key box. For example, you might base the linear handling charge on the quantity of the items, and the value in the Basis Item Key box might be sum.quantity key. If the order contains two items, one item with a quantity of four and the other item with a quantity of two, then the basis sum is six. The component calculates the handling charge by multiplying the value in the Rate box by six.

For more general information about basis item keys, see Specifying the Basis Item Key.

See Also

Specifying the Basis Item Key


LinearShipping

Use this component to calculate the shipping total on an order form using a fixed rate.

Note

  • The LinearShipping component is for backward compatibility only and does not support the new, extended Currency datatype.

Intended use: Order Processing pipeline, Shipping stage.

Configuration Values

You can determine how the LinearShipping component applies the shipping rate and the rate itself by setting component properties. Use the following boxes on the Linear Shipping tab of the Component Properties dialog box to determine this information.

Box | Description
Apply when Determines when to apply the shipping charge. The values are:

Always

Default. Specifies that the shipping charge is always applied to the order.

Equal to method

Specifies that the shipping cost should be applied when the value of the shipping_method key in the Order dictionary is the same as the string value specified in the Method box.

Has any value

Specifies that the shipping cost is applied when the shipping_method key of the order has any non-null value.
Method | The shipping method to match against the value of the shipping_method key in the Order dictionary. Used when the value in the Apply when box is set to Equal to method box.
Basis Item Key | The item property to use in computing the shipping charge. Defaults to the sum.quantity key.
Rate | The handling rate, which is an integer value.

Enter the value in the same currency unit in which prices are stored in the database.

Values Read

The LinearShipping component reads the following value from the indicated dictionary.

Key | Dictionary | Description
item.sum_quantity | Order | Dynamic. Default shown. The property of the item to use in computing the shipping charge. The key name is determined by the Basis Item Key configuration box.

Values Written

The LinearShipping component writes the following value to the Order dictionary.

Key | Description
_shipping_total | The shipping total for the entire order.

Remarks

The LinearShipping component computes the shipping charge by multiplying the value specified in the Rate box by the sum of the property specified in the Basis Item Key box. For example, you might base the linear shipping charge on the quantity of the items, and the value in the Basis Item Key box might be the sum.quantity key. If the order contains two items, one item with a quantity of four and the other item with a quantity of two, then the basis sum is six. The component calculates the handling charge by multiplying the value in the Rate box by six.

For more general information about basis item keys, see Specifying the Basis Item Key.

See Also

Specifying the Basis Item Key


LoadHistory

Use this component to retrieve a history string from a user profile, an item in the Active Server Pages (ASP) session collection, or a cookie.

Although the component appears as LoadHistory in the Pipeline Editor, its ProgID is Commerce.CSFLoadHistory.

Intended use: Content Selection pipeline, Load Context stage.

Configuration Values

You can determine where the LoadHistory component retrieves the history string by setting component properties. Use the following boxes on the Load History tab of the Component Properties dialog box to determine this information. You must choose one of the following options.

Box | Description
User Profile Object | The property in the user profile object containing the history string.
ASP Session Collection | The key in the Session object containing the history string. Requires that the component be configured with the proper key and that the pipeline be executing in the Internet Information Server (IIS) context.
HTTP Cookie The key in the Cookies object containing the history string. Requires that the component be configured with the proper key and that the pipeline be executing in the IIS context.

Note

  • The cookie is a session cookie and will not persist across sessions.

The default user object profile that ships with Commerce Server 2000 contains a property for the history string: Advertising Info.Campaign History. This is the only method that persists the history string across user sessions on the site (required to support ExposureLimit data member properly).

Values Read

The LoadHistory component reads the following values from the indicated dictionaries.

Key | Dictionary | Description
UserProfile | Context | A reference to the ProfileObject object for this user. This entry is optional, and is required only when the User Profile Object option is used.

Values Written

The LoadHistory component writes the following value to the Order dictionary.

Key | Description
_history | The history string, retrieved from one of the sources, as configured in the property page of the component.

Remarks

This component makes the history string easily accessible to other pipeline components by hiding its source.

If the User Profile Object option is chosen as the source for the history string, the property page requires the name of the property in the User Profile Object in which the history string is maintained.

When using the User Profile Object option, it is possible to use either a field that is mapped to a data column in a table, or a field that is not mapped. If the field is not mapped, the history string is persisted only for the duration of the user session and is later timed out of the profile cache. This method is more efficient than using the mapped method, but the mapped method allows the history string to be persisted across sessions. The unmapped option does not allow you to load balance Domain Name Server (DNS) network requests by sending the incoming requests to the next server in a list (round-robin load balancing).


LocalInventory

Use this component to set the number of items back ordered on the order form.

Intended use: Order Processing pipeline, Inventory stage.

Configuration Values

You can determine how the LocalInventory component deals with back orders by setting component properties. Use the following boxes on the Local Inventory tab of the Component Properties dialog box to determine this information.

Box | Description
Disallow Backorder | If selected, indicates that back orders are not permitted. The component adds a message to the _Purchase_Errors list if there is a back order.

Values Read

The LocalInventory component reads the following values from the indicated dictionaries.

Key | Dictionary | Description
item._product_local_inventory | Order | The local inventory for this stockkeeping unit (SKU).
item.quantity | Order | The quantity of the item ordered.
item.sku | Order | A unique identifier for the product.
MessageManager | Context | Dynamic. This key is used only if the Disallow Backorder option is selected. This key is a reference to a MessageManager object, and is used to retrieve the out of stock constant (pur_out_of_stock) in case of an error.

Values Written

The LocalInventory component writes the following values to the Order dictionary.

Key | Description
item._inventory_backorder | The amount back ordered to fulfill the order for this item.
_Purchase_Errors | Dynamic. Error messages are written to this SimpleList object only if the Disallow Backorder option is selected.

Errors

The component writes error messages to the _Purchase_Errors collection. The component uses a MessageManager object to retrieve user warning message text.

Constant | Condition
pur_out_of_stock | An item in the order is out of stock.

Remarks

The LocalInventory component sets the value of the _inventory_backorder key on the order form to the number of items back ordered. The LocalInventory component takes the sum of the items for each SKU in the order, and then compares this number with the value of the _product_local_inventory key. If the value of the _product_local_inventory key is less than the number of items ordered, the component sets the value of the _inventory_backorder key to the difference.

The value of the item._product_local_inventory key is set from a database table by a components such as QueryProdInfoADO or QueryCatalogInfo.

See Also

FlagInventory

QueryCatalogInfo

QueryProdInfoADO


MakePO

Use this component to produce a string by merging information from the order form with a template, such as creating a purchase order formatted from a purchase order template.

Configuration Values

You can determine how the MakePO component formats the purchase order and where it is written by setting component properties. Use the following boxes on the Make PO tab of the Component Properties dialog box to determine this information.

Box | Description
Template File Name | The name of the file providing the template for the purchase order. The template is usually a Microsoft Visual Basic Scripting Edition (VBScript) file in a special format described below.
Script language for the template | The programming language used in the template. The default is VBScript.
Output Property Name | The name of a field in the order form or Transport dictionary to which the component writes the PO. The default is _po_text.
Child Object Name | Applies only when the Use Child Object option is set. A child object is an object that is referenced by a key in the Transport dictionary that is passed into the pipeline. The Child Object Name box specifies the key. In a Commerce Interchange pipeline, the order form (business data object) from which the MakePO component generates the purchase order is a child object.
Use Child Object | Determines the source from which the component reads the purchase order information. Select this option when using a Commerce Interchange pipeline so that the component reads this information from the business data object specified by the value in the Child Object Name box. Clear this check box when using an Order Processing pipeline so that the component reads this information from the order form passed directly into the pipeline.

Values Read

The MakePO component reads the file indicated in the Template File Name box. The script can read anything available to it.

Values Written

The MakePO component assigns the value to the key in the Transport dictionary indicated in the Output Property Name box. The script may also be written to write out additional values.

Remarks

The MakePO component can be used to dynamically generate a text entry on the OrderForm object (usually a purchase order). The entry is generated from a template file similar to an Active Server Pages (ASP) page. Like an ASP page, a MakePO template contains plain text interspersed with special tags containing script code. From within script, output can be done using PageGen.Print expression, or <%% = expression %%> similar to the ASP shortcut for Response.Write. The script language is configurable in the property page.

From within the MakePO template, the business object (OrderForm object, dictionary, or child object) is exposed as an object with the name Items. The library for the selected scripting language is also extended to include the members of this object as built-in properties, so that referring to the entries of the business object using the Items.xxx notation is possible. For this reason, it is best to declare any temporary variables so that they are not saved in the business object.

The following segment is an example from a template:

Item Class:<%%= item.partclasscode %%>
#:<%%= item.partnumber %%>
Qty:<%%= item.quantity %%>
Cost:<%%= item.[_display_list_price] %%>
Unit Code:<%%= item.unitcode %%>

The PO generated by the MakePO component can be saved to a file using the POtoFile component.

The MakePO component cannot output variant subtype VT_DECIMAL. Any usage of decimal or currency in the MakePO component must be wrapped with a call to the CStr method, which properly coerces the value to a string. For example:

Requisition # <%% = CStr(RequisitionID) %%>

Programmatic Use

To use this component outside of a pipeline, you must configure it by assigning values to keys in the Configuration dictionary. The keys correspond to the indicated boxes on the Component Properties dialog box.

Key | Box | Description
TemplateFileName | Template File Name | String.
TemplateScriptLanguage | Script language for the template | String.
OutPropName | Output Property Name | String.
ChildObjectName | Child Object Name | String
UseChildObject | Use Chile Object | Numeric. 0 for False, 1 for True.

For more information about using pipeline components outside of pipelines, see MicroPipe Object.

See Also

MicroPipe Object

POtoFile


MoneyConverter

Use this component to convert OrderForm object keys and values from integers to the new currency type, or from the new currency type to integers.

Intended use: Order Processing pipeline, any stage.

Configuration Values

You can determine which conversion the MoneyConverter component performs as well as the fields converted by setting component properties. Use the following boxes on the Convert Money tab of the Component Properties dialog box to determine this information.

Box | Description
Convert currency to int | Converts currency values to integer values.
Convert int to currency | Converts integer values to currency values.
Currency Fields | This box contains a space-separated list of the currency fields. The integer fields have the same name but without the cy_ prefix. Prefix item-level fields with item. and order level elements with order.. See the Remarks section for more information.

Values Read

The fields specified in the Currency Fields box.

Values Written

The fields specified in the Currency Fields box.

Remarks

Use the MoneyConverter component in pipeline stages containing both Site Server 3.0 Commerce Edition and Commerce Server 2000 pipeline components using currency representations.

If a pipeline stage contains only Site Server 3.0 Commerce Edition or only Commerce Server 2000 objects, you do not need to use the MoneyConverter component. The various required components (RequiredItemPrice, for example) automatically perform currency and integer conversions at the end of a pipeline stage.

When converting values, the component gets the value of the key, converts it, and assigns it to the key of the other type. For example, suppose that you are converting the old integer currency value item._oadjust_adjustedprice. The MoneyConverter component gets the value from this key, converts it to the new currency data type, and assigns the converted value to the item._cy_oadjust_adjustedprice key. Values may be rounded during conversion. For more information about rounding, see Currency Enhancements.

The only difference between the keys is the cy_ in the name of the key holding the currency value. The currency key that is specified in the Component Properties dialog box regardless of the direction of the conversion.

See Also

DataFunctions Object


OrderDiscount

Use this component to apply discounts scheduled in the Campaign Manager module in Commerce Server Business Desk to the shopping basket.

Intended use: Order Processing pipeline, Order Adjust Price stage.

Configuration Values

None.

Values Read

The OrderDiscount component reads the following values from the indicated dictionaries.

Key | Dictionary | Description
item._cy_iadjust_currentprice | Order | The current price of an item. May have been adjusted in the Item Adjust Price stage.
item.quantity | Order | The total quantity of an item.
item._cy_oadjust_adjustedprice | Order | Optional. The total cost of the item before discounts.
item._n_unadjusted | Order | Optional. The quantity of this item that have not been discounted.
item._product_* | Order | The product properties for each item. The column name is appended to form the key name. For more information, see the Remarkssection.
item.discounts_applied | Order | Optional. A dictionary containing the IDs of the discounts that applied to this item. Keys are the IDs; values are the date-time stamps of the discounts.
currency_decimal_places | Order | Optional. The number of the decimal places in the current currency. The default is two (2).
discounts_clicked | Order | Optional. The campaign item IDs of the click-required discounts that have been clicked.
Evaluator | Context | A reference to an ExpressionEval object.
CacheManager | Context | A reference to the CacheManager object to use for retrieving the discount schedule.
CacheName | Context | String. The name of the cache.
MessageManager | Context | A reference to a MessageManager object that uses the discount removed error constant (pur_discount_removed) and the discount changed error constant (pur_discount_changed) to retrieve error messages.
Language | Context | Optional. The language for messages used by the MessageManager object.
UserProfile | Context | Optional. A reference to a user profile object.
ContextProfile | Context | Optional. A reference to an ExprEvalContext (expression context profile) object for use with the expression evaluator.
SiteName | Context | Optional. The site name, used in error messages.

Values Written

The OrderDiscount component writes the following values to the Order dictionary.

Key | Description
_discounts | A ContentList object containing the schedule of discounts. For the structure of the ContentList object, see CSFLoadDiscounts.
_winners | This key contains the campaign item IDs of all discounts applied to the basket.
_event | This key contains the name of the event to record, which should always be set to SOLD. This value is used by the RecordEvent and IISAppendToLog components.
item._cy_oadjust_adjustedprice | Optional. The total price of the items that have had discounts applied.
item._n_unadjusted | Optional. The number of items whose price remains unadjusted after discounts are applied.
item.discounts_applied | Optional. A dictionary containing the campaign item IDs of the discounts that applied to this item. The keys are the IDs; the values are the date-time stamps of the discounts.
_discounts_removed | Optional. A SimpleList object of campaign item IDs of discounts that no longer apply since the last time the pipeline was run. This key is written only if some discounts no longer apply.
_discounts_changed | Optional. A SimpleList object of campaign item IDs of discounts that have changed since the last time the pipeline was run. This key is written only if some discounts have changed.
_Basket_Errors | Error messages are written to this SimpleList object.
_<special_offer_type>_type Optional. The type of an order-level discount, if one applies. Another component in the pipeline (such as ShippingDiscountAdjust) applies the discount. The key name is formed from the string stored in the special_offer_type key in the ContentList object. Possible values are:
  • 1 (money discount)

  • 2 (percentage discount)

Free shipping is an example of an order-level discount.
_cy_<special_offer_type>_value | Optional. The value of an order-level discount, if one applies. Another component in the pipeline (such as ShippingDiscountAdjust) applies the discount. This key is used only for custom discounts applied outside of the pipeline. The key name is formed from the string stored in the u_special_offer_type key in the discount database. The value of the discount comes from the offer_value field in the ContentList object. Free shipping is an example of an order-level discount.
_cy_<special_offer_type>_description | Optional. String. The description of an order-level discount if one applies. This key may be used to display when the discount applies somewhere on the page. The value comes from the description field in the ContentList object.

Errors

The component writes error messages to the _Basket_Errors collection. The component uses a MessageManager object to retrieve user warning message text.

Constant | Condition
pur_discount_removed | A discount no longer applies since the pipeline was last run.
pur_discount_changed | A discount has changed since the pipeline was last run.

Remarks

The OrderDiscount component applies discounts to the shopping basket of a user. The discounts are scheduled through the Campaign Manager module in Commerce Server Business Desk. Each discount is a campaign item and has a unique campaign item ID.

You can adjust the scores of discounts that the OrderDiscount component applies by using the ScoreDiscounts component in a Content Selection pipeline. The ScoreDiscounts component adjusts the scores of discounts and saves them in the ContentList object held by the CacheManager object. That ContentList object would then be used by the OrderDiscount component in another pipeline.

The OrderDiscount component rounds at the line item level — if more than one discount applies to a line item, the discounts are combined before rounding is done. Currencies with four decimal places of precision are the exception. In this case, values are truncated to four decimal places as discounts are combined.

For a detailed discussion about how discounts are selected and applied, see Discount Objects.

The _winners and _event keys are used to record events for tracking in the campaign system and are imported into the Data Warehouse for reporting.

See Also

Discount Objects

CSFLoadDiscounts

ScoreDiscounts


POtoFile

Use this component to send a purchase order or other textual data to a file.

Intended use: Order Processing pipeline, Purchase Order Submit or Accept stage.

Configuration Values

You can determine where the POtoFile component retrieves the document and where it writes the result by setting component properties. Use the following boxes on the PO to File tab of the Component Properties dialog box to determine this information.

Box | Description
Source Field Name | The name of the field on the order from which the component reads the purchase order data. The default is po_text.
File Name | The full path to the file the component writes the purchase order to. To locate the file, click Browse.
File named in field | The name of the field in the OrderForm object whose value is the name of the file the component writes the purchase order to; for example, save_filename.
Temporary file, name saved in field | Specifies that the component should save the text to a temporary file, and then save the name of the temporary file in the field identified in the text box. For example, saved_filename.
Append to file instead of overwriting file | When checked, indicates that the text should be appended to the indicated file. Otherwise, the file is overwritten if it exists.

Values Read

The POtoFile component reads the value specified by the key in the Order dictionary indicated in the Source Field Name box.

Values Written

None.

Remarks

The purchase order is usually the output of the MakePO component.

The File Name, File named in field, and Temporary file boxes are mutually exclusive; that is, you can select only one of the three.

Programmatic Use

To use this component outside of a pipeline, you must configure it by assigning values to keys in the Configuration dictionary. The keys correspond to the indicated boxes in the Component Properties dialog box.

Key | Box | Description
SourceFieldName | Source Field Name | String.
SaveMode | N/A | Numeric. 0 for file name given; 1 for file name comes from SourceFieldName.
FixedSaveFileName | File Name | String.
SaveFileFieldName | File name in field | String.
TempFileFieldName | Temporary file, name saved in field | String.
IsAppendToFile | Append to file instead of overwriting file | Numeric. 0 for overwriting; 1 to append.

For more information about using pipeline components outside of pipelines, see MicroPipe Object.

See Also

MakePO


QueryCatalogInfo

Use this component to retrieve catalog information for every item in the order form.

Note

  • This component replaces the older QueryProdInfoADO component. The QueryCatalogInfo component works with the new Commerce Server 2000 catalog structure rather than performing product table lookups.

Intended use: Order Processing pipeline, Product Info stage.

Configuration Values

You can determine which product properties the QueryCatalogInfo component retrieves by setting component properties. Use the following box on the Query Catalog Info tab of the Component Properties dialog box to determine this information.

Box | Description
Columns | A comma-separated list of product properties to retrieve from the catalog system. Leave blank to retrieve all product properties.

Values Read

The QueryCatalogInfo component reads the following values from the indicated dictionary.

Key | Dictionary | Description
CacheManager | Context | A reference to a CacheManager object.
CatalogManager | Context | A reference to a CatalogManager object.
item.product_catalog | Context | String. The catalog containing the item.
item.product_id | Context | String. The product identifier.
item.product_variant_id | Context | Optional. String. An additional identifier used to distinguish variants of a particular product such as different colors of an item.

Values Written

The QueryCatalogInfo component writes the following values to the Order dictionary.

Key | Description
item._product_* | Product properties for each item. The column name is appended to form the key name. For more information, see the Remarks section.
item.delete | A flag indicating the item should be deleted from the order. For more information, see the Remarks section.

Remarks

The QueryCatalogInfo component retrieves product information from the catalog system for every item in the order. It adds the retrieved information to each Item dictionary in the order form.

The Columns box contains a comma-separated list of properties to retrieve from the catalog. If the Columns box is left blank, the QueryCatalogInfo component retrieves all product properties related to each item.

Items are identified by a combination of the product_catalog, product_id, and product_variant_id keys. The product_variant_id key is required only if the product is a variant, such a particular color of an item that comes in multiple colors.

If no data is found for an item, the QueryCatalogInfo component marks the item for deletion by creating a key in the Item dictionary. The key, delete, is assigned a value of one (1). The RequiredProdInfo component checks for this flag and deletes the item if the key is found. Typically, this deletion occurs when an item in the basket is removed from a catalog.

If data for an item is found, the QueryCatalogInfo component writes an entry to the corresponding Item dictionary for each property specified in the Columns box (or for every property if nothing was specified in the Columns box). The name of the entry is the prefix _product_ followed by the property name. For example, a product property named "weight", would be stored as _product_weight. The value of the entry is set to the corresponding data from the catalog system.

The QueryCatalogInfo component requires a CacheManager object with a QueryCatalogInfoCache datastructure in its PipeContext Dictionary. The QueryCatalogInfo component uses this data structure to cache the product and category information it applies to line items

The following code is used to setup the cache in the global.asa file.

    ' Initialize dictQCICacheConfig
    Set dictQCICacheConfig = Server.CreateObject("Commerce.Dictionary")
    dictQCICacheConfig("ConnectionString") _
     = _dictConfig.s_TransactionConfigConnectionString
    dictQCICacheConfig("CacheSize") = 10000
    dictQCICacheConfig("TableName") = "CatalogCache_Virtual_Directory"
    dictQCICacheConfig("CacheName") = "CatalogCache"
    dictQCICacheConfig("AppUrl") = sMachineBaseURL

    ' Configure CacheManager For QueryCatalogInfoCache
    oCacheManager.RefreshInterval("QueryCatalogInfoCache") = 60 * 60
    oCacheManager.RetryInterval("QueryCatalogInfoCache") = 5 * 60
    oCacheManager.CacheObjectProgId("QueryCatalogInfoCache") _
     = "Commerce.LRUCache"
    oCacheManager.LoaderProgId("QueryCatalogInfoCache") _
     = "Commerce.LRUCacheFlush"
    Set oCacheManager.LoaderConfig("QueryCatalogInfoCache") _
     = dictQCICacheConfig

See Also

RequiredProdInfo


QueryProdInfoADO

Use this component to retrieve product information from a database.

Note

  • Use the new QueryCatalogInfo for new applications to take advantage of the new Commerce Server 2000 catalog API.

Intended use: Order Processing pipeline, Product Info stage.

Configuration Values

You can determine the query the QueryProdInfoADO component runs by setting component properties. Use the following boxes on the Query Prod Info (ADO) tab of the Component Properties dialog box to determine this information.

Box | Description
Connection String | The connection string to connect to the database. This may be a full connection string or a name in a connection map. If blank, the default connection string is passed through.
Query | The full SQL text of the query this component will execute, or the name of a query whose full SQL text is defined in the Global.asa file in the QueryMap key.
Parameter List | A space-separated list of the parameters to pass to the query. The stockkeeping unit (SKU) for an item (item.sku) is commonly used.

Values Read

The QueryProdInfoADO component reads the following values from the indicated dictionaries.

Key | Dictionary | Description
DefaultConnectionString | Context | Optional. The key in the Application dictionary containing the default query string.
ConnectionStringMap | Context | Optional. The map in which to look up the name of a mapped connection string.
QueryMap | Context | Optional. A reference to a dictionary containing a query map.

Values Written

The QueryProdInfoADO component writes the following values to the Order dictionary.

Key | Description
item._product_* | The product information for each SKU found, added to the Item dictionary in the Order dictionary. The column name is appended to form the key name.
item.delete | A deletion flag, set to one (1) for an item if it is not found. The item will be deleted from the order.

Remarks

The QueryProdInfoADO component runs a database query to retrieve data about products on the order form. If unique data for the specified query is found, then for each column retrieved by the query, the component writes the data into the item._product_columnvalue keys in the Item dictionary of the order form. This makes product information available to components later in the pipeline.

The connection string must include either the full connection string (the data source name (DSN), database login ID, and database password) or the name of a named connection stored in the connection map.

If you add new columns to the product database table, and if this information is needed by any component in the pipeline, then you must add the column to the query used by the QueryProdInfoADO component.

If data for the specified SKU is found, then for each column retrieved by the query, the QueryProdInfoADO component writes a key and value pair to the Item dictionary. The key consists of the prefix _product_, followed by the column name. Thus, for example, the data in a table column named col would be placed in the value of item._product_col. Finally, the QueryProdInfoADO component initializes the value to contain the data stored in the appropriate column.

If no rows or more than one row are returned by the query, the QueryProdInfoADO component writes a key named delete to the Item dictionary, initializes the delete item to 1 (marking it for deletion) and moves on to the next item. Items marked for deletion are removed from the order form, typically by the RequiredProdInfo component.


RecordEvent

Use this component to record event delta counts for the selected content items (the winners) in the Performance dictionary.

Although this component appears as RecordEvent in the Pipeline Editor, its ProgID is Commerce.CSFRecordEvent.

Intended use: Content Selection or Event Processing pipeline, Record stage; Order Processing pipeline, Receipt stage.

Configuration Values

None.

Values Read

The RecordEvent component reads the following values from the indicated dictionaries.

Key | Dictionary | Description
_event | Order | A string containing the name of the event to record.
_eventcount | Order | Optional. A SimpleList object containing the number of events to record for each winning content item. It must contain the same number of elements as the _winners list. One event is recorded for each winning item if this key is not present.
_winnerindexes | Order | A SimpleList object containing the ContentList object indexes of the winning content items. If this key is present, the _winners key should not be present. If both are present, only this key is used.
_winners | Order | A SimpleList object containing values from the item_id keys of the selected (winning) content items. If this key is present, the _winnerindexes key should not be present. If both are present, only the _winnerindexes key is used.
_performance | Order | Specifically, the previous event delta count for the various content items.
_content.item_id | Order | The item_id key for the various content items contained in the ContentList referenced by _content. If the _content key is present, the referenced ContentList object must have a column named item_id.

Values Written

The RecordEvent component writes the following values to the Order dictionary.

Key | Description
_performance | The Performance dictionary. This key will contain the new event delta counts for the various content items.
_content.invalid_nod | A Boolean flag for each item in the ContentList object. Set this key to True if the item needs to have the Need of Delivery (NOD) re-calculated.

Remarks

The following are the names of the pre-defined events for campaigns:

  • REQUEST. A content request event.

  • CLICK. A click event for an ad or a promotion.

  • DOWNLOAD. A download of a GIF image or other advertising asset from the Web server.

  • SOLD. An item sold event, such as for a promotion or bounty ad.

You can record custom events by adding custom event names to the event_type table in your campaigns database.

This component flags whether or not the NOD values of the winning content items need to be re-calculated. The flag is set to True if the Item dictionary has a NOD key and if the event name matches the type of event the item is scheduled by.

The NOD values can be recomputed in the absence of a ContentList object (when the _Content key is not present) if the _winners key is passed instead of the _winnerindexes key.

The Performance dictionary contains a subdictionary for each content item for which an event has occurred, keyed by the item_id key. Each subdictionary maps event names to a count of the number of new occurrences of that event. Periodically, the total in the database for each event for each content item will be incremented by this amount. The RecordEvent component is responsible for creating keys in these dictionaries as needed and incrementing the corresponding values. The WriteEvents cache component is responsible for recording the increments in the running totals in the database.


RecordHistory

Use this component to record the identifiers of the winning content items in the history list string.

Although the component appears as RecordHistory in the Pipeline Editor, its ProgID is Commerce.CSFRecordHistory.

Intended use: Content Selection pipeline, Record stage.

Configuration Values

You can determine how many items the RecordHistory component saves in the string by setting component properties. Use the following box on the Record History tab of the Component Properties dialog box to determine this information.

Box | Description
Maximum number of items to store in history string | Numeric. The maximum number of items saved in the history string. The default is 35.

Values Read

The RecordHistory component reads the following values from the indicated dictionaries.

Key | Dictionary | Description
_history | Order | The history string retrieved by the LoadHistory component.
_winnerindexes | Order | A SimpleList object containing the ContentList object indexes of the winning content items. If this entry is present, the _winners key should not be present. If both are present, only this key is used.
_winners | Order | A SimpleList object containing the values from the item_id keys of the winning content items. If this entry is present, the _winnerindexes key should not be present. If both are present, only the _winnerindexes key is used.
_content | Order | The item_id key for the various content items contained in the ContentList object referenced by the _content key. The item_id key is automatically looked up if the _winnersindexes key is passed instead of the _winners key.

Values Written

The RecordHistory component writes the following values to the Order dictionary.

Key | Description
_history | The updated history list string.

Remarks

The RecordHistory component is responsible for managing the size of the history list and truncates it when necessary. The component removes the oldest entries from the string when it exceeds the maximum length.

The property page for the RecordHistory component allows the maximum number of entries in the history to be configured. This component trims the least recent history list entries, as necessary, to assure that this limit is not exceeded.

See Also

ContentList Object

SimpleList Object


RequiredHandlingCy, RequiredHandling

Use this component to verify that the handling total is present in the order.

The RequiredHandling component is for backward compatibility only. The RequiredHandlingCy component operates in both Site Server 3.0 Commerce Edition compatibility mode and in Commerce Server 2000 mode pipelines. For more information, see Currency Enhancements.

Intended use: Order Processing pipeline, Handling stage.

Configuration Values

None.

Values Read

The RequiredHandlingCy component reads the following values from the indicated dictionaries. The RequiredHandling component reads the same key but without cy_.

Key | Dictionary | Description
_cy_handling_total | Order | The total cost for handling the order.
MessageManager | Context | A reference to a MessageManager object. This key is used to retrieve the bad-handling total constant (pur_badhandling) in case of an error.

Values Written

The RequiredHandlingCy and RequiredHandling components write the following value to the Order dictionary.

Key | Description
_Purchase_Errors | Error messages are written to this SimpleList object.

Errors

The RequiredHandlingCy and RequiredHandling components return error level 2 (OPPERRORLEV_WARN) when the handling total is not in the order form. Other errors return error level 3 (OPPERRORLEV_FAIL).

The components write error messages to the _Purchase_Errors collection. The components use a MessageManager object to retrieve user warning message text.

Constant | Condition
pur_badhandling | The handling total is not in the order form.

Remarks

The RequiredHandlingCy and RequiredHandling components verify that the order._handling_total key is present.

See Also

MessageManager Object


RequiredItemAdjustPriceCy, RequiredItemAdjustPrice

Use these components to ensure that the current price for each item in the order is set and that it has not been changed.

The RequiredItemAdjustPrice component is for backward compatibility only. The RequiredItemAdjustPriceCy component operates in both Site Server 3.0 Commerce Edition compatibility mode and in Commerce Server 2000 mode pipelines. For more information, see Currency Enhancements.

Intended use: Order Processing pipeline, Item Adjust Price stage.

Configuration Values

None.

Values Read

The RequiredItemAdjustPriceCy component reads the following values from the indicated dictionaries. The RequiredItemAdjustPrice component reads the same key but without cy_.

Key | Dictionary | Description
item._cy_iadjust_currentprice | Order | Reads the current price of each item in the items collection in the OrderForm object.
item._cy_iadjust_regularprice | Order | Reads the regular price of each item in the items collection in the OrderForm object.
item.cy_placed_price | Order | Reads the placed price of each item in the items collection in the OrderForm object. For more information, see the Remarks section.
MessageManager | Order | A reference to a MessageManager object. This key is used to retrieve the bad-handling total constant (pur_badplacedprice) in case of an error.

Values Written

The RequiredItemAdjustPriceCy component writes the following values to the Order dictionary. The RequiredItemAdjustPrice component writes the same keys but without cy_.

Key | Description
item.cy_placed_price | Writes the placed price of an item in the items collection in the OrderForm object. For more information, see the Remarks section.
item._cy_iadjust_currentprice | Writes the adjusted current price of an item in the items collection in the OrderForm object.
_Basket_Errors | Error messages are written to this SimpleList object.

Errors

The RequiredItemAdjustPriceCy and RequiredItemAdjustPrice components return error level 2 (OPPERRORLEV_WARN) when the placed price is not equal to the current price. Other errors return error level 3 (OPPERRORLEV_FAIL).

These components write error messages to the _Basket_Errors collection. These components use a MessageManager object to retrieve user warning message text.

Constant | Condition
pur_badplacedprice | The placed price is not equal to the current price — the current price has changed since the item was added to the basket.

Remarks

The RequiredItemAdjustPriceCy and RequiredItemAdjustPrice components perform the same actions although on different dictionary keys. The following discussion uses the keys for the RequiredItemAdjustPriceCy component.

The RequiredItemAdjustPriceCy component verifies that the current price (_cy_iadjust_currentprice) exists for each item in the items list. If this value does not exist, the component creates it and initializes it to the regular price (_cy_iadjust_regularprice).

In addition, the component checks the placed price (cy_placed_price) against the current price (cy_iadjust_currentprice) to see if the current price has changed since the user placed the item in the basket. If the placed price does not exist, the component creates it and sets it to the current price (cy_iadjust_currentprice). If the placed price exists, but is not equal to the current price, the RequiredItemAdjustPriceCy component retrieves the warning message text for a bad placed price from the MessageManager object, and writes this message to the _Basket_Errors collection of the order form.


RequiredItemPriceCy, RequiredItemPrice

Use this component to verify that each item in the order form has a regular price assigned to it. Regular prices are assigned by the DefaultItemPrice component and similar components.

The RequiredItemPrice component is for backward compatibility only. The RequiredItemPriceCy component operates in both Site Server 3.0 Commerce Edition compatibility mode and in Commerce Server 2000 mode pipelines. For more information, see Currency Enhancements.

Intended use: Order Processing pipeline, Item Price stage.

Configuration Values

None.

Values Read

The RequiredItemPriceCy component reads the following values from the indicated dictionaries. The RequiredItemPrice component reads the same key but without cy_.

Key | Dictionary | Description
item._cy_iadjust_regularprice | Order | The regular price of an item.

Values Written

None.

Remarks

The RequiredItemPriceCy and RequiredItemPrice components perform the same actions although on different dictionary keys. The following discussion uses the keys for the RequiredItemPriceCy component.

The RequiredItemPriceCy component verifies that the _cy_iadjust_regularprice key has been set for each item in the items list.

Before the RequiredItemPrice component is run, the items list should have been initialized by the DefaultItemPriceCy component to contain the most current pricing information for the item.

If the _cy_iadjust_regularprice key does not contain a value, an error is raised.

See Also

DefaultItemPriceCy, DefaultItemPrice


RequiredOrderAdjustPriceCy, RequiredOrderAdjustPrice

Use these components to adjust the total cost of each item in an order after applying any discounts.

Use these components to calculate the cost of undiscounted items and the amount of a discount for all items in the order.

The RequiredOrderAdjustPrice component is for backward compatibility only. The RequiredOrderAdjustPriceCy component operates in both Site Server 3.0 Commerce Edition compatibility mode and in Commerce Server 2000 mode pipelines.

Intended use: Order Processing pipeline, Order Adjust Price stage.

Configuration Values

None.

Values Read

The RequiredOrderAdjustPriceCy component reads the following values from the indicated dictionaries. The RequiredOrderAdjustPrice component reads the same keys but without cy_.

Key | Dictionary | Description
item._n_unadjusted | Order | The quantity of this item that have not been discounted.
item._cy_iadjust_currentprice | Order | The current price of an item.
item._cy_oadjust_adjustedprice | Order | The total cost of an item before discounts.
item.quantity | Order | The total quantity of an item.

Values Written

The RequiredOrderAdjustPriceCy component writes the following values to the indicated dictionaries. The RequiredOrderAdjustPrice component writes the same keys but without cy_.

Key | Description
item._cy_oadjust_adjustedprice | The total cost of an item with discounts taken into account.
item._cy_oadjust_discount | The discount on an item.

Remarks

The RequiredOrderAdjustPriceCy and RequiredOrderAdjustPrice components perform the same actions although on different dictionary keys. The following discussion uses the keys for the RequiredOrderAdjustPriceCy component.

The RequiredOrderAdjustPriceCy component processes each item in the items collection of the OrderForm object.

For each item, the RequiredOrderAdjustPriceCy component first calculates the cost of the non-discounted quantity. It multiplies the current price of the item (_cy_iadjust_currentprice) by the undiscounted quantity of the item (n_unadjusted) and adds it to the total cost of the item (_cy_oadjust_adjustedprice).

Next, it calculates the discount for the item (cy_oadjust_discount) by calculating the total cost for the item (multiplying the current price of the item (_cy_iadjust_currentprice) by the total quantity (quantity)) and subtracting the previously calculated cost of the undiscounted items.

The RequiredOrderAdjustPriceCy component is visible in the Pipeline Editor only when the Editor is run in expert mode.


RequiredOrderCheck

Use this component to verify that the order form contains at least one item.

Intended use: Order Processing pipeline, Order Check stage.

Configuration Values

None.

Values Read

The RequiredOrderCheck component reads the following value from the indicated dictionary.

Key | Dictionary | Description
MessageManager | Context | A reference to a MessageManager object that is used to retrieve the "no items in order" constant (pur_noitems) in case of an error.

Values Written

The RequiredOrderCheck component writes the following values to the Order dictionary:

Key | Description
_Purchase_Errors | Error messages are written to this SimpleList object.

Errors

The RequiredOrderCheck component returns error level 2 (OPPERRORLEV_WARN) when there are no items in the OrderForm. Other errors return error level 3 (OPPERRORLEV_FAIL).

The components write error messages to the _Purchase_Errors collection. The components use a MessageManager object to retrieve user warning message text.

Constant | Condition
pur_noitems | There are no items in the OrderForm object.

Remarks

The RequiredOrderCheck component ensures that the items list of the OrderForm object is not empty.

See Also

MessageManager Object


RequiredOrderInitCy, RequiredOrderInit

Use this component to initialize the payment authorization code, order ID, totals, and subtotals in an order form.

The RequiredOrderInit component is for backward compatibility only. The RequiredOrderInitCy component operates in both 3.0 compatibility mode and in 4.0 mode pipelines. For more information, see Currency Enhancements.

Intended use: Order Processing pipeline, Order Initialization stage.

Configuration Values

None.

Values Read

The RequiredOrderInitCy and RequiredOrderInit components read the following values from the indicated dictionaries.

Key | Dictionary | Description
order_id | Order | The ID of the order.
item.quantity | Order | The quantity of an item.

Values Written

The RequiredOrderInitCy component writes the following values to the Order dictionary. The RequiredOrderInit component writes the same keys but without cy_.

Key | Description
order_id | The ID of the order.
item._cy_oadjust_adjustedprice | The total cost of an item.
item._n_unadjusted | The number of items that have not been discounted.
_cy_total_total | The total cost of the order.
_cy_oadjust_subtotal | The subtotal of all items in the items list.
_cy_shipping_total | The total cost of shipping all items in the order.
_cy_tax_total | The total tax for the order.
_cy_handling_total | The total handling cost for the order.
_payment_auth_code | The payment authorization code.

Remarks

The RequiredOrderInitCy and RequiredOrderInit components perform the same actions although on different dictionary keys. The following discussion uses the keys for the RequiredOrderInitCy component.

First, the RequiredOrderInitCy component ensures that the order_id key has a value. If it does not, the RequiredOrderInitCy component generates a unique order ID and assigns it to this key.

Next, to ensure order integrity, the component initializes the following keys by assigning NULL to them:

_cy_total_total
_cy_oadjust_subtotal
_cy_shipping_total
_cy_tax_total
_cy_handling_total
_cy_tax_included
_payment_auth_code

Finally, for each item in the items collection, the RequiredOrderInitCy component copies the value stored in the quantity key to the _n_unadjusted key to initialize the undiscounted quantity of the item, and initializes the _oadjust_adjustedprice (the total cost of the item) key to zero (0).


RequiredOrderSubtotalCy, RequiredOrderSubtotal

Use this component to ensure that the subtotal of all items in the item list of an order exist so that order totals are properly calculated.

The RequiredOrderSubtotal component is for backward compatibility only. The RequiredOrderSubtotalCy component operates in both Site Server 3.0 Commerce Edition compatibility mode and in Commerce Server 2000 mode pipelines. For more information, see Currency Enhancements.

Intended use: Order Processing pipeline, Order Subtotal stage.

Configuration Values

None.

Values Read

The RequiredOrderSubtotalCy component reads the following value from the indicated dictionary. The RequiredOrderSubtotal component reads the same key but without cy_.

Key | Dictionary | Description
_cy_oadjust_subtotal | Order | The subtotal of all items in the item list of the order.

Values Written

None.

Remarks

Both the RequiredOrderSubtotalCy and RequiredOrderSubtotal components check the _oadjust_subtotal key in the OrderForm object to ensure that the value assigned to it is not NULL.

The RequiredOrderSubtotalCy component is visible in the Pipeline Editor only when the Editor is run in expert mode.


RequiredPayment

Use this component to verify that the payment authorization code exists in the order form (is not NULL).

Intended use: Order Processing pipeline, Payment stage.

Configuration Values

None.

Values Read

The RequiredPayment component reads the following values from the indicated dictionaries.

Key | Dictionary | Description
_payment_auth_code | Order | The payment authorization code for the order form.
MessageManager | Context | A reference to a MessageManager objectthat is used to retrieve the bad payment constant (pur_bad_payment) in case of an error.

Values Written

The RequiredPayment component writes the following values to the Order dictionary.

Key | Description
_Purchase_Errors | Error messages are written to this SimpleList object.

Errors

This component writes an error message to the _Purchase_Errors collection. The component uses a MessageManager object to retrieve user warning message text.

Constant | Condition
pur_badpayment | The payment authorization code is missing from the order form.

Remarks

If the payment authorization code does not exist (is equal to NULL), the RequiredPayment component retrieves the error for the pur_badpayment constant from the MessageManager object, and writes this error to the _Purchase_Errors collection of the OrderForm object.

See Also

MessageManager Object


RequiredProdInfo

Use this component to delete items flagged for deletion by a previous Product Info stage component.

Intended use: Order Processing pipeline, Product Info stage.

Configuration Values

None.

Values Read

The RequiredProdInfo component reads the following values from the indicated dictionaries.

Key | Dictionary | Description
item.delete | Order | A flag on an item in the items collection of the OrderForm object. This key is created and set by another pipeline component.
MessageManager | Context | A reference to a MessageManager object that is used to retrieve the bad stockkeeping unit (SKU) constant (pur_badsku) in case of an error.

Values Written

The RequiredProdInfo component writes the following values to the Order dictionary.

Key | Description
_Basket_Errors | Error messages are written to this SimpleList object.

Errors

The component writes an error message to the _Basket_Errors collection. The component uses a MessageManager object to retrieve user warning message text.

Constant | Condition
pur_badsku | One or more items were deleted from the order.

Remarks

The RequiredProdInfo component checks all items in the items collection in the OrderForm object and deletes any items with a delete key set to 1 (one). Components that set this key include QueryCatalogInfo and QueryProdInfoADO.

If the RequiredProdInfo component deletes any items from the items collection, it uses the pur_badsku constant to retrieve error message text from the MessageManager object and stores this message in the _Basket_Errors collection of the OrderForm object so that the application can report the problem with the item to the user.

See Also

QueryCatalogInfo

QueryProdInfoADO


RequiredShippingCy, RequiredShipping

Use these components to verify that the shipping total has been set.

The RequiredShipping component is for backward compatibility only. The RequiredShippingCy component operates in both Site Server 3.0 Commerce Edition compatibility mode and in Commerce Server 2000 mode pipelines. For more information, see Currency Enhancements.

Intended use: Order Processing pipeline, Shipping stage.

Configuration Values

None.

Values Read

The RequiredShippingCy component reads the following values from the indicated dictionaries. The RequiredShipping component reads the same key but without cy_.

Key | Dictionary | Description
_cy_shipping_total | Order | The total shipping cost for the order.
MessageManager | Context | A reference to a MessageManager object that is used to retrieve the bad-shipping total constant (pur_badshipping) in case of an error.

Values Written

The RequiredShippingCy and RequiredShipping components write the following value to the Order dictionary.

Key | Description
_Purchase_Errors | Error messages are written to this SimpleList object.

Errors

The RequiredShippingCy and RequiredShipping components return error level 2 (OPPERRORLEV_WARN) when the handling total is not in the order form. Other errors return error level 3 (OPPERRORLEV_FAIL).

The components also write an error message to the _Purchase_Errors collection. The components use a MessageManager object to retrieve error message text.

Constant | Condition
pur_badshipping | The shipping total key does not exist in the order.

Remarks

The RequiredShippingCy and RequiredShipping components perform the same actions although on different dictionary keys. The following discussion uses the keys for the RequiredShippingCy component.

The RequiredShippingCy component verifies that the _cy_shipping_total key exists in the order form. If the value does not exist, it uses the pur_badshipping constant to retrieve error message text from the MessageManager object and stores this message in the _Purchase_Errors collection of the OrderForm object.

See Also

MessageManager Object


RequiredTaxCy, RequiredTax

Use these components to verify that total tax and tax included appear in the order form.

The RequiredTax component is for backward compatibility only. The RequiredTaxCy component operates in both Site Server 3.0 Commerce Edition compatibility mode and in Commerce Server 2000 mode pipelines. For more information, see Currency Enhancements.

Intended use: Order Processing pipeline, Tax stage.

Configuration Values

None.

Values Read

The RequiredTaxCy component reads the following values from the indicated dictionaries. The RequiredTax component reads the same key but without cy_.

Key | Dictionary | Description
_cy_tax_total | Order | The total tax for the order.
_cy_tax_included | Order | The amount of tax included in the order.
MessageManager | Context | A reference to a MessageManager object that is used to retrieve the bad tax constant (pur_badtax) in case of an error.

Values Written

The RequiredTaxCy and RequiredTax components write the following value to the Order dictionary.

Key | Description
_Purchase_Errors | Error messages are written to this SimpleList object.

Errors

The RequiredTaxCy and RequiredTax components return error level 2 (OPPERRORLEV_WARN) when one of the tax items is missing. Other errors return error level 3 (OPPERRORLEV_FAIL).

The components also write an error message to the _Purchase_Errors collection. The components use a MessageManager order to retrieve error message text.

Constant | Condition
pur_badtax | One of the tax items is missing.

Remarks

The RequiredTaxCy and RequiredTax components perform the same actions although on different dictionary keys. The following discussion uses the keys for the RequiredTaxCy component.

The RequiredTaxCy component verifies that the _cy_tax_total and _cy_tax_included keys exist in the order form. If either value does not exist, the RequiredTaxCy component uses the pur_badtax constant to retrieve error message text from the MessageManager object and stores this message in the _Purchase_Errors collection of the OrderForm object.

See Also

MessageManager Object


RequiredTotalCy, RequiredTotal

Use these components to verify that values on a page have not been tampered with or reset. The components compare values in the order against values in the _Verify_With dictionary.

The RequiredTotal component is for backward compatibility only. The RequiredTotalCy component operates in both Site Server 3.0 Commerce Edition compatibility mode and in Commerce Server 2000 mode pipelines. For more information, see Currency Enhancements.

Intended use: Order Processing pipeline, Order Total stage.

Configuration Values

None.

Values Read

The RequiredTotalCy and RequiredTotal components read the following values from the indicated dictionaries.

Key | Dictionary | Description
_Verify_With | Order | A dictionary whose keys and values will be tested against keys and values in the order form.
MessageManager | Context | A reference to a MessageManager object that is used to retrieve the verification error constant (pur_badverify) in case of an error.

Values Written

The RequiredTotalCy and RequiredTotal components write the following value to the Order dictionary.

Key | Description
_Purchase_Errors | Error messages are written to this SimpleList object.

Errors

The RequiredTotalCy and RequiredTotal components return error level 2 (OPPERRORLEV_WARN) when one or more of the keys and values in the _Verify_With dictionary do not match the corresponding order form entries. Other errors return error level 3 (OPPERRORLEV_FAIL).

The components write error messages to the _Purchase_Errors collection. The components use a MessageManager object to retrieve user warning message text.

Constant | Condition
pur_badverify | At least one of the keys and values in the _Verify_With dictionary did not match the corresponding pair in the order form.

Remarks

The RequiredTotalCy and RequiredTotal components go through the keys and values in the _Verify_With dictionary to ensure that the keys exists in the order form and have the same values.

You can use these components to verify that values on a page have not been tampered with or reset. To verify values on a page, add a hidden field for each item named _VERIFY_WITH that contains the item and the associated value. For, example to verify that the value ship_to_zip has not been altered, you would create a tag on the page similar this:

<INPUT TYPE="HIDDEN" NAME="_VERIFY_WITH"
       VALUE="<% = "ship_to_zip=" & CStr(mmsOrderForm.ship_to_zip) %>">

When the page is posted, the name and value will be added as a key and value to the _Verify_With dictionary in the OrderForm object.

You can use the VerifyWith method of the Page object to create the hidden tags. The ProcessVerifyWith method of the Page object copies the values of the hidden fields into the _Verify_With dictionary in the OrderForm object.

The Order Total stage always performs a _VERIFY_WITH check. Any fields in the post that appear as _VERIFY_WITH="value=key" will verify that the order has such a key and it is set to that value. This prevents a malicious resetting of addresses or contents. If _VERIFY_WITH is not on the order form, no check is performed.

For example, order._total_total should equal (order._VERIFY_WITH)._total_total if _total.total is in the _VERIFY_WITH clause.

See Also

Page.ProcessVerifyWith

Page.VerifyWith


SaleAdjust

Use this component to apply a sale price to an item.

This component is included for backward compatability only. It has been replaced by the OrderDiscount component.

Intended use: Order Processing pipeline, Item Adjust Price stage.

Configuration Values

None.

Values Read

The SaleAdjust component reads the following values from the indicated dictionaries.

Key | Dictionary | Description
item._product_sale_start | Order | Optional. The date the sale begins.
item._product_sale_end | Order | Optional. The date the sale ends.
item._product_sale_price | Order | The sale price of the item.

Values Written

The SaleAdjust component writes the following values to the Order dictionary.

Key | Description
item._iadjust_currentprice | The current price of the item with the promotion applied.

Remarks

The SaleAdjust component allows you to apply the sale price of an item. If the item is on sale, and if its _iadjust_currentprice key has not been initialized by a previously executed component, the SaleAdjust component initializes _iadjust_currentprice key to the value stored in item._product_sale_price key.

The SaleAdjust component determines if an item is on sale by comparing the current date to the date values specified for the _product_sale_start key and the _product_sale_end key of the item.

The SaleAdjust component requires that the various sale values exist in the product table of the site database. Otherwise, the OrderForm object will not contain the data needed to calculate the adjusted price of the item (_iadjust_currentprice), and an error message will be generated. The product sale keys are set by the QueryProdInfoADO component in the Product Information stage.

Because the _product_sale_start and _product_sale_end keys are actually date-time pairs that specify midnight, the _product_sale_end key excludes the date specified. Thus, if you want the last day of a promotion to be 3/31, be sure to specify that the promotion ends on 4/1.

See Also

QueryProdInfoADO

OrderDiscount


SampleRegionalTax

Use this component for calculating taxes in pipelines using the multiple shipment features of Commerce Server 2000.

Note

  • The SampleRegionalTax component is not a complete solution to tax calculation. It is provided as an example of a tax component that takes full advantage of the multiple shipment features of Commerce Server 2000. Microsoft strongly recommends that you purchase a third-party tax component.

Intended use: Order Processing pipeline, Tax stage.

Configuration Values

None.

Values Read

The SampleRegionalTax component reads the following values from the indicated dictionaries.

Key | Dictionary | Description
shipments | Order | A SimpleList object of shipments.
item._cy_oadjust_adjustedprice | Order | The total cost of an item.
RegionalTaxCache | Context | A reference to a dictionary containing tax information.

In addition, the SampleRegionalTax component reads the following keys from the Addresses dictionary in the OrderForm object.

Key | Description
addresses.country_code | The ship to country for the address ID retrieved for the shipment.
addresses.region_code | Optional. The ship to region for the address ID retrieved for the shipment.

Values Written

The SampleRegionalTax component writes the following values to the Order dictionary.

Key | Description
item._cy_tax_total | The total tax for the item.
item._cy_tax_included | The total tax for the item included in the cost. You must set this key to zero (0).
shipment._cy_tax_total | The total tax for the shipment.
shipment._cy_tax_included | The total tax for the shipment included in the cost. You must set this key to zero (0).
_cy_tax_total | The total tax for the order.
_cy_tax_included | The total tax for the order included in the cost. You must set this key to zero (0).

Remarks

The SampleRegionalTax component computes tax for the Commerce Server 2000 shipping architecture that handles multiple shipments. For more information about how Commerce Server processes shipments, see Multiple-shipment Shipping Architecture.

For each shipment in the order, the component first gets the tax rate from the database using the CacheManager object and stores it in the SampleRegionalTaxCache component.

The SampleRegionalTax component then goes through each item in the shipment and calculates its tax based on the rate retrieved from the tax rate table. Rates are retrieved based on the country and region codes in the dictionary of addresses in the Order dictionary. For more information about the dictionary of addresses, see Multiple-shipment Shipping Architecture.

As it goes through the items and shipments in the order, the SampleRegionalTax component accumulates totals for the items, shipments, and, finally, for the entire order.

The tax rate data stored in the SampleRegionalTaxCache component is a snapshot of the RegionalTax database table. The RegionalTax table contains three columns.

Column | Data Type | Description
country_code | String, 255 characters. | The country code.
region_code | String, 255 characters. | The region code.
rate | Float, 8 bytes. | The tax rate.

You may include a wildcard entry (@) for a region code. This will match regions that would not otherwise match. If no entry is found in the RegionalTax table, the rate is zero (0).

Using a pipeline containing the SampleRegionalTax component is very similar to using a Content Selection pipeline. First, you configure the CacheManager object to use the SampleRegionalTaxCache loader in the Application_OnStart section of the Global.asa file. Then, in the Active Server Pages (ASP) page, you add an entry for the CacheManager object to the Context dictionary and invoke the pipeline.

Setup code in the Application_OnStart method:

    ' Create a Dictionary to hold configuration information.
    Set dConfig = CreateObject("Commerce.Dictionary")

    ' Add configuration information to the dictionary. SampleRegtionalTax
    ' only uses a connection string.
    dConfig("ConnectionString") = "DSN=adsamples;UID=sa;PWD="

    ' Create a CacheManager object.
    Set CacheManager = Server.CreateObject("Commerce.CacheManager")

    ' Set the ProgID of the Loader component for the
    ' "SampleRegionalTaxCache" cache.
    CacheManager.LoaderProgId("SampleRegionalTaxCache") = _
                    "Commerce.SampleRegionalTaxCache"

    ' Set the Loader component config Dictionary for the cache.
    Set CacheManager.LoaderConfig("SampleRegionalTaxCache") = dConfig

    '
    ' Other CacheManager configuration code would appear here.
    '

    ' Store a reference to the CacheManager in the Application object.
    Set Application("CacheManager") = CacheManager

Code to run the pipeline containing the SampleRegionalTax component:

    ' Place a reference to the CacheManager in the context dictionary.
    Set dContext = Server.CreateObject("Commerce.Dictionary")
    dContext.CacheManager = Application("CacheManager")

    '
    ' Set other values and create the Order dictionary (dOrder) here.
    '

    ' Load and execute the pipeline containing the tax component.
    Set pPooledPipe = Server.CreateObject("Commerce.PooledPipeline")
    pPooledPipe.LoadPipe("OrderAndTax.pcf")
    iErrVal = pPooledPipe.Execute(0, dOrder, dContext, 1)

See Also

Multiple-shipment Shipping Architecture

CacheManager Object

PooledPipeline Object

PooledTxPipeline Object


SaveHistory

Use this component to record the history string in one of three locations: the User Profile object, the ASP Session Collection, or the HTTP Cookie.

Although the component appears as SaveHistory in the Pipeline Editor, its ProgID is Commerce.CSFSaveHistory.

Intended use: Content Selection pipeline, Record stage.

Configuration Values

You can determine where the SaveHistory component saves the history string by setting component properties. Use the following boxes on the Save History tab of the Component Properties dialog box to determine this information. You must choose one of the following options.

Box | Description
User Profile Object | The property in the user profile to store the history string. The default is Advertising Info.Campaign History.
ASP Session Collection | The key in the Session object containing the history string. Requires that the component be configured with the proper key and that the pipeline be executing in IIS context. This is the default option.
HTTP Cookie | The key in the Cookies object containing the history string. This option requires that the component be configured with the proper key and that the pipeline be executing in IIS context.

Values Read

The SaveHistory component reads the following values from the indicated dictionary.

Key | Dictionary | Description
_history | Order | The history string retrieved by the LoadHistory component.

Values Written

None.

Errors

The SaveHistory component returns error level 3 (OPPERRORLEV_FAIL) when an error occurs.

Remarks

Saves the history string in one of the same three locations that the LoadHistory component can use as a source.

The property page for this component supports the same three choices as the property page for the LoadHistory component.

When using the User Profile object option, it's possible to use either a field that is mapped to a data column in a table, or a field that is not mapped. If the field is not mapped, the history string is persisted only for the duration of the user session and is later timed out of the profile cache. This method is more efficient than using the mapped method, but the mapped method allows the history string to be persisted across sessions. The unmapped option does not allow you to load balance Domain Name Server (DNS) network requests by sending the incoming requests to the next server in a list (round-robin load balancing).

See Also

LoadHistory


SaveReceipt

Use this component to save an order in a database table.

Intended use: Order Processing pipeline, Accept stage.

Configuration Values

You can determine which items the SaveReceipt component will save in the database by setting component properties. Use the following boxes on the Save Receipt tab of the Component Properties dialog box to determine this information.

Box | Description
No Save Key Prefix | A prefix that identifies keys in the order form that should not be saved in the database table. Use this prefix to identify sensitive information such as credit-card numbers that should not be saved. The default prefix is _cc_.

Values Read

The SaveReceipt component reads the following values from the indicated dictionaries.

Key | Dictionary | Description
ReceiptStorage | Context | A reference to a DBStorage object pointing to a database in which to save the data.
<Various Fields> | Order | The SaveReceipt component saves all fields in the order form that have a corresponding name in the database table and that do not begin with the characters specified in the No Save Key Prefix box.

Values Written

None.

Remarks

The SaveReceipt component saves an order to a database table. The name of the database table is stored in the DBStorage object. The Context dictionary key ReceiptStorage points to the object. The SaveReceipt component saves all fields on the order form that have a corresponding column name in the database table.

See Also

DBStorage Object


ScoreDiscounts

Use this component in discount promotion selection to adjust scores of discount items to promote discounts most relevant to the current user.

Although the component appears as ScoreDiscounts in the Pipeline Editor, its ProgID is Commerce.CSFScoreDiscounts.

Intended use: Content Selection pipeline, Scoring stage.

Configuration Values

None.

Values Read

The ScoreDiscounts component reads the following values from the indicated dictionaries.

Key | Dictionary | Description
_content | Order | A reference to the ContentList object. Multiple fields are read. For more information, see the Remarks section..
Evaluator | Context | A reference to the Expression Evaluator component to use.
ContextProfile | Context | Optional. The ContentSelector object (a dictionary) used in expression evaluation. A SimpleList object of dictionaries can also be read from the ContextProfile object from a key named Products. Typically, this is a list of the products the user is viewing or browsing (on the current page, for example). This product list should have the same format as the items list in an OrderForm object once the QueryCatalogInfo component has been run on it, making all product attributes available for discount expressions.
UserProfile | Context | Optional. A reference to a ProfileObject object containing the user profile for the current user that is used in expression evaluation.
Items | ContextProfile | Optional. The items collection from the OrderForm object. This list of products should have the same format as the items list in an OrderForm object once the QueryCatalogInfo component has been run on it, making all attributes of a product available for discount expressions.
trace | Context | Optional. A Boolean indicating whether score adjustment tracing is enabled. This component will not produce trace strings unless this key is set to True.

The ScoreDiscounts component reads the following values for each item in the ContentList object referred to by the _content key.

Key | Description
required_exprs | The required expressions built on User and Context profiles. This is an array of expression IDs that must be True; otherwise the discount is assigned a score of zero (0).
condition_expr | The discount condition expression.
award_expr | The award condition expression.
date_start | The date the discount becomes active.
date_end | The date the discount expires.

Values Written

The ScoreDiscounts component writes the following value to the Order dictionary.

Key | Description
_content | A reference to the ContentList object. The score key of each content item in the object is assigned a value.

Remarks

This component adjusts the score of discount content items with the goal of promoting discounts most relevant to the current user. The algorithm is based on the following considerations:

  • The start and end dates of the discount. If the discount has not started, or has expired, it is disqualified.

  • Whether the item to be discounted is in the shopping basket.

  • Whether the item to be discounted is on the page being viewed (in the products list).

The following table lists the multipliers used based on the various combinations of the conditions and awards being met in the basket, in the products list, or not met. A condition or award being "met" means that the expression evaluates to True, but not necessarily that the cost or quantity amount was met. More than one entry in the table below may be met. The first one met is the one applied.

Condition | Award | Multiplier | Description
Met in basket | Applies to all (or free shipping) | 0.5 | The user is already receiving the benefit of the discount.
Met in basket | Met in basket | 0.5 | The user is already receiving the benefit of the discount.
Met in basket | Met in products | 1.6 | The user has half the discount in the basket, and is in the part of the site with the other half.
Met in basket | Not met | 1.4 | The user has half the discount in the basket.
Met in products | Applies to all (or free shipping) | 1.2 | The user is in the part of the site with half the discount.
Met in products | Met in basket | 1.6 | The user has half the discount in the basket, and is in the part of the site with the other half.
Met in products | Met in products | 1.4 | The user is in the part of the site with both halves of the discount.
Met in products | Not met | 1.2 | The user is in the part of the site with half the discount.
Not met | Applies to all (or free shipping) | 1.0 | Neutral context.
Not met | Met in basket | 1.4 | The user has half the discount in the basket.
Not met | Met in products | 1.2 | The user is in the part of the site with half the discount.
Not met | Not met | 1.0 | Neutral context.

The OrderDiscount component applies the discounts whose scores are adjusted by the ScoreDiscounts component. The ScoreDiscounts component saves the scores in the ContentList object held by the CacheManager object. That ContentList object is then used by the OrderDiscount component in another pipeline.

See Also

Discount Objects

CSFLoadDiscounts

OrderDiscount


Scriptor

Use this component to execute a script in a Microsoft ActiveX scripting language such as PerlScript from ActiveState, or Microsoft Visual Basic Scripting Edition (VBScript).

Intended use: any pipeline, any stage.

Configuration Values

You can determine where the Scriptor component reads the script and the parameters passed to it by setting component properties. Use the following boxes on the Scriptor tab of the Component Properties dialog box to determine this information.

Box | Description
Scripting Engine | Specifies the scripting language in which the script is written. The a drop-down list contains the scripting engines installed on your system.
Source Specifies whether the script is stored internally or externally. The options are:

Internal

The script is stored in the pipeline (.pcf) file itself. In the Pipeline Editor, click Edit to display the script for editing.

External

The script is stored in a file on disk. Enter the path and file name of the script in the Filename box. You can import an external script and convert it to an internal script. For more information, see Configuring a Scriptor Component.
Config | The parameters passed to the script in the form name=value.

Values Read

None.

Values Written

None.

Remarks

The Scriptor component calls three procedures in the script, in turn:

  1. The MSCSOpen procedure. The Scriptor component calls this procedure first and passes it the Configuration dictionary. You may omit this procedure.

  2. The MSCSExecute function. This is the main Scriptor component procedure and must appear in the script. The function is passed, in order, to the Configuration dictionary, the Order dictionary (usually an OrderForm object), the Context dictionary, and a flags variable.

  3. The MSCSClose handler. The Scriptor component invokes this procedure after the MSCSExecute procedure returns. It has no arguments and may be omitted.

The MSCSExecute function must return a success code. If you write the script in VBScript, the MSCSExecute routine must be a function, not a subroutine. The MSCSExcute function return values are: 1 for success, 2 for warning, and 3 for failure.

Parameters entered in the Config box of on the Scriptor tab in the Component Properties dialog box are passed to the script in the Configuration dictionary. The name is used as the key, and the value on the right of the equal sign is the value assigned to that key.

This is because the MSCSExecute function must return a success value of 1, a warning value of 2, or a failure value of 3. Subroutines cannot return 1.

If you include the Scriptor component in a pipeline using the MtsTxPipeline object, you should not call methods of the ObjectContext object in the MSCSOpen or MSCSClose procedures. Calls to ObjectContext methods may be used only in the MSCSExecute procedure.

The Microsoft Transaction Server (MTS) context is not available to a Scriptor component or to any components called by a Scriptor component. Thus context.SetComplete and context.SetAbort are not available to scripts run by the Scriptor component.

See Also

Configuring a Scriptor Component


Configuring a Scriptor Component

The script run by a Scriptor component can be stored internally, as part of a pipeline configuration file (.pcf), or externally, in a separate file called by the component when it runs.

You can write a general-purpose script that can behave differently depending on the parameters that are passed to it. Save the script itself in a file, and then configure the Scriptor component to pass the parameters.

The Microsoft Transaction Server (MTS) context is not available to a Scriptor component or to any components called by a Scriptor (that is, context.SetComplete and context.SetAbort are not available to scripts hosted by the Scriptor component).

To configure a Scriptor component

To convert a Scriptor between external and internal

To configure a Scriptor component

  1. Click Start, point to Programs, point to Microsoft Commerce Server, and then click Pipeline Editor.

  2. On the File menu, click Open. Browse to the pipeline containing the Scriptor component, and click Open.

  3. Right-click the Scriptor component you want to configure, click Properties, and then click the Scriptor tab.

  4. On the Scriptor tab, do the following:
    Use this | To do this
    Scripting Engine | Select the language in which the script was written.
    Source Select Internal, and then click Edit. In the Scriptor -- Source Code Edit screen, type or paste the script for your component, and then click OK.

    Or, select External to store the script in an external file. In the Scriptor dialog box, click No, if you do not wish to export the internal source code. Type the path and file name in the Filename box.
    Config To pass parameters to the script, type the parameters for the component in the form name=value.

    Or, leave blank.

  5. Click OK, and then click Apply.

To convert a Scriptor between external and internal

  1. Click Start, point to Programs, point to Microsoft Commerce Server, and then click Pipeline Editor.

  2. On the File menu, click Open. Browse to the pipeline containing the Scriptor component, and click Open.

  3. Right-click the Scriptor component you want to configure, click Properties, and then click the Scriptor tab.

  4. To convert to external storage if the Scriptor has already been configured for an external file, click Internal, and then click Yes to confirm that you want to import the external file.

    Or, to convert to internal storage if the Scriptor has already been configured for an internal file, click External, and then click Yes to confirm that you want to export the internal file. Specify a name for the external file, and then click Save.

  5. Click OK.


SelectWinners

Use this component to choose items based on their final scores in the Content Selection pipeline.

Although the component appears as SelectWinners in the Pipeline Editor, its ProgID is Commerce.CSFSelectWinners.

Intended use: Content Selection pipeline, Select stage.

Configuration Values

You can determine when the SelectWinners component displays house ads by setting component properties. Use the following box on the Select Winners tab of the Component Properties dialog box to determine this information.

Box | Description
Switch to house ads | The threshold at which house ads will be selected over paid ads. When the maximum Need of Delivery (NOD) for paid ads drops below this value, house ads are selected. The default is 0.95.

Values Read

The SelectWinners component reads the following values from the indicated dictionaries.

Key | Dictionary | Description
_Content | Order | A reference to the ContentList object. Multiple fields are read. For more information, see the Remarks section.
NumRequested | Order | Optional. The number of content items that should be selected for return. The default is 1 (one).
PageHistory | Context | Optional. A reference to the page-level history string. The reference allows the history to be passed between requests for content that are on the same page (can be used cross-page as well). This key is retrieved from the ContextProfile dictionary in the Context dictionary. It contains the item_ids of content items already selected on the page.

The SelectWinners component reads the following values for each item in the ContentList referred to by the _content key.

Key | Description
Score | The final scores of the various content items.
Industry | The industry tag used to prevent two content items from same industry from being selected.
need_of_delivery | The contract requirements for delivering the ad.
ad_type | A paid (1) versus house (2) ad type.
customer_id | This key is used to prevent competing ads.
ad_weight | This key is used for house ads to allow some to be displayed more frequently.

The Score key is required. Other keys are required only for ad selection.

Values Written

The SelectWinners component writes the following values to the indicated dictionaries.

Key | Dictionary | Description
_event | Order | This key is set to the string "REQUEST", unless it is already set.
PageHistory | Context | The new page history, now including items selected in the current request. The PageHistory key is in the ContextProfile dictionary in the Context dictionary.
_winnerindexes | Order | A reference to a SimpleList object containing the ContentList object indexes of selected content items.

Remarks

To communicate the winners, the SelectWinners component builds a new SimpleList object that contains the ContentList object indexes up to the requested number of winning content items.

The SelectWinners component performs the following additional actions:

  • Sets the _event key to the string "REQUEST", unless it is already set.

  • Uses the PageHistory key to prevent showing the same ad more than once on a page. This is most useful in network ad models where multiple selection requests are made from the same page.

  • Prevents competing ads from appearing on the same page. This is based on the industry setting of each ad, combined with a user identifier.

This component looks at the NumRequested key in the Order dictionary to determine how many content items to select. If that key is missing, one content item is selected. It is not considered an error to return fewer than NumRequested content items. The caller must handle this condition.

The PageHistory key is a string containing a list of IDs for content items already selected for the current page. The caller defines what constitutes a "page," and the caller is responsible for saving the PageHistory key across calls to the same page. The item_id keys from the content items in the ContentList object are written to this string in decimal form and are separated by commas. If the same ContentSelector object is used for multiple content requests on the same page, then the PageHistory key will automatically be passed between the calls.

The following list describes the selection algorithm for ads:

  • Items appearing in the PageHistory key are not eligible for selection.

  • Paid ads with a Need of Delivery (NOD) value greater than the house ad threshold will always be selected over house ads.

  • Ads that compete with another ad that was already selected, including ads in the PageHistory key, are not eligible for selection. Competing ads are defined as ads in the same industry but from different users.

  • Selection proceeds are based on score, returning higher scores first. If multiple paid ads have the same score, selection between them is random.

The following list describes the selection algorithm for content types other than ads:

  • Items appearing in the PageHistory key are not eligible for selection.

  • Selection proceeds are based on score, returning higher scores first. If multiple items have the same score, selection between them is random.

See Also

ContentList Object

ContentSelector Object


SendPrecomposedMessage

Use this component to send a direct mail message composed in earlier stages in the pipeline.

Although the component appears as SendPrecomposedMessage in the Pipeline Editor, its ProgID is Commerce.DMLSendPrecomposedMessage.

Intended use: Direct Mailer pipeline, Send E-mail stage.

Configuration Values

None.

Values Read

The SendPrecomposedMessage component reads the following values from the indicated dictionaries.

Key | Dictionary | Description
rcp_bypass | Order | Boolean. The component bypasses (skips) processing if True.
cdo_result | Order | The result code (an HRESULT) from the most recent Collaboration Data Objects (CDO) operation.
cdo_message | Context | A reference to the CDO message object (CDO.Message).

Values Written

The SendPrecomposedMessage component writes the following values to the Order dictionary.

Key | Description
messages_sent | The total number of messages sent for this pipeline cycle.
cdo_result | The result code (an HRESULT) from the most recent CDO operation.
cdo_error | Optional. An error string from the most recent CDO operation, if any. NULL if there is no error.

Remarks

The SendPrecomposedMessage component attempts to send a direct mail message using CDO for Microsoft Windows 2000. The component skips processing the message if the bypass flag (rcp_bypass) is True or if the cdo_result key is not equal to S_OK.

The component checks for errors after each CDO operation.

See Also

AddAttachments

ComposeDMLMessage

CreateUPMCookie

ThrottleDMLPerformance

VerifyMessageBody

VerifyRecipientData


SendSMTP

Use this component to send an e-mail message to a specified recipient.

Intended use: Commerce Interchange Transmit pipeline, Transport stage.

Configuration Values

You can determine where the SendSMTP component sends the message and the information sent by setting component properties. Use the following boxes on the Send SMTP tab of the Component Properties dialog box to determine this information.

Box | Description
From (required) | The e-mail address from which the message is sent. This is the actual e-mail address rather than a key containing the e-mail address.
SMTP Host (required) | The name or Internet Protocol (IP) address of the Simple Mail Transfer Protocol (SMTP) mail server that will transmit the object. This is the actual name of the server rather than a key containing the name.
To (required) | The key in the Order dictionary containing the e-mail address to send the message to.
Cc | The key in the Order dictionary containing the e-mail addresses to send copies of the message to.
Subject | The key in the Order dictionary that contains the text to display in the Subject box of the e-mail message.
Character Set for Subject | The character set to use to encode the subject of this e-mail message. This drop-down list displays the character sets currently installed on this computer.
Message Body | The key in the Order dictionary containing the message to include in the body of the e-mail message.
MIME header and body | Indicates the business data object is already encapsulated in a Multipurpose Internet Mail Extensions (MIME) header. If you select this option, the component uses the character set and header already encapsulated with the message rather than generating its own MIME header and using the character set specified in the Character Set for Subject box.
Text Body | Indicates the business data object consists of straight ASCII text and no further processing is needed.
Binary body | Specifies that the business data object is a binary blob. The SendSMTP component will base64-encode it before sending.

Values Read

None.

Values Written

None.

Remarks

The SendSMTP component sends a business data object as an e-mail message to an SMTP mail server. If you are using Microsoft Exchange and Outlook, you can run a Visual Basic script to invoke an OrderPipeline object (but not an MtsPipeline or MtsTxPipeline object) on the Exchange server to process the received messages.

In order for the SendSMTP component to properly support character set conversion, the corresponding Windows NT code page must be installed on the computer. For example, the US version of the Windows NT installation does not include the Japanese code page (code page 932), which must be present to convert Unicode to ISO-2022-jp. For information on installing a code page, see Microsoft Knowledge Base article Q164948.

Programmatic Use

To use this component outside a pipeline, you must configure it by assigning values to keys in the Configuration dictionary. The keys correspond to the indicated boxes in the Component Properties dialog box.

Key | Box | Description
From | From | String.
SMTPHost | SMTP Host | String.
ToField | To | String.
CCField | CC | String.
SubjectField | Subject | String.
CharSet | Character Set for Subject | String.
BodyField | Message Body | String.
BodyType | Message Body contains option buttons | Numeric: 0 MIME header and body 1 Text body 2 Binary body

For more information about using pipeline components outside pipelines, see MicroPipe Object.

See Also

MicroPipe Object


Test SendSMTP

Use this property page to send a test e-mail message to check the configuration of the SendSMTP component.

Box | Description
Email address to send text message to | The complete e-mail address to send the message to.


ShippingDiscountAdjust

Use this component to apply shipping discounts to an order.

Intended use: Order Processing pipeline, Shipping stage.

Configuration Values

None.

Values Read

The ShippingDiscountAdjust component reads the following values from the indicated dictionaries.

Key | Dictionary | Description
_cy_shipping_total | Order | The total shipping charges for the order before the discount is applied.
_shipping_discount_type | Order | The type of discount. The options are: 1 Discount by an amount 2 Percentage discount
_cy_shipping_discount_value | Order | The amount of the discount, either in a monetary value or a percentage value. Percentages are written as percentages rather than decimal fractions — a forty-percent discount would be represented by 40. Free shipping would be represented by 100.

Values Written

The ShippingDiscountAdjust component writes the following values to the Order dictionary.

Key | Description
_cy_shipping_total | The total shipping charges for the order with the discounts (if any) applied.

Remarks

The ShippingDiscountAdjust component examines the _shipping_discount_type key and adjusts the total shipping for the order. If the discount is blank, the component does nothing. If the discount type is 1 or 2, the component applies the discount. If the discount is none of these, the component returns an error.

The _shipping_discount_type key value is determined by the OrderDiscount object.

In Commerce Server 2000 pipelines, the ShippingDiscountAdjust component is used to provide free shipping by writing zero (0) for the _cy_shipping_total key.

See Also

Shipping Object

ShippingManagerCache

ShippingMethodManager Object

ShippingMethodRouter

StepwiseShipping


ShippingManagerCache

Use this component with the CacheManager object to load shipping data for the multiple shipments shipping architecture.

Note

  • Although the ShippingManagerCache component implements two of the pipeline component interfaces (IPipelineComponent and IPipelineComponentAdmin), it is not a pipeline component, it does not appear in the Pipeline Editor, and it cannot be used or configured from the Editor.

Configuration Values

None.

Values Read

None.

Values Written

None.

Remarks

You can use the ShippingManagerCache component with the CacheManager object to store shipping method information for the Splitter and ShippingMethodRouter pipeline components.

When executed by the CacheManager object, the ShippingManagerCache component uses two pipeline dictionaries (Order and Context) to determine how to run and how to return information to the CacheManager object.

Example

See the example in the Setting Up the Pipeline and Cache section in the Shipping Objects topic.

See Also

CacheManager Object

Shipping Object

ShippingDiscountAdjust

ShippingMethodManager Object

ShippingMethodRouter

StepwiseShipping


ShippingMethodRouter

Use the ShippingMethodRouter component as part of the multiple-shipment shipping architecture to look up and run the components to process the shipments and calculate the shipping total for the entire order.

Note

  • Shipping components designed to be run by the ShippingMethodRouter component should never be placed directly in a pipeline.

Intended use: Order Processing pipeline, Shipping stage.

Configuration Values

None.

Values Read

The ShippingMethodRouter component reads the following values from the indicated dictionaries.

Key | Dictionary | Description
Shipments | Order | A SimpleList object of dictionaries, one shipment per dictionary.
shipments._cy_shipping_total | Order | The shipping totals for each individual shipment.
CacheManager | Context | A reference to a CacheManager object used to handle the shipping method data.

Values Written

The ShippingMethodRouter component writes the following values to the Order dictionary.

Key | Description
_cy_shipping_total | The total shipping for all shipments in the order.

Remarks

The shipping components (other than the Splitter component) are run by the ShippingMethodRouter component.

The component next steps through the list of shipping methods. If there are shipments using a given method, the ShippingMethodRouter, passes the shipments to the shipping component, and runs the component. The individual shipping components calculate the total shipping charges for the shipments passed to it. When all of the shipments have been processed, the ShippingMethodRouter component calculates the total of all of the shipping charges.

The ShippingMethodRouter component instantiates only the components it will use.

See Also

Multiple-shipment Shipping Architecture

Shipping Object

ShippingDiscountAdjust

ShippingManagerCache

ShippingMethodManager Object

StepwiseShipping


SimpleCanadaTax

Use this component to calculate the Canadian Goods and Services Tax (GST) and Provincial Sales Tax (PST).

Note

  • The SimpleCanadaTax component is a Site Server 3.0 Commerce Edition sample tax component. The SampleRegionalTax component is the sample tax component for Commerce Server 2000. Because all tax components in the product are intended only as samples, Microsoft strongly recommends that you have an independent tax professional verify all applicable tax rates and data generated by this component before you use such information for personal or business purposes.

Intended use: Order Processing pipeline, Tax stage.

Configuration Values

You can determine how the SimpleCanadaTax component calculates the tax by setting component properties. Use the following boxes on the Simple Canada Tax tab of the Component Properties dialog box to determine this information.

Box | Description
Apply when | Determines when to apply the tax. The values are: Always Default. Specifies that the tax is always applied to the order. Equal to country Specifies that the tax should be applied when the value of the ship_to_country key in the Order dictionary is the same as the string specified in the Country box. Has any value Specifies that the tax is applied when the ship_to_country key of the order has any non-null value.
Country | The string to compare to the ship_to_country key in the order.
GST Item Key | The key in the order form whose value is the GST rate.
PST Item Key Prefix | A prefix that the SimpleCanadaTax component prepends to the name of the province to which the item is being shipped (from the ship_to_state key in the order form). The component uses this concatenated string to look up the PST rate on the order form.
Province List | The space-separated list of provinces for which to compute the tax.

Values Read

The SimpleCanadaTax component reads the following values from the indicated dictionaries.

Key | Dictionary | Description
item._oadjust_adjustedprice | Order | The total cost for an item.
ship_to_state | Order | The state to ship to.
item._product_gst | Order | Dynamic. Default shown. The GST for an item. The key name is determined by the value in the GST Item Key configuration box.
item._product_pst__* | Order | Dynamic. Default shown. The PST for an item in a given province. The province abbreviation is appended to the name and should match one in the Province List box. The key name is determined by the value in the PST Item Key Prefix configuration box.
ship_to_country | Order | The country to ship to.

Values Written

The SimpleCanadaTax component assigns values to the following keys in the Order dictionary.

Key | Description
item._tax_total | The total tax for items with this stockkeeping unit (SKU).
item._tax_included | The amount of tax included in the cost of the item.
_tax_total_gst | The total GST for the order.
_tax_total_pst | The total PST for the order.
_tax_total | The total tax for this order.
_tax_included | The amount of tax included in the cost of the order.

Remarks

GST is common throughout Canada and almost all goods and services have a GST. If a product is taxed, the GST rate is the same throughout Canada. However, some products are not taxed and some service merchants (making less than a given amount) may elect not to charge GST. Each province has its own PST, usually a fixed rate for all products, but the PST rate still depends on the product (although a province may elect to tax an item not taxed by another province).

When shipping from one province to another you do not pay any PST. Although not common, a product may have a PST but not a GST. The reverse may also be true.

The data used by the SimpleCanadaTax component is usually provided by the QueryCatalogInfo or QueryProdInfoADO component. The SimpleCanadaTax component always sets the _tax_included keys to zero (0) for both the items and the order. The component does not handle fractions of base currency units. All calculations are rounded to the nearest whole unit.

The combination of the Key, Apply when, and Country boxes determine whether tax should be applied, but only if the order is being shipped to one of the provinces in the Province List box.

The SimpleCanadaTax component first checks the value in the Apply when box:

  • If it is set to Always, the tax is always applied to the order.

  • If the value in the Apply when box is set to Has any value, the tax is applied to the order whenever the order form contains any value for the ship_to_country key.

  • If the value in the Apply when box is set to Equal to Country, the component does a comparison between the value of the ship_to_country key on the order form and the text string in the Country box. If there is a match, the tax is applied.

If the component determines that tax should be applied, it compares the value of the ship_to_state key on the order form to the list of provinces specified in the Province List box. If there is a match, indicating the order is going to a province where tax is collected, the component does two things. First, it retrieves the GST rate from the field on the order form identified by the GST Item Key box. Second, it prepends the prefix specified in the PST Item Key Prefix box to the name of the province to which the item is being shipped (from the ship_to_state key on the order form). The component then uses this concatenated string to look up the PST rate on the order form.

Example

To specify that a 2% GST tax rate and a 4.5% Alberta PST rate is charged for an item shipped to Alberta, Canada, do the following (assuming that you are using the QueryProdInfoADO component to retrieve product information):

  1. Add a column for the GST rate to your product table. The tax rate should be specified as a real number:

can_prod_gst_tax_rate real NOT NULL

  2. Add a column for the Alberta PST rate to your product table. The tax rate should be specified as a real number:

can_prod_pst_tax_rate_alb real NOT NULL

  3. Assign tax rates to each product in your product table using an SQL script. For this example, assign the 2% GST tax rate and the 4.5% Alberta PST tax rate to Product ABC. Type 2.0 into the can_prod_gst_tax_rate column and 4.5 into the can_prod_pst_tax_rate_alb column in the Product ABC row.

  4. Double-click the SimpleCanadaTax icon in the Pipeline Editor and enter the following in the resulting property page:
    Box | Value
    Apply when | Has any value
    Country | CAN
    GST Item Key | _product_can_prod_gst_tax_rate
    PST Item Key Prefix | _product_can_prod_pst_tax_rate
    Province List | Alb

Note that if the user types a country or province on the order form that is not specified in the SimpleCanadaTax component configuration, the values will not be assigned to the _tax_total and _tax_included keys in the order and the items will not be set.


SimpleJapanTax

Use this component to compute taxes according to the Japanese tax model.

Note

  • The SimpleJapanTax component is a Site Server 3.0 Commerce Edition sample tax component. The SampleRegionalTax component is the sample tax component for Commerce Server 2000. Because all tax components in the product are intended only as samples, Microsoft strongly recommends that you have an independent tax professional verify all applicable tax rates and data generated by this component before you use such information for personal or business purposes.

Intended use: Order Processing pipeline, Tax stage.

Configuration Values

You can determine how the SimpleJapanTax component calculates the tax by setting component properties. Use the following boxes on the Simple Japan Tax tab of the Component Properties dialog box to determine this information.

Box | Description
Apply when | Determines when to apply the tax. The values are: Always Default. Specifies that the tax is always applied to the order. Equal to country Specifies that the tax should be applied when the value of the ship_to_country key in the Order dictionary is the same as the string specified in the Country box. Has any value Specifies that the tax is applied when the ship_to_country key of the order has any non-null value.
Country | The string to compare to the ship_to_country key in the order to determine if tax is applied.
Include Item Key | The key in the Item dictionary that indicates whether or not tax is already included in the price of the item.
Rate Item Key | The key in the item that contains the tax rate charged for the item.

Values Read

The SimpleJapanTax component reads the following values from the indicated dictionaries.

Key | Dictionary | Description
item._oadjust_adjustedprice | Order | The total cost for an item.
item._product_jpn_tax_included | Order | Dynamic. Default shown. A Boolean indicating whether tax is already included in the item cost. The key name is determined by the value in the Include Item Key configuration box.
item._product_jpn_tax_rate | Order | Dynamic. Default shown. The tax rate for an item. The key name is determined by the value in the Rate Item Key configuration box.
ship_to_country | Order | The country to ship to.

Values Written

The SimpleJapanTax component assigns values to the following keys in the Order dictionary.

Key | Description
item._tax_total | The total tax for items with this stockkeeping unit (SKU).
item._tax_included | The amount of tax included in the cost of the item.
_tax_total | The total tax for this order.
_tax_included | The amount of tax included in the cost of the order.

Remarks

The SimpleJapanTax component computes a tax rate for the Japanese tax model. It can be used for any country that uses a similar model. The component handles fractions of currency units only at the item level; order-level calculations (order._tax_total and order._tax_included) are rounded to the nearest whole unit.

The combination of the values in the Key, Apply when, and Country boxes determines whether tax should be applied, but only if tax is not already included in the price of the item.

The SimpleJapanTax component first checks the Apply when value:

  • If it is set to Always, the tax is always applied to the order.

  • If the value in the Apply when box is set to Has any value, the tax is applied to the order whenever the order form contains any value for the ship_to_country key.

  • If the value in the Apply when box is set to Equal to Country, the component compares the value of the ship_to_country key on the order form and the text string in the Country box on the property page. If they match, the component applies the tax whose value is stored in the box specified in Rate Item Key.

The key in the Include Item Key box specifies the name of the field in the Item dictionary that indicates whether tax is already included in the price of the item. This field is assumed to contain a Boolean value that indicates whether or not the tax rate is to be added to the line item (in which case the item._tax_total key is set to the tax amount and the item._tax_included key is set to zero), or whether the tax rate is included in the price (in which case the item._tax_included key is set to the tax amount and the item._tax_total key is set to zero).

Example

To specify that a 9.54% tax rate is included in the price of an item and is not included in the price of another item for items in Japan, do the following:

  1. Add a column for the included tax rate to your product table. The tax rate should be specified as a smallint number:

jpn_prod_tax_included smallint NOT NULL,

  2. Add a column for the tax rate to your product table. The tax rate should be specified as a real number:

jpn_prod_tax_rate real NOT NULL,

  3. Assign tax rates and tax included values to each product in your product table using an SQL script. This example uses two products, Product Included and Product Excluded. Assign Product Included the 9.54% tax rate with the tax included in the product price. Type 9.54 into the jpn_prod_tax_rate column and 1 (True), in the jpn_prod_tax_included column in the Product Included row. Assign Product Excluded the 9.54% tax rate with the tax not included in the product price. Type 9.54 into the jpn_prod_tax_rate column and 0 (False), in the jpn_prod_tax_included column in the Product Excluded row.

  4. Use the Pipeline Editor to enter the following in the property page of the SimpleJapanTax component:
    Box | Value
    Apply when | Has any value
    Country | JPN
    Include Item Key | _product_jpn_prod_tax_included
    Rate Item Key | _product_jpn_prod_tax_rate

If the user types a country in the order form that is not specified in the SimpleJapanTax component configuration, the _tax_total and _tax_included keys on the order and on the items will not be set.


SimpleUSTax

Use this component to apply taxes on any order sent to a specified state in the United States.

Note

  • The SimpleUSTax component is a Site Server 3.0 Commerce Edition sample tax component. The SampleRegionalTax component is the sample tax component for Commerce Server 2000. Because all tax components in the product are intended only as samples, Microsoft strongly recommends that you have an independent tax professional verify all applicable tax rates and data generated by this component before you use such information for personal or business purposes.

Intended use: Order Processing pipeline, Tax stage.

Configuration Values

You can determine how the SimpleUSTax component calculates the tax by setting component properties. Use the following boxes on the Simple United States Tax tab of the Component Properties dialog box to determine this information.

Box | Description
Apply when | Determines when to apply the tax. The values are: Always Default. Specifies that the tax is always applied to the order. Equal to country Specifies that the tax should be applied when the value of the ship_to_country key in the Order dictionary is the same as the string specified for the Country box. Has any value Specifies that the tax is applied when the ship_to_country key of the order has any non-null value.
Country | The string to compare to the ship_to_country key in the order.
State Rate List | The list of states and tax rates, in the form state:rate, with state as the two-character postal code abbreviation and rate expressed as a decimal value. For example WA:8.6 is an 8.6% tax rate for the state of Washington. Multiple state and rate pairs are separated by spaces.

Values Read

The SimpleUSTax component reads the following values from the indicated dictionaries.

Key | Dictionary | Description
ship_to_state | Order | The state to ship to.
item._oadjust_adjustedprice | Order | The total cost for an item.
ship_to_country | Order | The country to ship to.

Values Written

The SimpleUSTax component assigns values to the following keys in the Order dictionary.

Key | Description
item._tax_total | The total tax for items with this stockkeeping unit (SKU).
item._tax_included | The amount of tax included in the cost of the item.
_tax_total | The total tax for this order.
_tax_included | The amount of tax included in the cost of the order.

Remarks

The SimpleUSTax component calculates state taxes within the United States.

The combination of the values in the Key, Apply when, and Country boxes determine whether tax is applied, but only if the state to which the order is shipped appears in the State Rate List box.

The SimpleUSTax component first checks the Apply when value:

  • If it is set to Always, the tax is always applied to the order.

  • If the value in the Apply when box is set to Has any value, the tax is applied to the order whenever the order form contains any value for the ship_to_country key.

  • If the value in the Apply when box is set to Equal to Country, the component does a comparison between the value of the ship_to_country key on the order form and the text string in the Country box on this property page. If there is a match, the component applies the tax.

If the component determines that tax should be applied, it then compares the value of the ship_to_state key on the order form to the list of states specified in State Rate List box. If there is a match, indicating that the order is being shipped to a state where tax should be collected, the component applies the tax rate for that state, and sets the values for the item._tax_total, item._tax_included, order._tax_total, and order._tax_included keys.

The SimpleUSTax component always assigns zero (0) to the _tax_included keys for both the item and the order. The component does not handle fractions of base currency units; all calculations are rounded to the nearest whole unit.

If the user types a country or state in the order form that is not specified in the SimpleUSTax component configuration, the values of the _tax_total and _tax_included name/value pairs on the order and on the items will not be set.

You can enter an at sign (@) (the wildcard character) to represent all states that are not explicitly listed (for example: @:0).


SimpleVATTax

Use this component to calculate a Value Added Tax (VAT).

Note

  • The SimpleVATTax component is a Site Server 3.0 Commerce Edition sample tax component. The SampleRegionalTax component is the sample tax component for Commerce Server 2000. Because all tax components in the product are intended only as samples, Microsoft strongly recommends that you have an independent tax professional verify all applicable tax rates and data generated by this component before you use such information for personal or business purposes.

Intended use: Order Processing pipeline, Tax stage.

Configuration Values

You can determine how the SimpleVATTax component calculates the tax by setting component properties. Use the following boxes on the Simple VAT Tax tab of the Component Properties dialog box to determine this information.

Box | Description
Apply when | Determines when to apply the tax. The values are: Always Default. Specifies that the tax is always applied to the order. Equal to country Specifies that the tax should be applied when the value of the ship_to_country key in the Order dictionary is the same as the string specified for Country box. Has any value Specifies that the tax is applied when the ship_to_country key of the order has any non-null value.
Country | The string to compare to the ship_to_country key in the order to determine if tax is applied.
Rate Item Key | The key in the item that contains the tax rate charged for the item.

Values Read

The SimpleVATTax component reads the following values from the indicated dictionaries.

Key | Dictionary | Description
item._oadjust_adjustedprice | Order | The total cost for an item.
item._product_tax_rate | Order | Dynamic. Default shown. The tax rate for the product. The key name is determined by value in the Rate Item Key configuration box.

Values Written

The SimpleVATTax component assigns values to the following keys in the Order dictionary.

Key | Description
item._tax_total | The total tax for items with this stockkeeping unit (SKU).
item._tax_vat_item | The VAT for the item.
item._tax_included | The amount of tax included in the cost of the item.
_tax_total | The total tax for this order.
_tax_included | The amount of tax included in the cost of the order.

Remarks

The SimpleVATTax component calculates simple Value Added Tax (VAT).

The SimpleVATTax component always assigns zero (0) to the _tax_total keys for both the item and the order. The component does not handle fractions of currency units — all calculations are rounded to the nearest whole unit.

The combination of the values in the Key, Apply when, and Country boxes determine whether tax should be applied. The SimpleVATTax component first checks the Apply when value:

  • If it is set to Always, the tax is always applied to the order.

  • If the value in the Apply when box is set to Has any value, the tax is applied to the order whenever the order form contains any value for the ship_to_country key.

  • If the value in the Apply when box is set to Equal to Country, the component does a comparison between the value of the ship_to_country key on the order form and the text string in the Country box on this property page. If there is a match, the component applies the tax whose value is stored in the field specified in Rate Item Key.

Example

To specify that a VAT tax rate of 6.5% is charged for an item in Germany, do the following:

  1. Add a column for the VAT rate in Germany to your product table. The tax rate should be specified as a real number:

ger_vat_tax_rate real NOT NULL

  2. Assign tax rates to each product in your product table using an SQL script. For this example, assign the 6.5% VAT rate to Product ABC. Type 6.5 into the ger_vat_tax_rate column in the Product ABC row.

  3. Enter the following values in the property page for the SimpleVATTax component in the Pipeline Editor:
    Box | Value
    Apply when | Always
    Country | GER
    Rate Item Key | _product_ger_vat_tax_rate

If the user types a country on the order form that is not specified in the SimpleVATTax component configuration, the values of the _tax_total and _tax_included keys in the order and in the items will not be set.


Splitter

Use this component to divide an order into groups based on a list of item keys. For example, in the Accept stage, the Splitter component can be used to divide orders by catalog and vendor; in the Shipping stage it can be used to divide an order into shipments by shipping methods and addresses.

Intended use: Order Processing pipeline, any stage.

Configuration Values

You can determine how the Splitter component divides orders by setting component properties. Use the following boxes on the OrderSplitter tab of the Component Properties dialog box to determine this information.

Box | Description
Output Structure | The name of the SimpleList object that points to the resulting dictionaries. The Splitter component creates one dictionary for each set of distinguisher values.
Input Distinguishers | A space-separated list of line item attributes (keys) to use to split the order. The defaults are the shipping_method_id and shipping_address_id keys, the distinguishers for splitting orders into multiple shipments.

Values Read

The Splitter component reads the following values from the indicated dictionaries.

Key | Dictionary | Description
CacheManager | Context | A reference to a CacheManager object. If supplied, this component will automatically look up the shipping method name and write it to the output structure if shipping_method_id is a distinguisher.
ShipmentDistinguishers | Context | Optional. An array of strings containing the line item attributes (keys) to use to split shipments. The defaults are the shipping_method_id and shipping_address_id keys. This key is used only if no values are specified in the Input Distinguishers box. For example, Dict("ShipmentDistinguishers") = "quantity shipping_address_id name shipping_method_id ...".

Values Written

The Splitter component writes the following values to the Order dictionary.

Key | Description
dynamic (what the Output Structure is set to) | (Optional) The name of the SimpleList object that points to the resulting dictionaries. The Splitter component creates one dictionary for each set of distinguisher values. The Shipments key is used only if no other key is specified in the Output Structure box.

Remarks

For information about setting up the Splitter component to divide orders into multiple shipments , see Using the Splitter to Create Multiple Shipments.

Example

With the Splitter component, you can split an order any way you want. For example, you have four line items, numbered zero (0) through three (3) with the following attributes:

shipping_method_id | shipping_address_id | shipping_date | catalog | vendor
A | Home | ASAP | A | A
A | Home | ASAP | A | A
B | Work | ASAP | B | B
A | Work | 3/1 | C | B

If you split by shipping_method_id and shipping_address_id, to an output structure called _Shipments, you will get a SimpleList object of dictionaries on your order form called "shipments" with the following entries:

shipping_method_id | shipping_address_id | ItemIndexes
A | Home | 0,1
B | Work | 2
A | Work | 3

If you split by vendor, to an output structure called _Vendors, you will get a SimpleList object of dictionaries on your order form called "_Vendors" with the following entries:

Vendor | ItemIndexes
A | 0,1
B | 2,3

See Also

Shipping Object

Shipping Objects

ShippingDiscountAdjust

ShippingManagerCache

ShippingMethodManager Object

ShippingMethodRouter

StepwiseShipping


SQLItemADO

Use this component to run a query for each item in an order form.

Intended use: Order Processing pipeline, Accept stage.

Configuration Values

You can determine the query the SQLItemADO component runs by setting component properties. Use the following boxes on the SQL Item (ADO) tab of the Component Properties dialog box to determine this information.

Box | Description
Connection String | The connection string to connect to the database. This may be a full connection string or a name in a connection map. If blank, the default connection string is used.
Query | The full SQL text of the query this component will execute, or the name of a query whose full SQL text is defined in the Global.asa file in the QueryMap key.
Parameter List | The parameters the component passes to the query. Separate multiple parameters with a single space. The following are the allowed parameters: count Passes the query the number of line items on the order. index Give the query the zero-based index number of this line item. order.fieldname Passes the value of the specified field in the order form. item.fieldname Passes the value of the specified field in the Item dictionary. sum.fieldname The query receives the sum of a particular field on the order. sumq.fieldname Passes the sum times the respective quantities.

Values Read

The SQLItemADO component reads the following values from the indicated dictionaries.

Key | Dictionary | Description
DefaultConnectionString | Context | Optional. The key in the Application dictionary containing the default query string.
ConnectionStringMap | Context | Optional. The map in which to look up the name of a mapped connection string.
QueryMap | Context | Optional. A reference to a dictionary containing a query map.

Values Written

None.

Remarks

The SQLItemADO component runs a query for each item in the items list, passing the specified order form fields as parameters to the query. These fields can include keys from either the Order or the Item dictionary.

The connection string must include either the full connection string (the data source name (DSN), database login ID, and database password) or the name of a named connection stored in the connection map.


SQLOrderADO

Use this component to run a single SQL query on an order, passing order parameters to the query.

Intended use: Order Processing pipeline, Accept stage.

Configuration Values

You can determine the query the SQLOrderADO component runs by setting component properties. Use the following boxes on the SQL Order (ADO) tab of the Component Properties dialog box to determine this information.

Box | Description
Connection String | The connection string to connect to the database. This may be a full connection string or a name in a connection map. If blank, the default connection string is used.
Query | The full SQL text of the query this component will execute, or the name of a query whose full SQL text is defined in the Global.asa file in the QueryMap key.
Parameter List | The parameters the component passes to the query. Separate multiple parameters with a single space. The following are the allowed parameters: count Passes the query the number of line items on the order. order.fieldname Passes the value of the specified field in the order form. sum.fieldname The query receives the sum of a particular field on the order. sumq.fieldname Passes the sum times the respective quantities.
Child Object Name | The name of a field that receives the data. The component uses the field only if the Use Child Object check box is selected.
Use Child Object | Indicates whether or not the component is to use the object specified in the Child Object Name box. If the check box is not selected, the component assumes there is no child object.

Values Read

The SQLOrderADO component reads the following values from the indicated dictionaries.

Key | Dictionary | Description
DefaultConnectionString | Context | Optional. The key in the Application dictionary containing the default connection string.
ConnectionStringMap | Context | Optional. The map in which to look up the name of a mapped connection string.
QueryMap | Context | Optional. A reference to a dictionary containing a query map.

Values Written

None.

Remarks

The SQLOrderADO component runs a SQL query once per order, passing the specified order parameters to the query. The component uses ActiveX Data Objects (ADO) to interface with the data source, and therefore supports COM+ transactions.

The connection string must include either the full connection string (the data source name (DSN), database login ID, and database password) or the name of a named connection stored in the connection map.


StepwiseShipping

Use this component in the multiple-shipment shipping architecture to calculate shipping costs for shipments. The StepwiseShipping component can handle charging for shipping by weight, by quantity, or by price.

Note

  • This component should never be inserted directly in a pipeline; it is run by the ShippingMethodRouter component.

Configuration Values

The ShippingMethodRouter component sets the following value in the Configuration dictionary before executing the StepwiseShipping component.

Key | Description
mode | The shipping calculation mode. The options are: 0 Use subtotal to calculate shipping. 1 Use quantity to calculate shipping. 2 Use weight to calculate shipping.

Values Read

The StepwiseShipping component reads the following values from the indicated dictionaries.

Key | Dictionary | Description
TransactionConfigConnectionString | Context | The data connection string to the database containing the shipping rates.
shipments_to_process | Context | A SimpleList object of the shipments to process. Each shipment is represented by a dictionary.

The StepwiseShipping component also reads the following values for each item in each Shipment dictionary in the shipments_to_process SimpleList object.

Key | Description
_product_weight | Optional. The weight of an individual item. Needed only if weight is used to calculate shipping.
quantity | Optional. The quantity of an individual item. Needed only if quantity is used to calculate shipping.
_cy_oadjust_adjustedprice | Optional. The subtotal for an item. Needed only if the subtotal is used to calculate shipping.

Values Written

The StepwiseShipping component writes the following values to the Order dictionary.

Key | Description
shipments._cy_shipping_total | The shipping charges for each individual shipment.

Remarks

The StepwiseShipping component goes through the list of shipments. For each shipment, it retrieves the shipping rate from the shipping rate table, and calculates the shipping according to the mode specified.

If you use weight to calculate shipping, all items must have a weight or the component returns an error.

See Also

Shipping Object

ShippingDiscountAdjust

ShippingManagerCache

ShippingMethodManager Object

ShippingMethodRouter


TableHandlingADO

Use this component to set the handling total on an order based on values retrieved from the database.

Intended use: Order Processing pipeline, Handling stage.

Configuration Values

You can determine when the TableHandlingADO component calculates the handling charge by setting component properties. Use the following boxes on the Table Handling (ADO) tab of the Component Properties dialog box to determine this information.

Box | Description
Apply when Determines when to apply the handling charge. The values are:

Always

Default. Specifies that the handling charge is always applied to the order.

Equal to method

The handling charge should be applied when the value of shipping_method key in the Order dictionary is the same as the string specified in the Method box.

Has any value

Specifies that the handling charge should be applied when the shipping_method key of the order has any non-null value.
Method | The shipping method to match against the value of the shipping_method key in the Order dictionary. Used when the value in the Apply when box is set to the value in the Equal to method box.
Connection String | The connection string to connect to the database. This may be a full DSN or a name in a connection map. If blank, the default connection string is used.
Query | The full SQL text of the query this component will execute, or the name of a query whose full SQL text is defined in the Global.asa file in the QueryMap key.
Parameter List The parameters the component passes to the query. Separate multiple parameters with a single space. The following are the allowed parameters:

count

Passes the query the number of line items on the order.

order.fieldname

Passes the value of the specified field in the order form.

sum.fieldname

The query receives the sum of a particular field on the order.

sumq.fieldname

Passes the sum times the respective quantities.
Column | The name of the column in the database containing the handling charge.

Values Read

The TableHandlingADO component reads the following values from the indicated dictionaries.

Key | Dictionary | Description
shipping_method | Order | Optional. The shipping method as a string.
DefaultConnectionString | Context | Optional. The key in the Application dictionary containing the default query string.
ConnectionStringMap | Context | Optional. The map in which to look up the name of a mapped connection string.
QueryMap | Context | Optional. A reference to a dictionary containing a query map.

Values Written

The TableHandlingADO component assigns a value to the following key in the Order dictionary.

Key | Description
_handling_total | The total cost for handling the order.

Remarks

The TableHandlingADO component sets the value of the _handling_total key on the order form using values retrieved from the database.

The combination of the the values in the Apply when and Method boxes determine whether or not the handling charge is applied to the order.

The TableHandlingADO component first checks the Apply when value. If it is set to Always, the handling charge is always applied to the order. If the value in the Apply when box is set to Has any value, the handling charge is applied to the order whenever the order form contains any value for the shipping_method key. If the value in the Apply when box is set to Equal to Method, the component does a comparison between the value of the shipping_method key on the order form and the text string in the Method box on this property page. If there is a match, the handling charge is applied.

If the component determines that the handling charge should be applied, it executes the query specified in the Query box. The query retrieves the handling charge from the database column specified in the Column box. The component then computes the handling charge.

The connection string must include either the full connection string (the data source name (DSN), database login ID, and database password) or the name of a named connection stored in the connection map.


TableShippingADO

Use this component to set the total shipping on an order by using values retrieved from the database.

Intended use: Order Processing pipeline, Shipping stage.

Configuration Values

You can determine when the TableShippingADO component calculates the handling charge by setting component properties. Use the following boxes on the Table Shipping (ADO) tab of the Component Properties dialog box to determine this information.

Field | Description
Apply when Determines when to apply the shipping charge. The values are:

Always

Default. Specifies that the shipping charge is always applied to the order.

Equal to method

The shipping charge should be applied when the value of the shipping_method key in the Order dictionary is the same as the string specified in the Method box.

Has any value

Specifies that the shipping charge should be applied when the shipping_method key of the order has any non-null value.
Method | The shipping method to match against the value of the shipping_method key in the Order dictionary. Used when the value in the Apply when box is set to the value in the Equal to method box.
Connection String | The connection string to connect to the database. This may be a full connection string or a name in a connection map. If blank, the default connection string is used.
Query | The full SQL text of the query this component will execute, or the name of a query whose full SQL text is defined in the Global.asa file in the QueryMap key.
Parameter List The parameters the component passes to the query. Separate multiple parameters with a single space. The following are the allowed parameters:

count

Passes the query the number of line items on the order.

order.fieldname

Passes the value of the specified field in the order form.

sum.fieldname

The query receives the sum of a particular field on the order.

sumq.fieldname

Passes the sum times the respective quantities.
Column | The name of the column in the database containing the handling charge.

Values Read

The TableShippingADO component reads the following values from the indicated dictionaries.

Key | Dictionary | Description
shipping_method | Order | Optional. The shipping method as a string.
DefaultConnectionString | Context | Optional. The key in the Application dictionary containing the default query string.
ConnectionStringMap | Context | Optional. The map in which to look up the name of a mapped connection string.
QueryMap | Context | Optional. A reference to a dictionary containing a query map.

Values Written

The TableShippingADO component assigns a value to the following key in the Order dictionary.

Key | Description
_handling_total | The total cost for handling the order.

Remarks

The TableShippingADO component sets the value of the _shipping_total key on the order form using values retrieved from the database.

Be sure to remove the DefaultShipping component from the pipeline if you use the TableShippingADO component.

The combination of the values in the Key, Apply when, and Method boxes determine whether the shipping charge should be applied to the order.

The TableShippingADO component first checks the Apply when value. If it is set to Always, the shipping charge is always applied to the order. If the Apply when value is set to Has any value, the shipping charge is applied to the order whenever the order form contains any value for the shipping_method key. If the value in the Apply when box is set to the value in the Equal to Method box, the component does a comparison between the value of the shipping_method key on the order form and the text string in the Method box on this property page. If there is a match, the shipping charge is applied.

If the component determines that the shipping charge should be applied, it executes the query specified in the Query box, which retrieves the shipping charge from the database column specified in the Column box. The component then computes the shipping charge.

The value in the Parameter List box is used to specify parameters to the query, which usually includes a basis for the table lookup. The basis can be total cost of the order, or a merchant-defined value such as weight.

The following table illustrates some useful values for the Basis Item Key box.

Example Basis Item Key | Result
order._oadjust_subtotal | The subtotal on the order form.
sum.quantity | The sum of all quantities (total number of items ordered).
sum._oadjust_adjustedprice | The sum of adjusted prices.
sumq._iadjust_currentprice | The sum of current price times quantity for all items in the order.
sumq._product_weight | The total weight of order. (Assumes that the weight column exists in the product table, and that the query used by the QueryProdInfoADO component includes this field.)

For example, if the sumq._product_weight key is specified, and if the order has two items, one item weighing 2 pounds with a quantity of 3 and the other item weighing 4 pounds with a quantity of 1, then the basis value is 10 pounds.


ThrottleDMLPerformance

Use this component to control the speed the pipeline processes direct mail messages. This controls the load on the Simple Mail Transfer Protocol (SMTP) server.

Intended use: Direct Mailer pipeline, Throttle stage.

Configuration Values

None.

Values Read

The ThrottleDMLPerformance component reads the following values from the indicated dictionaries.

Key | Dictionary | Description
delay_msec | Context | The delay between messages in milliseconds.

Values Written

None.

Remarks

An SMTP server can be overwhelmed by receiving too many messages at a time. For this reason, a direct mail pipeline may need to slow down delivery of messages to the server.

The ThrottleDMLPerformance component simply waits the number of milliseconds specified by the delay_msec key. The Direct Mailer service calculates the delay needed to maintain an appropriate delivery rate. It then sets the delay_msec value in the Context dictionary, which is read by the ThrottleDMLPerformance component.

See Also

AddAttachments

ComposeDMLMessage

CreateUPMCookie

SendPrecomposedMessage

VerifyMessageBody

VerifyRecipientData


ValidateCCNumber

Use this component to check the expiration date of a credit card and to perform a checksum test on the number. Checksum testing ensures that the format of the number is correct; it does not verify the validity of the account.

Intended use: Order Processing pipeline, Payment stage.

Configuration Values

You can determine when the ValidateCCNumber component checks the credit card by setting component properties. Use the following boxes on the Validate CC tab of the Component Properties dialog box to determine this information.

Box | Description
Apply when Determines when to apply the credit card check. The values are:

Always

Default. Specifies that the format of the credit-card number is always checked.

Equal to method

Specifies that the format of the number should be checked when the value of the payment_method key in the Order dictionary is the same as the string specified for the Method box.

Has any value

Specifies that the format of the number should be checked when the payment_method key of the order has any non-null value.
Method | The payment method to match against the value of the payment_method key in the Order dictionary. Used when the value in the Apply when is set to Equal to method box.

Values Read

The ValidateCCNumber component reads the following values from the indicated dictionaries.

Key | Dictionary | Description
_cc_number | Order | The credit card number.
_cc_expmonth | Order | The expiration month as a string.
_cc_expyear | Order | The expiration year as a string.
cc_type | Order | The type of the credit card as a string. Must be one of the following six types: MasterCard, MC, VISA, Discover, American Express, AMEX. No other type will be validated.
MessageManager | Context | A reference to a MessageManager object, which uses the invalid credit card error constant (pur_badcc) to retrieve an error message.

Values Written

The ValidateCCNumber component writes the following values to the Order dictionary.

Key | Description
_Purchase_Errors | Error messages are written to this SimpleList object.

Errors

The ValidateCCNumber component returns error level 2 (OPPERRORLEV_WARN) when an error occurs.

The component writes error messages to the _Purchase_Errors collection. The component uses a MessageManager object to retrieve user warning message text.

Constant | Condition
pur_badcc | The credit card has expired or has a bad number.

Remarks

The ValidateCCNumber component first determines whether the credit card type specified in the order.cc_type key is one of the types accepted by this component. Accepted types are VISA, MasterCard, American Express, Discover, and the abbreviations MC and AMEX.

The ValidateCCNumber component checks the values stored in the order._cc_expmonth and order._cc_expyear keys to confirm that the credit card has not expired.

If the card is an accepted type, the component then runs a checksum on the number stored in the order._cc_number key to ensure that the number is properly formed. For example, if the specified credit card type is Discover, a well-formed number must begin with a 3 and must consist of 16 digits.

See Also

MessageManager Object


VerifyMessageBody

Use this component to check the body of a direct mail message.

Although the component appears as VerifyMessageBody in the Pipeline Editor, its ProgID is Commerce.DMLVerifyMessageBody.

Intended use: Direct Mailer pipeline, Send E-mail stage.

Configuration Values

None.

Values Read

The VerifyMessageBody component reads the following values from the indicated dictionaries.

Key | Dictionary | Description
rcp_bypass | Order | Boolean. The component bypasses (skips) processing if True.
user_flags | Order | A bit mask indicating elements of the message to check. Only the rightmost bit is currently used.
cdo_result | Order | The result code (an HRESULT) from the most recent Collaboration Data Objects (CDO) for Microsoft Windows 2000 operation.
cdo_message | Context | A reference to the CDO message object (CDO.Message).

Values Written

The VerifyMessageBody component writes the following values to the Order dictionary.

Key | Description
rcp_bypass | Boolean. Set to True so that other components will bypass further processing if errors exist.

Remarks

The VerifyMessageBody component checks the message body according to a set of user flags (user_flags). In the current component, only the rightmost bit is tested. If set (1), the component ensures that the message body is not blank. If the user flag is not set, or if the cdo_result key is not equal to S_OK, the component does nothing.

The component also checks for attachments and for the correct number of attachments.

If the body is blank and there are no attachments, the component sets the rcp_bypass key to True.

See Also

AddAttachments

ComposeDMLMessage

CreateUPMCookie

SendPrecomposedMessage

ThrottleDMLPerformance

VerifyRecipientData


VerifyRecipientData

Use this component to check the data about the recipient of a direct mail message.

Although the component appears as VerifyRecipientData in the Pipeline Editor, its ProgID is Commerce.DMLVerifyRecipientdata.

Intended use: Direct Mailer pipeline, Preprocess Recipient stage.

Configuration Values

None.

Values Read

The VerifyRecipientData component reads the following values from the indicated dictionaries.

Key | Dictionary | Description
rcp_bypass | Order | Boolean. The component bypasses (skips) processing if True.
rcp_email | Order | The e-mail address of the recipient.
rcp_formatting | Order | Numeric. The format for the message. The options are: 0 Default formatting 1 Plain text 2 MIME 3 MHTML This key overrides the default format.
default_formatting | Context | Optional. Numeric. The default formatting for the message. The values are: 0 Default formatting 1 Plain text 2 MIME 3 MHTML

Values Written

The VerifyRecipientData component writes the following values to the Order dictionary.

Key | Description
rcp_bypass | Boolean. This key is set to True if there is a problem with the recipient data. This will make subsequent components skip or bypass this recipient.

Remarks

The VerifyRecipientData component checks multiple values in the pipeline dictionaries to verify data about the recipient. If any one of the checks fails, the component sets the rcp_bypass key to True so that subsequent components in the pipeline skip the recipient.

The component performs the following checks:

  • Tests the rcp_bypass key to see if it is True on entry. If True, the component does nothing further.

  • Ensures that the e-mail address key (rcp_email) is present and has a value.

  • Tests the formatting code (rcp_formatting) to see if it is empty. If empty, the component uses the default formatting.

  • Tests the formatting against text, MIME, or MHTML.

The VerifyRecipientData component does not check any of the personalization information. The direct mail sender must verify this data.

See Also

AddAttachments

ComposeDMLMessage

CreateUPMCookie

SendPrecomposedMessage

ThrottleDMLPerformance

VerifyMessageBody


OLE DB Provider for Commerce Server

An OLE DB provider is a COM component that accepts calls to the OLE DB API and processes that request against the data source. OLE DB Provider for Commerce Server provides two distinct paths of functionality. The Fastload property passed in the connection string determines which of these functionalities is used.

The Profiling System is mainly concerned with single insertions and queries and the ability of the provider to aggregate profile data across multiple data stores.

The Data Warehouse concentrates on bulk insertion and the ability of the provider to automatically instantiate the parent classes when a child class is created.

This section contains:

  • Data. Describes the data types and their formats supported by OLE DB Provider for Commerce Server.

  • OLE DB Interface Support. Lists the supported OLE DB 2.5 objects and interfaces.

  • Data Warehouse, Analysis, and OLE DB Provider. Describes the functionalities of OLE DB Provider for Commerce Server as they are used by the Data Warehouse and Analysis.

  • Profiling System and OLE DB. Describes the functionalities of OLE DB Provider for Commerce Server as they are used by the Profiling System.

See Also

Code to Perform Bulk Operations using ADO and SQL

Data Warehouse Schema

Working with the Data Warehouse


Data

The following topics describe the supported data types and their formats.

  • DateTime Format

  • Strings

  • Supported Data Types

DateTime Format

ActiveX Data Objects (ADO), OLE DB, and Open Database Connectivity (ODBC) applications should use the following escape clauses when specifying dates for input to INSERT and UPDATE statements. Use the 24-hour time format; do not use A.M or P.M to indicate morning or evening.

  • {ts 'YYYY-MM-DD [HH:MM:SS.FFF]'}, for example, {ts '2000-10-31 23:59:59.999'}

  • {d 'YYYY-MM-DD'}, for example, {d '2000-10-31'}

  • {t 'HH:MM:SS'} for example, {t '23:59:59'}

For further information, see Writing International Transact-SQL Statements in SQL Books Online.

On import, if one member of a multi-valued DateTime member is invalid, none of the DateTime members are imported.

Strings

The Commerce database supports strings of 4000 characters. Since the Data Warehouse only supports strings of 512 characters, any string consisting of more than 512 characters will be truncated to 512 characters when it is imported.

For multi-valued strings, the count includes one additional character (the semi-colon) per element, the length of the integer specifying the number of elements, plus one.

Supported Data Types

The following table contains the valid data types supported by OLE DB Provider for Commerce Server. The Support column specifies whether the data type is supported by the Data Warehouse, the Profiling System, or both. Binary data is not supported by the Data Warehouse, but is supported by the Profiling System in the following contexts:

  • Access by means of a ProfileService object or a Recordset object.

  • Modification by means of a ProfileService object or a Record object.
TypeName | Support | Description
BINARY | Profiling System | Binary
BOOL | Both | Boolean (0 or 1)
CURRENCY | Both | 64-bit currency
DATE | Both | Standard date
DATETIME | Both | SQL Date-time
FILETIME | Data Warehouse | Standard file date/time stamp
FLOAT | Profiling System | 4-byte floating point number
IDENTITY | Data Warehouse | 48-bit numerical identifier
IDENTITY6 | Data Warehouse | 48-bit numerical identifier
IMAGE | Profiling System | 128 KB binary data
INT64 | Data Warehouse | 64-bit integer
LONG | Data Warehouse | 32-bit integer
LONGREAL | Data Warehouse | 64-bit floating point number
LONGTEXT | Profiling System | Unicode string of length 4000 characters
None | Data Warehouse | Empty type
NULL | Data Warehouse | No value
NUMBER | Profiling System | 4-byte integer
REAL | Data Warehouse | 32-bit floating point number
SHORT | Data Warehouse | 16-bit integer
STRING | Profiling System | Standard string
TIME | Data Warehouse | Standard time
UINT64 | Data Warehouse | 64-bit unsigned integer
ULONG | Data Warehouse | 32-bit unsigned integer
UUID | Data Warehouse | Packed decimal number used for globally unique identifiers (GUID)
WORD | Data Warehouse | 16-bit unsigned integer
WSTR | Data Warehouse | Unicode string of length 255
WSTR8, WSTR12. WSTR16, WSTR24, WSTR32, WSTR48, WSTR64, WSTR80, WSTR96, WSTR112, WSTR128, WSTR144, WSTR160, WSTR255, WSTR400, WSTR512 | Data Warehouse | Unicode string of designated length
WSTR1K, WSTR2K, WSTR4K | Profiling System | Unicode string of designated length


OLE DB Interface Support

The following table lists the OLE DB 2.5 objects and interfaces that are supported by OLE DB Provider for Commerce Server.

Object | Interface | Support
Binder | IBindResource | Yes
 | ICreateRow | Yes
 | IDBBinderProperties | Yes
 | ISupportErrorInfo | No
Command | IAccessor | Yes
 | IColumnsInfo | No
 | IColumnsRowset | No
 | ICommand | Yes
 | ICommandPersist | No
 | ICommandPrepare | No
 | ICommandProperties | Yes
 | ICommandText | Yes
 | ICommandWithParameters | No
 | IConnectionPointContainer | No
 | IConvertType | No
 | IDBAsynchStatus | No
 | IDBInitialize | No
 | ISupportErrorInfo | No
Data Source | IConnectionPointContainer | No
 | IDBAsynchStatus | No
 | IDBCreateSession | Yes
 | IDBDataSourceAdmin | No
 | IDBInfo | No
 | IDBInitialize | Yes
 | IDBProperties | Yes
 | IDBResetProperties | No
 | IPersist | Yes
 | IPersistFile | No
 | ISupportErrorInfo | Yes
Error | IErrorInfo | Yes
 | IErrorRecords | Yes
Multiple Results | IMultipleResults | Yes
Row | IColumnsInfo | Yes
 | IColumnsInfo2 | Yes
 | IConnectionPointContainer | No
 | IConvertType | Yes
 | ICreateRow | Yes
 | IDBAsynchStatus | No
 | IDBInitialize | No
 | IGetSession | Yes
 | IRow | Yes
 | IRowChange | Yes
 | IRowSchemaChange | No
 | IScopedOperations | No
 | ISupportErrorInfo | No
Rowset | IAccessor | Yes
 | IChapteredRowset | No
 | IColumnsInfo | Yes
 | IColumnsRowset | No
 | IConnectionPointContainer | No
 | IConvertType | Yes
 | IDBAsynchStatus | No
 | IDBInitialize | No
 | IGetRow | No
 | IRowset | Yes
 | IRowsetChange | No
 | IRowsetChapterMember | No
 | IRowsetFind | No
 | IRowsetIdentity | No
 | IRowsetIndex | No
 | IRowsetInfo | Yes
 | IRowsetLocate | No
 | IRowsetRefresh | No
 | IRowsetScroll | No
 | IRowsetUpdate | No
 | IRowsetView | No
 | ISupportErrorInfo | No
Session | IAlterIndex | No
 | IAlterTable | No
 | IBindResource | No
 | IConnectionPointContainer | No
 | ICreateRow | Yes
 | IDBASynchStatus | No
 | IDBCreateCommand | Yes
 | IDBInitialize | No
 | IDBSchemaRowset | No
 | IGetDataSource | Yes
 | IIndexDefinition | No
 | IOpenRowset | Yes
 | ISessionProperties | Yes
 | ISupportErrorInfo | Yes
 | ITableDefinition | No
 | ITransaction | No
 | ITransactionJoin | No
 | ITransactionLocal | No
 | ITransactionObject | No


Data Warehouse, Analysis, and OLE DB

This section describes the functionalities of OLE DB Provider for Commerce Server as it is used by the Data Warehouse and Analysis.

This section contains:

  • Bind URLs. Describes the commands used to bind to a Row object.

  • Connection Strings for the Data Warehouse. Describes the connection strings recognized by OLE DB Provider for Commerce Server.

  • Delete Syntax. Describes the syntax for deleting data from the Data Warehouse.

  • Schema Change. Describes the steps needed to commit a change to the Data Warehouse logical schema.


Bind URLs

OLE DB Provider for Commerce Server implements a Binder object that supports direct binding to the OLE DB Row object using the Uniform Resource Locator (URL) naming convention.

The following table lists the custom bindable URLs. Note that "ClassNames" is both the name of a URL and the name of a field in the returned record.

URL | Description
ClassNames | Returns a record with a ClassNames field which contains a collection of all the class names.
DimensionNames | Returns a record with a ClassNames field which contains a collection of all the dimension class names.
FactNames | Returns a record with a ClassNames field which contains a collection of all the fact class names.
RelationNames | Returns a record with a ClassNames field which contains a collection of all the class relation names.

Example

The following Microsoft Visual Basic example displays the name of each fact class. This functionality is not available in Microsoft Visual Basic Scripting Edition (VBScript) because rec("ClassNames") returns an array of Strings, not an array of Variants of String type.

Dim rec, conn, savNames, sName
Set rec = CreateObject("ADODB.Record")
Set conn = CreateObject("ADODB.Connection")

conn.Open "URL=mscop://INPROCCONNECT/Server=servername:" & _
 "Database=dbname:Catalog=dwschema:fastload=true:" & _
 "user=username:password=******"

rec.Open "FactNames", conn

savNames = rec("ClassNames")

For Each sName In savNames
   MsgBox sName
Next

rec.Close
Set rec = Nothing
Set conn = Nothing


Connection Strings for the Data Warehouse

Two types of connection strings are recognized by OLE DB Provider for Commerce Server for use with the Data Warehouse:

  • "URL=mscop://InProcConnect/Server=myserver:Database=dbname:
    Catalog=DWSchema:User=userid:Password=********:FastLoad=True"

  • "Provider=commerce.dso.1;Data Source=mscop://InProcConnect/Server=myserver:
    Catalog=DWSchema:Database=dbname:User=userid:
    Password=********:FastLoad=True"

The name of the catalog must be "DWSchema".

The Fastload option must be set to True which precludes the use of binary data.


Delete Syntax

This topic describes the syntax for programmatically deleting data from the Data Warehouse.

A Data Deletion Data Transformation Services (DTS) task is provided for deleting all the data in the Data Warehouse, or for deleting Web log import data by the TaskHistoryID property. For information about the Data Deletion DTS task, see Deleting Data from the Data Warehouse.

The delete syntax format is:

   DELETE [FROM] BaseClassName
      [WITH (DELETEORPHANS | ONLYFACT | UPDATECHILDREN)]
      [WHERE where_clause]

BaseClassName

The name of the class containing the data to delete.

DELETEORPHANS

Specifies to delete any orphans produced by the delete operation. An orphan is an instance in a child class that is not referenced by any of its parent classes.

ONLYFACT

Specifies to only delete children of BaseClassName that are marked as FACT tables.

UPDATECHILDREN

Specifies to update the children, if any, of BaseClassName.

where_clause - memberpath [NOT] operator testvalue [AND where_clause]

memberpath - [BaseClassName.][pathelements]MemberName

pathelements - (ParentName|RelationToParentName).[pathelements]

ParentName - the name of the class that is a parent to the class

immediately preceeding it in memberpath

RelationToParentName - the name of the relation between the parent

and its base class

MemberName - the name of a class member from the rightmost class in

memberpath; this specifies the class member to test in where_clause

operator - one of the following operators:

= | <> | < | > | <= | <= | LIKE | IS LIKE | IS NULL | IS IN | NOT NULL
 | != | !>= | !<= | !> | !< | NOT LIKE | IS NOT LIKE | IS NOT NULL | IS NOT IN | NOT IN

testvalue - one of the following: value, IN valuelist, NULL

value - the value to test MemberName against in where_clause

valuelist - a comma delimited list of values surrounded by parentheses

Delete Syntax Example

Set cmdDel = WScript.CreateObject("ADODB.Command.2.5")

cmdDel.CommandText = "DELETE FROM Request"
cmdDel.CommandText = "DELETE FROM Request
                         WHERE RequestNum > 2"
cmdDel.CommandText = "DELETE FROM Date
                         WHERE DTimestamp > '1998-10-29 00:00:00'"
cmdDel.CommandText = "DELETE FROM Date
                         WITH UPDATECHILDREN"
cmdDel.CommandText = "DELETE FROM Date
                         WITH DELETEORPHANS"
cmdDel.CommandText = "DELETE FROM Date
                         WITH UPDATECHILDREN
                         WHERE DTimestamp > '1998-10-29 00:00:00'"
cmdDel.CommandText = "DELETE FROM Date
                         WITH DELETEORPHANS
                         WHERE Date.DTimestamp > '1998-10-29 00:00:00'"
cmdDel.CommandText = "DELETE FROM Visit
                         WHERE DTimestamp > 1998-10-29 00:00:00'"
cmdDel.CommandText = "DELETE FROM Visit
                         WHERE DTimestamp
                            IN ('1999-10-29 00:00:00',
                                '1999-10-30 00:00:00')"
cmdDel.CommandText = "DELETE FROM Request
                         WHERE Request.Loguser.IPRef.Hostname = " & _
                           "'1.1.1.1'"
cmdDel.Execute


Schema Change

To extend the logical schema, OLE DB Provider for Commerce Server must be notified by turning on the schema change mode. Changes to the existing schema are not allowed when in schema change mode. The __Commit attribute determines whether changes are persisted to intermediate tables. The CommitSchema command persists the session changes to the actual schema tables, provided all changes pass validation.

When extending the schema, perform the following steps:

  1. Turn the schema change mode on by setting the SchemaMode attribute to 1.

  2. Create a new instance in the schema table you want (ClsDef, MemDef, and so forth).

  3. Set the attributes you want.

  4. Set the persistence of the new row using the __Commit attribute.

  5. Save the changed row using the Update method.

  6. Repeat steps 2 - 5 for each additional row to be added.

  7. Commit the session changes by executing the CommitSchema command.

  8. Turn the schema change mode off by setting the SchemaMode attribute to 0 (zero).

Commit

The __Commit attribute determines whether the data inserted into a row will be persisted and when.

When setting row data in OLE DB Provider for Commerce Server in Fastload mode, the data is buffered. Two values, Flush (do not save current row) and Save and Flush, explicitly (and synchronously) flush the data to the database.

It is recommended for C++ applications that have high load requirements to use row reuse. Normally, an application will create an instance of a blank row through the OLE DB 2.6 binder interface, populate the column data, commit the data, and release the row. The Reuse Row value allows the client to reuse the same row over and over without having to release and recreate a new row.

In order to reuse rows, set the __Commit column value to 0x201 (Save with Reuse) after populating the column data for the row. If setting the __Commit column succeeds, the row column data can be re-populated and reused.

Similar to setting the __Commit attribute to 0, the Ignore value will not persist the data in the row but still allows the row to be reused.

The following table lists the valid values for the __Commit attribute, and provides a brief description of each.

Action | Value | Description
Discard | 0x00 | Discards the row.
Save | 0x01 | Saves the current row.
Flush | 0x02 | Flushes the buffers. Must be called on a row with only the __Commit column set.
Save and Flush | 0x04 | Saves the current row and flush the buffers.
Ignore | 0x100 | Makes the row non-persistent.
Reuse Row | 0x200 | Reuses the row multiple times without rebinding.


Profiling System and OLE DB

This section describes the functionalities of OLE DB Provider for Commerce Server as it is used by the Profiling System.

This section contains:

  • Aggregation Across Multiple Data Sources. Describes the ability of OLE DB Provider for Commerce Server to manipulate objects aggregated across multiple data sources.

  • Connection Strings for the Profiling System. Describes the connection strings recognized by OLE DB Provider for Commerce Server.

  • SQL Queries. Describes the subset of ANSI SQL used to manipulate objects aggregated across multiple data sources.


Aggregation Across Multiple Data Sources

This topic describes the ability of the provider to aggregate profile object data from multiple disparate data sources into a single homogeneous OLE DB Row object.

The data aggregation layer handles requests for fetching specified properties of profile object data, inserting new profile objects, deleting profile objects, updating specified properties of profile object data, and combining the results of running search queries simultaneously across multiple data stores.

The data aggregation layer provides support for the following data source types:

  • Microsoft Active Directory

  • Microsoft SQL Server 7.0

  • Line-Of-Business (LOB) store with the following support:
    • An OLE DB/Open Database Connectivity (ODBC) provider with support for a simple published subset of ANSI SQL,

    or

    • A Lightweight Directory Access Protocol version 3 (LDAPv3) compliant directory store.

The data aggregation layer is optimized for performance and scalability against Active Directory and SQL Server 7.0 stores.

The data aggregation layer is implemented as four components:

  • Aggregation layer. This layer is part of OLE DB Provider for Commerce Server itself.

  • Directory component.

  • Microsoft SQL Server 7.0 component.

  • LOB stores component.

The aggregation layer processes requests by splitting them into sub-requests appropriate to each aggregated data store and passing them to components responsible for those stores.


Connection Strings for the Profiling System

Two types of connection strings are recognized by OLE DB Provider for Commerce Server for use with the Profiling System:

  • "URL=mscop://InProcConnect/Server=myserver:Database=dbname:
    Catalog=Profile Definitions:User=userid:Password=*******"

  • "Provider=commerce.dso.1;Data Source=mscop://InProcConnect/Server=myserver:Database=dbname:
    Catalog=Profile Definitions:User=userid:Password=*******"

The URL based format is the recommended format.

The name of the catalog must be "Profile Definitions".

The Fastload option (False by default) is not used by the Profiling System.


SQL Queries

This section describes the subset of ANSI SQL language used to manipulate objects aggregated across multiple data sources.

SQL Query Syntax

Restrictions

SQL Query Syntax

The following code example shows the SQL query syntax supported by OLE DB Provider for Commerce Server:

SELECT select_list FROM class_name
   [WHERE search_condition]
   [ORDER BY order_expression]

select_list ::= * | member_name*
search_condition ::= in_exression | predicate |
                     predicate AND search_condition
in_expression ::= member_name IN ( value1, … , valueN )
predicate ::=
      member_name { = | <> | > | >= | < | <= | LIKE } value |
      member_name IS [NOT] NULL
order_expression::= member_name*

INSERT [INTO] class_name member_list VALUES value_list

member_list ::= member_name | member_name , member_list
value_list ::= value | value , value_list

UPDATE class_name SET member_value_list WHERE search_condition

member_value_list ::= member_value | member_value , member_value_list
member_value ::= member_name = value
DELETE [FROM] class_name WHERE search_condition

Restrictions

The following restrictions apply to the query syntax:

  • All members in all queries must be specified by their fully qualified names.

  • Active Directory does not support queries using the less than (<) or greater than (>) operators. For more information, see RFC 2254, "The String Representation of LDAP Search Filters".

  • Queries cannot be ordered by multiple properties when these properties are stored in Active Directory.

  • Membership Directory does not support sorting.

  • Non-printable characters are not supported.

  • The results set from a SELECT query is streamed back in the order in which the underlying data store returns the data.

  • All members in the WHERE or ORDER_BY clauses must belong to the same underlying data store. If both WHERE and ORDER_BY clauses are present, then all members in both clauses must map to the same underlying data store.

  • Only single-valued Number (Integer, Float), String, Currency or Date/Time/Datetime data types are supported in the WHERE clause.

  • LIKE clauses support wild-card searches through the '%' character only. All members in LIKE clauses must be of the String data type.

  • The semi-colon (;) is used as the delimiter for values in a multi-valued property. Thus, values in a multi-valued property must not contain a semi-colon.

  • INSERT and UPDATE commands allow multi-valued property values. The following examples illustrate the use of multi-valued properties:
    INSERT INTO UserObject (Name, Interests)
VALUES ('Joe', ('Basketball', 'Baseball'))

UPDATE UserObject
SET (Interests = ('Basketball', Baseball'))
WHERE Name = 'Joe'


Business Desk Reference

Commerce Server Business Desk provides a framework within which third party developers can add their own functionality. The different aspects of the framework can be categorized as follows:

  • A well-defined way in which new modules make themselves known.

  • A number of HTML Components (HTCs) that provide a standardized user interface for the display and manipulation of data.

  • A large number of constants, global variables, and utility routines that provide a common basis for module development.

This section provides detailed information about these different aspects of the Business Desk Framework, presented in a reference format.

For conceptual information about building a new Business Desk module, see Building Business Desk Modules.

For information about the cascading style sheets that control the look of Business Desk, see Style Sheet Reference.

This section contains:

  • XML Structures. Describes the Extensible Markup Language (XML) structures that are used with Business Desk for module and category configuration, and for HTC configuration. This includes links to the XML Reference section for details about these structures.

  • HTML Components. Describes the HTML Components that are used for data presentation and manipulation within Business Desk. Provides detailed information about the various properties, methods, and events associated with these HTCs, as well as links to the XML Reference topics describing the structure of their configuration information.

  • Include Files. Describes the include files that define the constants, global variables, and utility routines that constitute much of the Business Desk Framework. Explains when to include and when to not include each of these files.

  • Constants. Describes the constants defined in the various Business Desk include files. Defines which constants are available in client-side script and which constants are available in server-side script.

  • Global Variables. Describes the global variables defined in the various Business Desk include files. Defines which global variables are available in client-side script and which global variables are available in server-side script.

  • Utility Routines. Describes the routines defined in the various Business Desk include files. Defines which routines are available in client-side script and which routines are available in server-side script.

  • Debugging Business Desk. Describes debugging aids built into the HTCs and framework routines.


XML Structures

The Commerce Server Business Desk Framework and HTML Components (HTCs) make extensive use of Extensible Markup Language (XML) in specific, pre-defined structures. The following table briefly describes these structures and provides links to more detailed information in Business Desk XML Structures.

XML Structure | Description
Master Configuration File | The XML structure of the master configuration file that ties all other module configuration files together.
Module Configuration Files | The XML structure of the module configuration files that specify the details of each individual module.
Standard XML Data Record Format | The XML structure in which many of the HTCs expect data to be represented. These HTCs include DynamicTable, EditField, EditSheet, ListEditor, and ListSheet.
DynamicTable Configuration | The XML structure of the configuration information for the DynamicTable HTC.
EditField Configuration | The XML structure of the configuration information for one or more EditField HTCs.
EditSheet Configuration | The XML structure of the configuration information for the EditSheet HTC.
ExpressionBuilder Configuration | The XML structure of the configuration information for the ExpressionBuilder HTC.
ListEditor Configuration | The XML structure of the configuration information for the ListEditor HTC.
ListSheet Configuration | The XML structure of the configuration information for the ListSheet HTC.
QueryBuilder Configuration | The XML structure of the configuration information for the QueryBuilder HTC.
TreeView Configuration | The XML structure of the combined data and configuration information used by the TreeView HTC.


HTML Components

The Commerce Server Business Desk Framework includes a number of HTML Components (HTCs) that are used extensively by the modules that ship with Commerce Server. These same HTCs should be used in new Business Desk modules, wherever appropriate, to preserve a consistent look-and-feel within all modules.

This section contains:

  • DynamicTable. Describes the HTC used for editing tabular data where editing is limited to the columns being displayed. Record editing is performed in a special row above the column headings.

  • EditField. Describes the HTC used for editing individual items of data of various types. This control is often embedded within other tabular controls to provide the actual editing functionality for individual cells in the table.

  • EditSheet. Describes the HTC used to bundle together other HTCs that are used to edit data.

  • ExpressionBuilder. Describes the HTC used for creating named expressions that can be used for targeting. The ExpressionBuilder HTC makes use of an embedded version of the QueryBuilder HTC.

  • ListEditor. Describes the HTC used for editing tabular data where the editing of individual records occurs in a separate table below the table containing the list. The table used for record editing may allow editing of fields other than those displayed in the list table. The ListEditor HTC makes use of an embedded version of the EditSheet and ListSheet HTCs.

  • ListSheet. Describes the read-only HTC used to display a list of records and allows selection of one or more of those records for editing. The editing itself is always performed within one of the other HTCs.

  • QueryBuilder. Describes the HTC used to build a simple query.

  • TreeView. Describes the HTC used to display an expandable tree structure that provides a mechanism for both navigation and selection.


DynamicTable

The DynamicTable HTML Component (HTC) displays a table of data where each row represents a record and each column represents a particular field from the record. Above each column in the table is an EditField HTC that allows the corresponding field of the selected record to be edited. The column that is designated as the key is displayed as the first column. The remaining columns are displayed in the order that they are specified in the configuration data.

Unlike the ListEditor HTC, the DynamicTable HTC only allows the editing of data displayed in the columns of the table. Like the ListEditor HTC, the DynamicTable HTC returns its result as an XML list document.

Data is passed to the DynamicTable HTC in the form of XML data-islands. This includes the configuration data that provides, for example, the display names for data columns. It also includes the data itself, contained in a different XML data-island. Configuration data varies from HTC to HTC, depending on the specific characteristics of each type of HTC. In contrast, the data itself is essentially always the same — one or more records, each containing individual fields of data. Because of this, most of the HTCs accept data in the same generalized format. For more information about this data format, see Getting Data to the Client.

Note

  • You can change the height of the DynamicTable HTC by changing a setting in the customizable style sheet file Bizdesk.css. Search for the style setting ".dtTableStyle DIV.dtContainer" and change the default HEIGHT setting of "70" to a value of your choice.

This section contains:

  • OverX Feature. Describes the OverX feature supported by the DynamicTable HTC.

  • Events. Describes the events supported by the DynamicTable HTC.

  • Properties. Describes the properties supported by the DynamicTable HTC.

  • Methods. Describes the methods supported by the DynamicTable HTC.

  • Container Attributes. Describes the attributes that the DynamicTable HTC expects to be set on the element in which it is contained.

  • Configuration Data. Describes the data passed to the DynamicTable HTC via the ID used as the value of the MetaXML container attribute.

  • Instantiation Example. Demonstrates how the DynamicTable HTC is instantiated in script on an Active Server Pages (ASP) page.


OverX Feature

The OverX feature of the DynamicTable HTC is primarily intended for use in the Shipping Methods module in Commerce Server Business Desk. It is a very specialized feature with severe limitations that may not make it suitable for use in other pages.

The Shipping Methods module in Business Desk uses a special row in the shipping method data table to compute the shipping charges in cases where the key value is larger than the highest set value for all rows.

For example, a shipping method that sets the shipping rate by the subtotal of the order could have the following rates:

  • $.50 for subtotals from $0 to $5.00

  • $2.00 for subtotals from $5.00 to $20.00

  • $5.00 for subtotals from $20.00 to $50.00

  • $10.00 for subtotals over $50.00

The way that the over $50.00 rate is set is by using the OverX feature of the DynamicTable HTC. The "over $50.00" row subtotal value is represented in the underlying data by "-1".

The following limitations apply to this feature:

  • All fields in the OverX row are required for the DynamicTable HTC to be valid. This is because the shipping component of the Order Processing pipeline must have data in this row to function properly.

  • The OverX row will always display as the last row in the table.

  • To achieve the correct behavior with the OverX feature, the DynamicTable HTC must be set to sort by key. This is because the keys are assumed to be in ascending order, culminating in the OverX row that represents a value for all items with a key value greater than the highest key in the table.

  • When the OverX row is displayed in the control, the key field will display as "Over X", where X is the value of the last row above it in the table (or zero if there are no other rows).

  • When the XMLList object is returned from the DynamicTable HTC, the OverX row key will always contain "-1".

  • Because the OverX row is internally represented by a value of "–1", the key value for a DynamicTable HTC using the OverX feature must consist of numeric values of zero or greater. Key fields of type date, time, text, Boolean, or select are not supported when using this feature.

  • When the OverX feature is turned on, the OverX row will be added even if it is not represented in the original data passed to the control. This is because the OverX row is required.


Events

The DynamicTable HTC supports the following events:

  • OnChange

  • OnError

  • OnRequire

  • OnValid

OnChange

The OnChange event fires when the user clicks either the Done button or the Remove button.

The event object property window.event.XMLlist is a standard XMLlist object hierarchy, including the state attribute in the record elements. For more information, see XMLlist and XMLrecord Properties.

When the OverX feature is used, the OverX record key will have the value '-1'. For more information about the OverX feature, see OverX Feature.

Return to top

OnError

The OnError event fires when the HTC encounters a developer error condition. In addition, if the m_bDebug variable in the HTC is set to True, an alert box appears. This switch can be very helpful in debugging problems that occur if you get the error message "The control could not load."

The event object property window.event.error contains a string with details about the error.

Return to top

OnRequire

The OnRequire event fires whenever the list changes from required to not required, or from not required to required.

The event object property window.event.required is set to True if the required attribute of the global element in the configuration data for the HTC is set to "Yes" and there are no rows in the table display. Otherwise it is set to False.

If the OverX feature is used, the table is required even if there are rows in the table as long as the OverX row is not completely filled in. For more information about the OverX feature, see OverX Feature.

Return to top

OnValid

The OnValid event fires whenever the user starts editing a row and again when editing is complete.

The event object property window.event.valid is set to False when the event is fired because a row is being edited. When editing is complete (when either the Cancel or Accept button is clicked), the value will be True.

This assures that the HTC cannot be saved when the user is in the middle of an edit.

Return to top


Properties

The DynamicTable HTC supports the following properties:

  • dirty

  • required

  • XMLlist

dirty

The dirty property returns True if a row has been added, removed, or edited, and False otherwise.

This property is read-only.

Return to top

required

The required property returns True if the HTC is marked as required and currently has no rows in the table display, and False otherwise.

If using the OverX feature, the required property is False even when there are rows in the table display as long as the OverX row is not completely filled in. For more information about the OverX feature, see OverX Feature.

This property is read-only.

Return to top

XMLlist

The XMLlist property is a standard XMLlist object hierarchy, containing the list currently in use by the HTC, and including the state attribute in the record elements. For more information, see XMLlist and XMLrecord Properties.

This property is read-only.

Return to top


Methods

The DynamicTable HTC supports the following methods:

  • cleanup

  • field

cleanup

The cleanup method removes all records marked as deleted, as indicated by the state attribute, and clears the state attribute for all remaining records.

Example: elDynamicTable.cleanup

Return to top

field(sFieldId)

The field method retrieves a particular EditField HTC embedded within the DynamicTable HTC. The EditField HTC is identified by the required sFieldId parameter, which specifies the value of the id attribute of one of the child elements of the fields element in the MetaXML data-island.

The returned HTMLElement has an attached EditField HTC. If the parameter does not match any of the id attributes, NULL is returned.

The returned HTMLElement allows access to any of the properties or methods of the EditField HTC.

Example: set elEditField = elDynamicTable.field(sFieldId)

Return to top


Container Attributes

In order to pass data to the DynamicTable HTC, the following attributes must be set on the element that is using the DynamicTable behavior (note that this element is typically a DIV):

DataXML

The value of this attribute must be set to the value of the id attribute of the XML data-island containing the data to be displayed.

MetaXML

The value of this attribute must be set to the value of the id attribute of the XML data-island containing the configuration information for this instance of the DynamicTable HTC.


Configuration Data

The DynamicTable HTC requires that its configuration information be passed to it in the form of an XML data-island. This information consists primarily of details about each column to be displayed. For example, the type of the data in the column, the name to use in the column heading, and the element name used for the corresponding data in the DataXML data-island. In addition, there is some global configuration information, such as whether the New and Remove operations should be available.

For detailed information about the structure of this XML data-island, see DynamicTable Configuration.

For more information about the ways in which an XML document can be included on a page (creating an XML data-island), see XML Data-Islands.


Instantiation Example

The following HTML code shows a typical instantiation of a DynamicTable HTC within a DIV element. The Class attribute specifies that the DynamicTable HTC behavior be associated with this DIV element.

Note

  • In order for the Class attribute to properly identify the DynamicTable HTC, you must make sure that your pages use the Bizdesk.css style sheet.

The DataXML and MetaXML attributes specify the data and configuration data-islands, respectively, that are defined elsewhere within the document. The Language attribute specifies that the DynamicTable HTC event handlers are implemented in Microsoft Visual Basic Scripting Edition (VBScript). The remaining attributes associate methods defined elsewhere with the specific events supported by the DynamicTable HTC.

Finally, temporary text is provided to inform the user that the DynamicTable HTC is loading.

  <DIV Id='myDynamicTable'
       Class='DynamicTable'
       Language='VBScript'
       DataXML='DataIslandID'
       MetaXML='MetaDataIslandID'
       OnChange='ChangeHandler()'
       OnError='ErrorHandler()'
       OnRequire='RequireHandler()'
       OnValid='ValidHandler()'
  >Loading DynamicTable, please wait...</DIV>


EditField

The EditField HTML Component (HTC) provides a mechanism for editing simple data types. It provides validation of input according to supplied limits. EditField HTCs are used in a variety of circumstances: embedded within the DynamicTable, EditSheet, and ListEditor HTCs, or by themselves on a page. Validation of input is built into the control.

Data is passed to the EditField HTC in the form of XML data-islands. This includes the configuration data that provides, for example, minimum and maximum values for input validation. It also includes the data itself, contained in a different XML data-island. Configuration data varies slightly from HTC to HTC, depending on the specific characteristics of each type of HTC. In contrast, the data itself is essentially always the same — one or more records, each containing individual fields of data. Because of this, most of the HTCs accept data in the same generalized format. For more information about this data format, see Getting Data to the Client.

This section contains:

  • Data Types. Describes the different data types, and thus different controls, supported by the EditField HTC.

  • Events. Describes the events supported by the EditField HTC.

  • Properties. Describes the properties supported by the EditField HTC.

  • Methods. Describes the methods supported by the EditField HTC.

  • Container Attributes. Describes the attributes that the EditField HTC expects to be set on the element in which it is contained.

  • Configuration Data. Describes the data passed to the EditField HTC via the ID used as the value of the MetaXML container attribute.

  • Instantiation Example. Demonstrates how the EditField HTC is instantiated in script on an Active Server Pages (ASP) page.


Data Types

The EditField HTC presents a different user interface for editing data based on the specified type of the data. The basic type of the data is specified by the name of the element specifying the configuration information for that data. Some of the basic types also have subtypes.

The EditField HTC supports the following data/control types (and sub-types):

  • boolean

  • date

  • numeric (currency)

  • numeric (float)

  • numeric (integer)

  • select

  • text (long)

  • text (password)

  • text (short)

  • time

boolean

A box containing a check box on the left side, followed by a label indicating some condition that is True when the check box is checked and False when the check box is unchecked. Unlike the HTML check box control, which only returns a value when checked, this control always returns a 1 (one) when checked or a 0 (zero) when unchecked.

Return to top

date

A box containing a date in one of several pre-defined, configurable formats. It might also contain a prompt to enter a date. At the right end of the box is a drop-down arrow, which when pressed reveals a calendar control for picking a date. Minimum and maximum dates can be specified for use in validation checking.

Return to top

numeric (currency)

A box containing a currency value or a prompt to enter a currency value. Currency values can be input in one of several configurable formats, and illegal formats are either not accepted as input, or caught as errors. Minimum and maximum currency values can be specified for use in validation checking.

Return to top

numeric (float)

A box containing a decimal number or a prompt to enter a number. Decimal numbers can be input in one of several configurable formats, and illegal formats are either not accepted as input, or caught as errors. Minimum and maximum decimal numbers can be specified for use in validation checking.

Return to top

numeric (integer)

A box containing a whole number or a prompt to enter a number. Whole numbers can be input in one of several configurable formats, and illegal formats are either not accepted as input, or caught as errors. Minimum and maximum whole numbers can be specified for use in validation checking.

Return to top

select

A box allowing one of a number of distinct choices or containing a prompt to make a selection. At the right end of the box is a drop-down arrow, which when pressed reveals a drop-down list containing the available choices. Unlike the normal HTML select control, this control is not windowed and so can be drawn over using Dynamic Hypertext Markup Language (DHTML).

When the data does not specify an item in the list of choices, a prompt is displayed.

Return to top

text (long)

A four line, scrollable text box that allows carriage returns to be entered. A maximum length and a minimum length may be specified.

A character mask can be specified for use in validation checking to force valid input to conform to a particular format. If no character mask is provided, a default character mask is used.

The default regular expression representing long text does not allow entering '<', '>', and '&' characters:

^[^<>&]*$

Return to top

text (password)

A single line text box that does not allow carriage returns to be entered. Entered characters are displayed in the box as the asterisk ('*') so that the password remains hidden. A maximum length and a minimum length may be specified.

A character mask can be specified for use in validation checking to force valid input to conform to a particular format. If no character mask is provided, a default character mask is used.

The default regular expression representing password text does not allow entering '<', '>', and '&' characters:

^[^<>&]*$

Return to top

text (short)

A single line text box that does not allow carriage returns to be entered. A maximum length and a minimum length may be specified.

A character mask can be specified for use in validation checking to force valid input to conform to a particular format. If no character mask is provided, a default character mask is used.

The default regular expression representing short text does not allow entering '<', '>', and '&' characters:

^[^<>&]*$

Return to top

time

A box containing a time of day expressed in the 24-hour format HH:MM. It may also contain a prompt to enter a time. Minimum and maximum times can be specified for use in validation checking.

Return to top


Events

The EditField HTC supports the following events:

  • OnBrowse

  • OnChange

  • OnError

  • OnRequire

  • OnValid

OnBrowse

The OnBrowse event fires when the Browse button to the right of the input box is clicked. The Browse button will only be enabled and visible if browsing has been enabled by setting one of the two attributes onbrowse or browse.

The event object property window.event.value contains the current value of the EditField HTC.

Though any of the EditField types may be configured to have a Browse button and whatever custom browse functionality is appropriate, it is far more common to associate Browse buttons with some EditField types than with others. For example, a Boolean field is unlikely to need a Browse button.

Return to top

OnChange

The OnChange event fires whenever the value in the EditField HTC changes and loses focus. This event does not fire when the EditField HTC is disabled.

Return to top

OnError

The OnError event fires when the EditField HTC encounters a developer error condition. In addition, if the m_bDebug variable in the EditField HTC is set to True, an alert box appears. This switch can be very helpful in debugging problems that occur if you get the error message "The control could not load."

The event object property window.event.error contains a string with details about the error.

Return to top

OnRequire

The OnRequire event fires whenever the EditField HTC changes from required to not required, or from not required to required.

The event object property window.event.required is set to True if the EditField HTC is configured as required and is empty. Otherwise it is set to False. This event does not fire when the EditField HTC is hidden by setting the display style property to "none".

Return to top

OnValid

The OnValid event fires whenever the EditField HTC changes from valid to not valid, or from not valid to valid.

The event object property window.event.valid is set to True if the value in the EditField HTC is valid. Otherwise it is set to False. This event does not fire when the EditField HTC is hidden by setting the display style property to "none".

Return to top


Properties

The EditField HTC supports the following properties:

  • dirty

  • disabled

  • displayvalue

  • options

  • prompt

  • readonly

  • required

  • selected

  • valid

  • value

dirty

The dirty property tracks whether the value in the EditField HTC has changed. Legal values are True and False. A value of True indicates that the value of the EditField HTC has changed, and False indicates that the value of the EditField HTC has not changed.

This property is read-only.

Return to top

disabled

The disabled property tracks whether the EditField HTC has been disabled. Legal values are True and False. A value of True indicates that the EditField HTC has been disabled, and False indicates that the EditField HTC has not been disabled.

Disabled controls are dimmed, including both text entry and button portions of the control, if present, and input is not accepted.

This property is read/write.

Return to top

displayvalue

The displayvalue property, which should only be accessed when the type of the EditField HTC is select, contains the display name for the current value.

This property is read-only.

Return to top

options

The options property, which should only be accessed when the type of the EditField HTC is select, contains the collection of option elements (HTML Div elements) for use in iterative loops.

This property is read-only.

Return to top

prompt

The prompt property is used to set and retrieve the prompt that is displayed when the EditField HTC has no value.

Note that EditField HTCs of the select type will only display the prompt when the current value is not associated with any of the select options.

By default, the prompt property has a distinct default value for each of the EditField types. If no prompt is needed, set the prompt property to an empty string.

This property is read/write.

Return to top

readonly

The readonly property tracks whether the EditField HTC has been set to read-only. Legal values are True and False. A value of True indicates that the EditField HTC has been set to read-only, and False indicates that the EditField HTC has not been set to read-only.

The background color for read-only controls is gray, and the button portion of the control, if present, is removed.

This property is read/write.

Return to top

required

The required property tracks whether the EditField HTC requires user input. Requiring input is defined as being configured as required, but having no current value. Legal values are True and False. A value of True indicates that user input is required, and False indicates that user input is not required.

Required controls with an empty value have a yellow background color.

The OnRequire event fires whenever the value of this property changes.

This property is read-only.

Return to top

selected

The selected property, which should only be accessed when the type of the EditField HTC is select, returns the option element (HTML Div element) currently selected in the list of options.

This property is read-only.

Return to top

valid

The valid property tracks whether the current value in the EditField is valid according to constraints imposed by the configuration information. Legal values are True and False. A value of True indicates that the current value is valid, and False indicates that the current value is not valid.

Controls with a value that is not valid have a yellow background color after the control loses focus.

The OnValid event fires whenever the value of this property changes.

This property is read-only.

Return to top

value

The value property contains the value currently in the EditField, if any.

The OnChange event fires whenever the value of this property changes and the EditField HTC loses focus.

This property is read/write.

Return to top


Methods

The EditField HTC supports the following methods:

  • addItem

  • focus

  • reload

  • removeItem

  • resetDefault

addItem(sValue, sDisplayValue)

The addItem method is used to add a new option to a select drop-down list. This method should not be called unless the control type is set to select.

The required parameter sValue specifies the underlying value for the new item. The required parameter sDisplayValue specifies the display value for the new item.

This method has no return value.

Return to top

focus

The focus method sets focus to the EditField HTC and selects the contents, assuming the control is not disabled. When the EditField is of the select type, the drop-down button gets the focus and the box contents are not selected.

Similar behavior occurs when an EditField HTC is configured with the browsereadonly attribute set to "Yes" — the Browse button is given the focus and the box contents are not selected.

This method does not take any parameters and does not return any value.

Return to top

reload(sDataID)

The reload method is used to reload a different set of enumerated values in a select drop-down list. This method should not be called unless the control type is set to select.

The parameter sDataID specifies a field in the data-island specified by the MetaXML container attribute from which the new set of enumerated values should be retrieved.

This method has no return value.

Return to top

removeItem(sValue)

The removeItem method is used to remove an option from a select drop-down list. This method should not be called unless the control type is set to select.

The required parameter sValue specifies the underlying value for the item to remove.

This method has no return value.

Return to top

resetDefault

The resetDefault method is used to reset the control value to the default.

This method has no return value.

Return to top


Container Attributes

In order to pass data to the EditField , the following attributes must be set on the element that is using the EditField behavior (this element is typically a DIV):

DataXML

The value of this attribute must be set to the value of the id attribute of the Extensible Markup Language (XML) data-island containing the data to be displayed. The EditField HTC will always access and display the value of the field in the first record in the DataXML data-island.

MetaXML

The value of this attribute must be set to the value of the id attribute of the XML data-island containing the configuration information for this instance of the EditField HTC.

ID

The value of this attribute should be set to the value of the id attribute of one of the child elements of the fields element within the MetaXML data-island that corresponds to this instance of the EditField HTC.

The child element is from the set boolean, date, numeric, select, text, and time. It is the type of the element that establishes the type of the EditField HTC.

The value of the ID attribute will also be the same as the name of the element containing the corresponding data in the first record of the DataXML data-island.


Configuration Data

The EditField HTC requires that its configuration information be passed to it in the form of an XML data-island. This information consists primarily of details about each column to be displayed. For example, the type of the data in the column, minimum and maximum values for validation purposes, and the element name used for the corresponding data in the DataXML data-island.

The configuration XML data-island can contain configuration information for multiple EditFields, using the ID container attribute to identify which individual EditField configuration information should be used for each instance of an EditField HTC.

For detailed information about the structure of this XML data-island, see EditField Configuration.

For more information about the ways in which an XML document can be included on a page (creating an XML data-island), see XML Data-Islands.


Instantiation Example

The following HTML code shows a typical instantiation of an EditField HTC within a DIV element. The Class attribute specifies that the EditField behavior be associated with this DIV element.

Note

  • In order for the Class attribute to properly identify the EditField HTC, you must make sure that your pages use the Bizdesk.css style sheet.

The DataXML and MetaXML attributes specify the data and configuration data data-islands, respectively, that are defined elsewhere within the document. The ID attribute specifies the same value as assigned to the id attribute of a particular child element of the fields element within the MetaXML data-island. This ID attribute is also the same string used for the name of the element containing the corresponding data value in the DataXML data-island. The Language attribute specifies that the EditField HTC event handlers are implemented in Microsoft Visual Basic Scripting Edition (VBScript). The remaining attributes associate methods defined elsewhere with the specific events supported by the EditField HTC. The OnBrowse event handler should only be defined if the EditField HTC is configured to include a Browse button.

Finally, temporary text is provided to inform the user that the EditField HTC is loading.

  <DIV Id='myEditField'
       Class='EditField'
       Language='VBScript'
       DataXML='DataIslandID'
       MetaXML='MetaDataIslandID'
       ID='FieldIdInMetaXML'
       OnChange='ChangeHandler()'
       OnError='ErrorHandler()'
       OnRequire='RequireHandler()'
       OnBrowse='BrowseHandler()'
       OnValid='ValidHandler()'
  >Loading EditField, please wait...</DIV>


EditSheet

The EditSheet HTML component (HTC) provides the bulk of the functionality required on an edit page. It can display an editable form in a pre-formatted table, with fields displayed according to their order in the configuration data. The editable form can also be displayed according to a template of free-form Dynamic Hypertext Markup Language (DHTML). The EditSheet HTC also enables sophisticated control of each field.

Data is passed to the EditSheet HTC in the form of Extensible Markup Language (XML) data-islands. This includes the configuration data that provides, for example, the display names for data fields. It also includes the data itself, contained in a different XML data-island. Configuration data varies from HTC to HTC, depending on the specific characteristics of each type of HTC. In contrast, the data itself is essentially always the same — one or more records, each containing individual fields of data. Because of this, most of the HTCs, including the EditSheet HTC, accept data in the same generalized format. For more information about this data format, see Getting Data to the Client.

In the EditSheet HTC, a single record is manipulated, displayed as one field per row in a pre-formatted table, or freely formatted when using a template.

This section contains:

  • Events. Describes the events supported by the EditSheet HTC.

  • Properties. Describes the properties supported by the EditSheet HTC.

  • Methods. Describes the methods supported by the EditSheet HTC.

  • Container Attributes. Describes the attributes that the EditSheet HTC expects to be set on the element in which it is contained.

  • Configuration Data. Describes the data passed to the EditSheet HTC via the ID used as the value of the MetaXML container attribute.

  • Instantiation Example. Demonstrates how the EditSheet HTC is instantiated in script on an Active Server Pages (ASP) page.


Events

The EditSheet HTC supports the following events:

  • OnChange

  • OnError

  • OnRequire

  • OnValid

OnChange

The OnChange event fires whenever the value in an embedded field changes.

Return to top

OnError

The OnError event fires when the EditSheet HTC encounters a developer error condition. In addition, if the m_bDebug variable in the HTC is set to True, an alert box appears. This switch can be very helpful in debugging problems that occur if you get the error message "The control could not load."

The event object property window.event.error contains a string with details about the error.

Return to top

OnRequire

The OnRequire event fires whenever an embedded field changes from required to not required, or from not required to required.

The event object property window.event.required is set to True if any embedded field is marked as required and has no value. Otherwise it is set to False.

Return to top

OnValid

The OnValid event fires whenever an embedded field changes from valid to not valid, or from not valid to valid.

The event object property window.event.valid is set to False if the value in any embedded EditField HTC is not valid. Otherwise it is set to True.

Return to top


Properties

The EditSheet HTC supports the following properties:

  • dirty

  • required

  • valid

dirty

The dirty property tracks whether the value in any embedded field has changed. Legal values are True and False. A value of True indicates that the value of some embedded field has changed, and False indicates that none of the values in the embedded fields have changed.

This property is read-only.

Return to top

required

The required property tracks whether any embedded field requires user input. Requiring input is defined as being configured as required, but having no current value. Legal values are True and False. A value of True indicates that user input is required, and False indicates that user input is not required.

The OnRequire event fires whenever the value of this property changes.

This property is read-only.

Return to top

valid

The valid property tracks whether the current values in all embedded fields are valid according to constraints imposed by the configuration information. Legal values are True and False. A value of False indicates that at least one current value is not valid, and True indicates that all current values are valid.

The OnValid event fires whenever the value of this property changes.

This property is read-only.

Return to top


Methods

The EditSheet HTC supports the following methods:

  • field

  • focus

  • hidden

  • hide

  • resetDefault

  • resetDirty

  • show

field(sFieldId)

The field method retrieves a particular field element embedded within the EditSheet HTC. The field element is identified by the required sFieldId parameter, which specifies the value of the id attribute of one of the child elements of the fields element in the MetaXML data-island.

The returned HTMLElement has an attached field element. If the parameter does not match any of the id attributes, NULL is returned.

The returned HTMLElement allows access to any of the properties or methods of the field element.

Example: set elEditField = elEditSheet.field(sFieldId)

Return to top

focus

The focus method sets focus to the EditSheet HTC, assuming it is not disabled.

This method does not have parameters or a return value.

Return to top

hidden(sFieldId)

The hidden method returns True if the specified field is hidden and False if not.

The field element is identified by the required sFieldId parameter, which specifies the value of the id attribute of one of the child elements of the fields element in the MetaXML data-island.

This method is only meant for use with the standard table layout; it cannot report whether or not a field within a template is hidden.

Return to top

hide(sFieldId)

The hide method hides the label and control for a field within the standard table layout.

The field element is identified by the required sFieldId parameter, which specifies the value of the id attribute of one of the child elements of the fields element in the MetaXML data-island.

This method is only meant for use with the standard table layout; it cannot hide a field within a template. Hidden fields will not fire onRequire or onValid events when their values are changed programmatically.

This method has no return value.

Return to top

resetDefault

The resetDefault method sets all fields in the EditSheet HTC back to their default values. This method also resets the dirty property to False.

This method does not have parameters or a return value.

Return to top

resetDirty

The resetDirty method resets the dirty property to False.

This method does not have parameters or a return value.

Return to top

show(sFieldId)

The show method shows the label and control for a hidden field within the standard table layout.

The field element is identified by the required sFieldId parameter, which specifies the value of the id attribute of one of the child elements of the fields element in the MetaXML data-island.

This method is only meant for use with the standard table layout; it cannot show a field within a template.

This method has no return value.

Return to top


Container Attributes

In order to pass data to the EditSheet HTC, the following attributes must be set on the element that is using the EditSheet behavior (this element is typically a DIV):

DataXML

The value of this attribute must be set to the value of the id attribute of the Extensible Markup Language (XML) data-island containing the data to be displayed.

MetaXML

The value of this attribute must be set to the value of the id attribute of the XML data-island containing the configuration information for this instance of the EditSheet HTC.


Configuration Data

The EditSheet HTC requires that its configuration information be passed to it in the form of an Extensible Markup Language (XML) data-island. This information consists primarily of details about each editable field to be displayed. For example, the type of the data in the field, the name to use as the field label, and the element name used for the corresponding data in the DataXML data-island. In addition, there is some global configuration information, such as whether the EditSheet should be initially displayed as opened or closed.

The configuration XML data-island is also known as the MetaXML data-island.

For detailed information about the structure of this XML data-island, see EditSheet Configuration.

For more information about the ways in which an XML document can be included on a page (creating an XML data-island), see XML Data-Islands.


Instantiation Example

The following code shows a typical instantiation of an EditSheet HTC within a DIV element. The Class attribute specifies that the EditSheet behavior be associated with this DIV element.

Note

  • In order for the Class attribute to properly identify the EditSheet HTC, you must make sure that your pages use the Bizdesk.css style sheet.

The DataXML and MetaXML attributes specify the data and metadata data-islands that are defined elsewhere within the document. The Language attribute specifies that the EditSheet HTC event handlers are implemented in Microsoft Visual Basic Scripting Edition (VBScript). The remaining attributes associate methods defined elsewhere with the specific events supported by the EditSheet HTC.

Finally, temporary text is provided to inform the user that the EditSheet HTC is loading.

  <DIV Id='myEditSheet'
       Class='EditSheet'
       Language='VBScript'
       DataXML='DataIslandID'
       MetaXML='MetaDataIslandID'
       OnChange='ChangeHandler()'
       OnError='ErrorHandler()'
       OnRequire='RequireHandler()'
       OnValid='ValidHandler()'
  >Loading EditSheet, please wait...</DIV>


ExpressionBuilder

The ExpressionBuilder HTML component (HTC) provides users with an easy and intuitive manner in which to build expressions used for targeting. These expressions are given names and are saved in an Extensible Markup Language (XML) representation in the Expression Store. The ExpressionBuilder HTC makes use of the QueryBuilder HTC for the manipulation of the expression bodies.

This section contains:

  • Events. Describes the events supported by the ExpressionBuilder HTC.

  • Properties. Describes the properties supported by the ExpressionBuilder HTC.

  • Methods. Describes the methods supported by the ExpressionBuilder HTC.

  • Container Attributes. Describes the attributes that the ExpressionBuilder HTC expects to be set on the element in which it is contained.

  • Configuration Data. Describes the data passed to the ExpressionBuilder HTC via the ID used as the value of the XMLCfgID container attribute.

  • Instantiation Example. Demonstrates how the ExpressionBuilder HTC is instantiated in script on an Active Server Pages (ASP) page.


Events

The ExpressionBuilder HTC supports the following events:

  • OnComplete

  • OnError

  • OnReady

OnComplete

The OnComplete event fires when the ExpressionBuilder HTC has successfully terminated. This can happen when the user presses the Save button or the Cancel button and the associated processing does not encounter any errors.

Return to top

OnError

The OnError event fires when activation of the ExpressionBuilder HTC fails. This event can occur after returning from a successful call to the Activate method. This indicates the occurrence of an unexpected error later in the activation process.

Return to top

OnReady

The OnReady event fires when the ExpressionBuilder HTC is fully loaded and initialized, indicating that its programmatic interface is ready to use. No methods or properties of the ExpressionBuilder HTC should be used before this event fires.

Return to top


Properties

The ExpressionBuilder HTC supports the following properties:

  • IsActive

  • IsReady

IsActive

The IsActive property indicates whether the ExpressionBuilder HTC is currently active. The value of this property is True when the ExpressionBuilder HTC is active. The ExpressionBuilder HTC is defined as 'active' when a user can interact with it. The value is False when the control is inactive.

This property is read-only.

Return to top

IsReady

The IsReady property indicates whether the ExpressionBuilder HTC is ready to use. The value of this property is False before the OnReady event fires, and True after that event fires. It allows polling to be used to determine whether the ExpressionBuilder HTC is ready to use.

This property is read-only.

Return to top


Methods

The ExpressionBuilder HTC supports the following methods:

  • Activate

  • Deactivate

  • GetResults

  • Save

  • Cancel

Activate(strMode, nExprID)

The Activate method activates the ExpressionBuilder HTC, indicating success with a return value of True, and failure with a return value of False.

The required strMode parameter indicates the mode in which the expression indicated by the required nExprID parameter, if any, is loaded. Legal values are 'create', 'createfrom', 'edit', and 'view'. If the value of strMode is 'create', the value of the nExprID parameter is ignored. Otherwise, the value of the nExprID parameter must be the ID of an expression in the expression store.

Example:

bResult = elExpBuilder.Activate("create", -1)

After calling the Activate method, you should wait for the IsReady event to fire or the IsReady property to become True. If the OnError event fires first, an asynchronous activation error has occurred.

Return to top

Deactivate

The Deactivate method deactivates the ExpressionBuilder HTC. It does not take any parameters, and the current expression information is not cleared.

Return to top

GetResults

The GetResults method returns the current ExpressionBuilder HTC status and results using a Scripting.Dictionary object. This Dictionary object contains the following entries:

  • The SavedExpr dictionary entry is set to True if the current expression has been successfully saved, and False otherwise. Expressions are saved as a result of successful create and save operations.

  • The ExprID dictionary entry contains the ID of the expression being manipulated. It is set to –1 (EXPR_INVALID) if the expression has not yet been saved.

  • The ExprName dictionary entry contains the current name of the expression, regardless of whether expression editing is complete.

  • The ExprBody dictionary entry contains the current XML representation of the expression, regardless of whether expression editing is complete.

The GetResults method does not take any parameters.

Example: oDictionary = elExpBuilder.GetResults()

Return to top

Save

Assuming that the activation mode is not 'view', the Save method saves the current expression. It returns True if the save operation is successful, and False otherwise.

Calling this method is equivalent to the user clicking the Save button. If successful, it fires the OnComplete event.

Return to top

Cancel

The Cancel method discards any unsaved editing of the current expression and disables the Expression Builder user interface. It does not return any value.

Calling this method is equivalent to the user clicking the Cancel button. If the user does not abort the cancellation, this method fires the OnComplete event.

Return to top


Container Attributes

In order to pass data to the ExpressionBuilder HTC, the following attribute must be set on the element that is using the ExpressionBuilder behavior (this element is typically a DIV):

XMLCfgID

The value of this attribute must be set to the ID of the Extensible Markup Language (XML) data-island containing the configuration data for the ExpressionBuilder HTC.


Configuration Data

The ExpressionBuilder HTC requires that its configuration information be passed to it in the form of an Extensible Markup Language (XML) data-island. This information consists partly of configuration information specific to the embedded QueryBuilder HTC, which is ignored by the ExpressionBuilder HTC, and partly of configuration information specific to the ExpressionBuilder HTC.

For detailed information about the structure of this XML data-island, see ExpressionBuilder Configuration.

For more information about the ways in which an XML document can be included on a page (creating an XML data-island), see XML Data-Islands.


Instantiation Example

The following HTML code shows a typical instantiation of a ExpressionBuilder HTC within a DIV element. The Style attribute specifies that the ExpressionBuilder HTC behavior be associated with this DIV element.

Note

  • In order for the Class attribute to properly identify the ExpressionBuilder HTC, you must make sure that your pages use the Bizdesk.css style sheet.

The XMLCfgID attribute specifies the configuration data-island that is defined elsewhere within the document. The Language attribute specifies that the ExpressionBuilder HTC event handlers are implemented in Microsoft Visual Basic Scripting Edition (VBScript). The remaining attributes associate methods defined elsewhere with the specific events supported by the ExpressionBuilder HTC.

Finally, temporary text is provided to inform the user that the ExpressionBuilder HTC is loading.

  <DIV Id='myExpressionBuilder'
       Class='clsExprBldr'
       Style='behavior:url(/widgets/exprbldrHTC/ExprBldr.htc); width:100%'
       Language='VBScript'
       XMLCfgID='DataIslandID'
       OnComplete='CompleteHandler()'
       OnError='ErrorHandler()'
       OnReady='ReadyHandler()'
  >Loading ExpressionBuilder, please wait...</DIV>


ListBox

The ListBox HTML component (HTC) allows easy list operations on a nested DIV element. A common use of the ListBox HTC occurs when a pair of them are used side by side, with the one on the left listing available choices and the one on the right listing those choices already made. Typically, several buttons are placed between the lists, providing the ability to move items from one list to the other.

Data is initially specified to populate the ListBox HTC as attribute and data values to DIV elements nested within the DIV element that specifies the 'ListBox' value for the Class attribute. After that, additional data is added and removed from the ListBox HTC using methods provided for that purpose. Unlike the other Commerce Server HTCs, the ListBox HTC does not require any pre-existing XML data-islands to provide configuration information.

This section contains:

  • Events. Describes the events supported by the ListBox HTC.

  • Properties. Describes the properties supported by the ListBox HTC.

  • Methods. Describes the methods supported by the ListBox HTC.

  • Container Attributes. Describes the attributes that the ListBox HTC expects to be set on the element in which it is contained.

  • Initial Data Population. Describes how the data used to initially populate the ListBox HTC is provided.

  • Instantiation Example. Demonstrates how the ListBox HTC is instantiated in script on an Active Server Pages (ASP) page.


Events

The ListBox HTC supports the following events:

  • OnChange

  • OnSelect

  • OnSelectAll

  • OnUnselect

  • OnUnselectAll

OnChange

The OnChange event fires when one or more items is added to, or removed from, the list.

There are no event object properties associated with this event.

Return to top

OnSelect

The OnSelect event fires when one or more items are selected.

There are no event object properties associated with this event.

Return to top

OnSelectAll

The OnSelectAll event fires when all items are selected via the SelectAll method.

There are no event object properties associated with this event.

Return to top

OnUnselect

The OnUnselect event fires when an item is unselected.

There are no event object properties associated with this event.

Return to top

OnUnselectAll

The OnUnselectAll event fires when all items are unselected via the UnselectAll method.

There are no event object properties associated with this event.

Return to top


Properties

The ListBox HTC supports the following properties:

  • disabled

  • selected

  • text

  • value

disabled

The disabled property returns True when the ListBox HTC has been disabled, and False otherwise. While disabled, the ListBox HTC will be dimmed and removed from the tab order.

This property is read/write.

Return to top

selected

The selected property returns the selected HTML element.

When in multi-select mode, this property returns a single HTML element, even if multiple elements are selected. It returns either the first or the last selected item in the list. Therefore, you should not rely on this property when in multi-select mode.

This property is read-only.

Return to top

text

The text property returns the display name associated with the currently selected item.

When in multi-select mode, this property returns a single display name, even if multiple items are selected. It returns the display name of either the first or the last selected item in the list. Therefore, you should not rely on this property when in multi-select mode.

This property is read/write.

Return to top

value

The value property returns the value associated with the currently selected item, represented as a string. When in multi-select mode, this property returns the value associated with either the last selected item or the first selected item from the list.

This property is read/write.

Return to top


Methods

The ListBox HTC supports the following methods:

  • add

  • addItem

  • movedown

  • moveup

  • remove

  • select

  • SelectAll

  • unselect

  • UnselectAll

add(xmlNodes)

The add method adds one or more items to the list, based on the data contained in the xmlNodes object passed via the required xmlNodes parameter. This xmlNodes object must have the same format as that returned by the remove method. Beyond that, no other format assumptions should be made.

This method does not return any value.

This method is most useful when moving one or more items from one ListBox HTC to another ListBox HTC.

Return to top

addItem(sValue, sText)

The addItem method adds a single item to the list based on the values of the required parameters sValue and sText. The sValue parameter specifies the value associated with the new item, and the sText parameter specifies the display name of the new item.

This method does not return any value.

Return to top

movedown

The movedown method moves the selected item to the next lower position in the list.

When in multi-select mode, this property moves a single selected item down one position, even if multiple items are selected. It moves either the first or the last selected item in the list. Therefore, you should not rely on this method when in multi-select mode.

This method does not return any value.

Return to top

moveup

The moveup method moves the selected item to the next higher position in the list.

When in multi-select mode, this property moves a single selected item up one position, even if multiple items are selected. It moves either the first or the last selected item in the list. Therefore, you should not rely on this method when in multi-select mode.

This method does not return any value.

Return to top

remove

The remove method removes all selected items from the list and returns those items in XML representation. The returned xmlNodes object has the same format as that required by the add method. Beyond that, no other format assumptions should be made.

This method is most useful when moving one or more items from one ListBox HTC to another ListBox HTC.

Example: set xmlNodes = elListBox.remove

Return to top

select(sValue)

The select method selects the first item found that has a value equal to the required sValue parameter. If nothing is found, nothing is selected (this is not considered an error, so no error is returned).

This method does not return any value.

Return to top

SelectAll

The SelectAll method selects all of the items in the list. It does not take any parameters or return any value.

Return to top

unselect(sValue)

The unselect method unselects the first item found that has a value equal to the required sValue parameter. If nothing is found, nothing is unselected (this is not considered an error, so no error is returned).

This method does not return any value.

Return to top

UnselectAll

The UnselectAll method unselects all of the items in the list. It does not take any parameters or return any value.

Return to top


Container Attributes

Unlike most of the other Commerce Server HTCs, the ListBox HTC does not use Extensible Markup Language (XML) data-islands, specified using container attributes, for its data and configuration information. Instead, it uses a container attribute and an additional Class attribute value for some simple configuration, as follows:

selection

The value of this attribute specifies whether the ListBox HTC will allow single selection or multiple selection. Legal values are 'single' and 'multi'. The default is single selection.

lbDisabled

Specifying this Class attribute value, in addition to the 'ListBox' Class attribute value, causes the ListBox HTC to initially be displayed as disabled.


Initial Data Population

The ListBox HTC allows its initial set of data to be specified using DIV elements, one per item, that are nested within the DIV element that specifies the ListBox HTC itself. These inner DIV elements must include a VALUE attribute, the value of which specifies the value to be associated with the list item. They must also include data, which provides the string to be displayed for the item in the ListBox HTC. The following example shows this DIV element structure:

  <DIV Class='ListBox'   . . . >
      <DIV VALUE='value1'>display value 1</DIV>
      <DIV VALUE='value2'>display value 2</DIV>
      . . .
      <DIV VALUE='valueN'>display value N</DIV>
  </DIV>


Instantiation Example

The following HTML code shows a typical instantiation of a ListBox HTC within a DIV element. The first Class attribute value specifies that the ListBox behavior be associated with this DIV element.

Note

  • In order for the Class attribute to properly identify the ListBox HTC, you must make sure that your pages use the Bizdesk.css style sheet.

The nested DIV elements specify the initial list box data. The second Class attribute value and the Selection attribute specify that the list box should be initially disabled, and allow multiple selection, respectively. The Language attribute specifies that the ListBox HTC event handlers are implemented in Microsoft Visual Basic Scripting Edition (VBScript). The remaining attributes associate methods defined elsewhere with the specific events supported by the ListBox HTC.

  <DIV Class='ListBox lbDisabled'
       Language='VBScript'
       Selection='multi'
       OnChange='ChangeHandler()'
       OnSelect='SelectHandler()'
       OnSelectAll='SelectAllHandler()'
       OnUnselect='UnselectHandler()'
       OnUnselectAll='UnselectAllHandler()'>
         <DIV VALUE='value1'>display value 1</DIV>
         <DIV VALUE='value2'>display value 2</DIV>
         . . .
         <DIV VALUE='valueN'>display value N</DIV>
  </DIV>


ListEditor

The ListEditor HTML component (HTC) displays a table of data, known as the list area, where each row represents a record and each column represents a particular field from the record. Below this table is another table, known as the edit area, which displays and allows editing of the record selected in the first table. This second table has two columns. The first column contains field names and the second column contains the field data itself, displayed within the appropriate embedded EditField HTC.

Data is passed to the ListEditor HTC in the form of Extensible Markup Language (XML) data-islands. This includes the configuration data that provides, for example, the display names for columns in the list area, and various characteristics of the fields displayed in the edit area. It also includes the data itself, contained in a different XML data-island. Configuration data varies from HTC to HTC, depending on the specific characteristics of each type of HTC. In contrast, the data itself is essentially always the same — one or more records, each containing individual fields of data. Because of this, most of the HTCs, including the ListEditor HTC, accept data in the same generalized format. For more information about this data format, see Getting Data to the Client.

Unlike the DynamicTable HTC, the ListEditor HTC can be configured to allow the editing of data that is not displayed in the columns of the list table. Like the DynamicTable HTC, the ListEditor HTC returns its result as an XML list document.

This section contains:

  • Events. Describes the events supported by the ListEditor HTC.

  • Properties. Describes the properties supported by the ListEditor HTC.

  • Methods. Describes the methods supported by the ListEditor HTC.

  • Container Attributes. Describes the attributes that the ListEditor HTC expects to be set on the element in which it is contained.

  • Configuration Data. Describes the data passed to the ListEditor HTC via the ID used as the value of the MetaXML container attribute.

  • Instantiation Example. Demonstrates how the ListEditor HTC is instantiated in script on an Active Server Pages (ASP) page.


Events

The ListEditor HTC supports the following events:

  • OnCancel

  • OnChange

  • OnEdit

  • OnError

  • OnNew

  • OnValid

OnCancel

The OnCancel event fires when the user clicks the Cancel button or cancels the selection of a row in the list table.

Return to top

OnChange

The OnChange event fires when the user clicks either the Done button or the Remove button.

The event object property window.event.XMLlist is a standard XMLlist object hierarchy, including the state attribute in the record elements. For more information, see XMLlist and XMLrecord Properties.

The event object property window.event.recordNumber contains a positive integer indicating the relative position of the last record changed (starting from zero).

Return to top

OnEdit

The OnEdit event fires when a user clicks a row to edit it and the associated values have been placed into the fields in the edit area.

The event object property window.event.recordNumber contains a positive integer indicating the relative position of the record being edited (starting from zero).

The event object property window.event.XMLrecord is a standard XMLrecord object hierarchy corresponding to the row being edited. For more information, see XMLlist and XMLrecord Properties.

Return to top

OnError

The OnError event fires when the ListEditor HTC encounters a developer error condition. In addition, if the m_bDebug variable in the HTC is set to True, an alert box appears. This switch can be very helpful in debugging problems that occur if you get the errror message "The control could not load."

The event object property window.event.error contains a string with details about the error.

Return to top

OnNew

The OnNew event fires when the user clicks the New button and the fields in the edit area have been cleared.

The event object property window.event.recordNumber contains the value –1 to indicate that a new record is being added. New records are always added to the end of the list.

The event object property window.event.XMLrecord is a standard XMLrecord object hierarchy consisting of a new and empty record element. For more information, see XMLlist and XMLrecord Properties.

Return to top

OnValid

The OnValid event fires whenever the user starts editing a row and again when editing is complete.

The event object property window.event.valid is set to False when the event is fired because a row is being edited. When editing is complete (when either the Cancel or Accept button is clicked), the value is set to True.

This assures that the HTC cannot be saved when the user is in the middle of an edit.

Return to top


Properties

The ListEditor HTC supports the following properties:

  • dirty

  • XMLlist

dirty

The dirty property returns True if a row has been added, deleted, or edited, and False otherwise.

This property is read-only.

Return to top

XMLlist

The XMLlist property is a standard XMLlist object hierarchy, containing the list currently in use by the HTC, and including the state attribute in the record elements. For more information, see XMLlist and XMLrecord Properties.

This property is read-only.

Return to top


Methods

The ListEditor HTC supports the following method:

field(sFieldId)

The field method retrieves a particular field element being used by the ListEditor HTC. The field is identified by the required sFieldId parameter, which specifies the value of the id attribute of one of the child elements of the fields element in the MetaXML data-island.

The returned HTMLElement has an attached EditField HTC. If the parameter does not match any of the id attributes, NULL is returned.

The returned HTMLElement allows access to any of the properties or methods of the EditField HTC.

Example: set elEditField = elListEditor.field(sFieldId)


Container Attributes

In order to pass data to the ListEditor HTC, the following attributes must be set on the element that is using the ListEditor behavior (this element is typically a DIV):

DataXML

The value of this attribute must be set to the value of the id attribute of the XML data-island containing the data to be displayed.

MetaXML

The value of this attribute must be set to the value of the id attribute of the XML data-island containing the configuration information for this instance of the DynamicTable HTC.


Configuration Data

The ListEditor HTC requires that its configuration information be passed to it in the form of an Extensible Markup Language (XML) data-island. This information consists of details about each column and row to be displayed in the list area and the edit area, respectively. For example, the type of the data in the column or row, minimum and maximum values for validation purposes, and the element name used for the corresponding data in the DataXML data-island.

For detailed information about the structure of this XML data-island, see ListEditor Configuration.

For more information about the ways in which an XML document can be included on a page (creating an XML data-island), see XML Data-Islands.


Instantiation Example

The following HTML code shows a typical instantiation of a ListEditor HTC within a DIV element. The Class attribute specifies that the ListEditor behavior be associated with this DIV element.

Note

  • In order for the Class attribute to properly identify the ListEditor HTC, you must make sure that your pages use the Bizdesk.css style sheet.

The DataXML and MetaXML attributes specify the data and configuration data-islands that are defined elsewhere within the document. The Language attribute specifies that the ListEditor HTC event handlers are implemented in Microsoft Visual Basic Scripting Edition (VBScript). The remaining attributes associate methods defined elsewhere with the specific events supported by the ListEditor HTC.

Finally, temporary text is provided to inform the user that the ListEditor HTC is loading.

  <DIV Id='myListEditor'
       Class='ListEditor'
       Language='VBScript'
       DataXML='DataIslandID'
       MetaXML='MetaDataIslandID'
       OnCancel=CancelHandler()'
       OnChange=ChangeHandler()'
       OnEdit='EditHandler()'
       OnError='ErrorHandler()'
       OnNew='NewHandler()'
       OnValid='ValidHandler()'
  >Loading ListEditor, please wait...</DIV>


ListSheet

The ListSheet HTML component (HTC) is the primary control for presenting data on a list page, and is used mainly to present data for viewing and selection. It displays data in a configurable, tabular format that allows paging and sorting. It can be configured to allow multiple selection, or it can be limited to a single selection.

In most of the available modes, data is presented in a hierarchical manner, allowing details to be shown or hidden by clicking in the row containing the higher-level information. When the arrow is pointing to the right, the details are hidden; when the arrow is pointing down, the details are shown.

Data is passed to the ListSheet HTC in the form of Extensible Markup Language (XML) data-islands. This includes the configuration data that provides, for example, the display names for data columns. It also includes the data itself, contained in a different XML data-island. Configuration data varies from HTC to HTC, depending on the specific characteristics of each type of HTC. In contrast, the data itself is essentially always the same — one or more records, each containing individual fields of data. Because of this, most of the HTCs, including the ListSheet HTC, accept data in the same generalized format. For more information about this data format, see Getting Data to the Client.

This section contains:

  • Modes of Operation. Describes the different modes in which the ListSheet HTC can be used.

  • Events. Describes the events supported by the ListSheet HTC.

  • Properties. Describes the properties supported by the ListSheet HTC.

  • Methods. Describes the methods supported by the ListSheet HTC.

  • Container Attributes. Describes the attributes that the ListSheet HTC expects to be set on the element in which it is contained.

  • Configuration Data. Describes the data passed to the ListSheet HTC via the ID used as the value of the MetaXML container attribute.

  • Instantiation Example. Demonstrates how the ListSheet HTC is instantiated in script on an Active Server Pages (ASP) page.


Modes of Operation

There are five distinct modes in which the ListSheet HTC can be configured, based on settings in the configuration data XML data-island. These five modes can be classified as belonging to one of three basic types: flat lists, homogeneous grouped lists, and heterogeneous grouped lists. The five modes are:

  • Flat List

  • Two-Level Homogeneous Grouped List

  • Three-Level Homogeneous Grouped List

  • List-Style Heterogeneous Grouped List

  • Properties-Style Heterogeneous Grouped List

Flat List

This is the most basic mode of the ListSheet HTC. The data is presented as a simple table with no expand/collapse capabilities. The id2 and id3 attributes of the column elements are not used. Also, the subobject element within the columns element is not used.

In this mode the ListSheet HTC expects a single-tiered DataXML data-island. Any extra tiers are ignored.

Return to top

Two-Level Homogeneous Grouped List

Two-level homogeneous lists are appropriate when there are two levels of data to display, and the same set of columns (specifically, column headings) can serve for the data at both levels.

Any given column need not contain data for both levels, and can be left blank or otherwise filled in such a way as to indicate that no data is expected in that column for that level of data. Some existing Commerce Server Business Desk modules use the hyphen ('-') character to indicate such a lack of data.

In two-level homogeneous grouped lists, the id2 attribute of the column (child of columns) elements are used to identify detail data in the second tier of records in the DataXML data-island. The subobject element and its embedded column elements are not used.

In this mode the ListSheet HTC expects a two-tiered DataXML data-island. Any extra tiers are ignored.

Return to top

Three-Level Homogeneous Grouped List

Three-level homogeneous lists are appropriate when there are three levels of data to display, and the same set of columns (specifically, column headings) can serve for the data at all three levels.

Any given column need not contain data for all three levels, and can be left blank or otherwise filled in such a way as to indicate that no data is expected in that column for that level of data. Some existing Business Desk modules use the hyphen ('-') character to indicate such a lack of data.

In three-level homogeneous grouped lists, the id2 and id3 attributes of the column (child of columns) elements are used to identify detail data in the second and third tiers of records, respectively, in the DataXML data-island. The subobject element and its embedded column elements are not used.

In this mode the ListSheet HTC expects a three-tiered DataXML data-island. Three is the greatest number of tiers that is supported.

Return to top

List-Style Heterogeneous Grouped List

Heterogeneous lists are appropriate where the data presented in columns in the group rows is different than the detailed data, and the sharing of column headings would not be appropriate. In list-style heterogeneous grouped lists, the detailed data is presented in what appears to be an embedded ListSheet HTC, typically displaying multiple records. Sub-items in a heterogeneous list are not selectable.

The subobject element and its column elements are used to describe the detailed data columns to be displayed. This includes the identity of the detail data to be displayed, which must exist in the second tier of records in the DataXML data-island. The id2 and id3 attributes of the (columns) column element are not used.

In this mode the ListSheet HTC expects a two-tiered DataXML data-island. Any extra tiers are ignored.

Return to top

Properties-Style Heterogeneous Grouped List

Heterogeneous lists are appropriate where the data presented in columns in the group rows is different than the detailed data, and the sharing of column headings would not be appropriate. In properties-style heterogeneous grouped lists, the detailed data is presented in what appears to be an embedded EditSheet HTC, displaying a single record. Sub-items in a heterogeneous list are not selectable.

The subobject element and its column elements are used to describe the detailed data rows to be displayed. This includes the identity of the detail data to be displayed, which must exist in the second tier of records in the DataXML data-island. The id2 and id3 attributes of the (columns) column element are not used.

In this mode the ListSheet HTC expects a two-tiered DataXML data-island. Any extra tiers are ignored.

Return to top


Events

The ListSheet HTC supports the following events:

  • OnAllRowsSelect

  • OnAllRowsUnselect

  • OnError

  • OnGroupOpen

  • OnHeaderClick

  • OnNewPage

  • OnRowSelect

  • OnRowUnselect

OnAllRowsSelect

The OnAllRowsSelect event fires when all rows are selected together using the Select All button.

No event object properties are set for this event.

The firing of this event indicates that all rows have been selected, including those on pages that are not currently being displayed.

Return to top

OnAllRowsUnselect

The OnAllRowsUnselect event fires when all rows are unselected together using the Deselect All button.

No event object properties are set for this event.

The firing of this event indicates that all rows have been unselected, including those on pages that are not currently being displayed.

Return to top

OnError

The OnError event fires when the ListSheet HTC encounters a developer error condition. In addition, if the m_bDebug variable in the HTC is set to True, an alert box appears. This switch can be very helpful in debugging problems that occur when you get the errror message "The control could not load."

The event object property window.event.error contains a string with details about the error.

Return to top

OnGroupOpen

The OnGroupOpen event fires when a group row is opened to display sub-item rows or a sub-object table.

The event object property window.event.XMLrecord is a standard XMLrecord object hierarchy corresponding to the opened group row. For more information, see XMLlist and XMLrecord Properties.

Return to top

OnHeaderClick

The OnHeaderClick event fires when one of the column headings is clicked, allowing a sorting routine to be invoked. This event will not fire if sorting has been disabled (by setting the sort attribute to "no" in the meta-data).

Two event object properties are set when the event is fired. The window.event.sortcol property contains a string that is set to the value of the id attribute of the (columns) column element corresponding to the heading that was clicked.

Note

  • When using the XMLHTTP sort operation there is no need to trap this event because sort executes automatically.

The event object property window.event.sortdir contains one of the two strings 'asc' or 'desc', indicating the new sorting direction (ascending or descending, respectively).

Return to top

OnNewPage

The OnNewPage event fires when one of the page navigation buttons is clicked (First, Previous, Next, and Last), or when the page number is explicitly changed.

Note

  • When using the XMLHTTP page operation there is no need to trap this event because the page operation executes automatically.

The event object property window.event.page contains a positive integer that indicates the new page to be displayed. Page numbers start at one, not zero.

Return to top

OnRowSelect

The OnRowSelect event fires when a row is selected.

The event object property window.event.XMLrecord is a standard XMLrecord object hierarchy corresponding to the selected row. For more information, see XMLlist and XMLrecord Properties.

Return to top

OnRowUnselect

The OnRowUnselect event fires when a row is unselected.

The event object property window.event.XMLrecord is a standard XMLrecord object hierarchy corresponding to the row that has been unselected. For more information, see XMLlist and XMLrecord Properties.

Return to top


Properties

The ListSheet HTC supports the following properties:

  • page

  • recordcount

  • XMLlist

page

The page property reads and writes the page number that is displayed in the page controls.

Writing a new page property does not fire the OnNewPage event, or do anything with regard to retrieving the data associated with the new page.

This property is read/write.

Return to top

recordcount

The recordcount property reads and writes the current number of records, and when written, the ListSheet HTC recalculates the page controls.

Setting this property to –1 causes the Last button to be disabled, and indicates that the number of records is not known.

Setting this property to 0 (zero) or any number less than or equal to the page size causes the page controls to be hidden.

This property is read/write.

Return to top

XMLlist

The XMLlist property is a standard XMLlist object hierarchy, containing the list currently in use by the HTC. For more information, see XMLlist and XMLrecord Properties.

This property is read-only.

Return to top


Methods

The ListSheet HTC supports the following methods:

  • reload

  • selectAllRows

  • unselectAllRows

reload(sOp, sArgs)

The reload method reloads the data into the ListSheet HTC using an operation configured in the MetaXML data-island. This type of operation, known as an XMLHTTP operation, retrieves and displays new data from the server without reloading the current page.

The operation is identified by the required sOp parameter, which specifies the name of a child element of the operations element in the MetaXML data-island. The element name can be one of the pre-defined operations: page, sort, or sublist, or it can be a completely custom operation.

The formid attribute of the matching operation element identifies the form that is posted as a result of this operation. The action attribute of the form specifies the page to which the form is posted.

Since the form will be posted in XML format, response pages should use the utility routine dGetRequestXMLAsDict to retrieve the posted XML as a Dictionary object. In addition, response pages should include the file BDXMLHeader.asp, which sets the response.contentType to 'text/xml' and inserts the processing instruction node to set the XML version and charset.

The sArgs parameter specifies a list of URL-encoded page arguments that are passed to the page being posted. In addition, any child elements of the form are sent with the form posting.

Finally, the pre-defined operations result in certain, pre-defined arguments being included:

  • Page operations: 'op', 'prevpage', 'page', 'column', and 'direction'

  • Sort operations: 'op', 'page', 'column' and 'direction'

  • SubList operation: 'op' and 'xmlrecord'

This method returns False if any error nodes are present in the returned XML, or if nothing is returned. It returns True if a valid XML record list is returned with no error nodes.

Example:

bRetVal = elListSheet.reload("double_sort")

The Sort operation automatically resets the current page number to 1 (one) and will execute automatically when a column header is clicked. The Page operation automatically resets the current page number to whatever new page is requested and executes automatically when any of the page controls are clicked or if a new page number is entered into the page number input field. For some custom operations, it may be necessary to set the current page number of the ListSheet HTC to some new value before calling the reload method, based on the nature of the custom operation. The page property of the ListSheet HTC is provided for this purpose. For more information about the page property, see page.

Return to top

selectAllRows

The selectAllRows method selects all rows in the list. It does not take any parameters and does not have any return value.

This method selects all rows, including those on pages not currently being displayed.

Return to top

unselectAllRows

The unselectAllRows method unselects all rows in the list. It does not take any parameters and does not have any return value.

This method unselects all rows, including those on pages not currently being displayed.

Return to top


Container Attributes

In order to pass data to the ListSheet HTC, the following attributes must be set on the element that is using the ListSheet behavior (note that this element is typically a DIV):

DataXML

The value of this attribute must be set to the value of the id attribute of the Extensible Markup Language (XML) data-island containing the data to be displayed.

Depending on the mode in which the ListSheet HTC is configured to run, this data-island may have one, two, or three tiers of record elements within it.

MetaXML

The value of this attribute must be set to the value of the id attribute of the XML data-island containing the configuration information for this instance of the ListSheet HTC.


Configuration Data

The ListSheet HTC requires that its configuration information be passed to it in the form of an XML data-island. This information consists primarily of details about each column to be displayed. For example, the type of the data in the column, minimum and maximum values for validation purposes, and the element name used for the corresponding data in the DataXML data-island.

For detailed information about the structure of this XML data-island, see ListSheet Configuration.

For more information about the ways in which an XML document can be included on a page (creating an XML data-island), see XML Data-Islands.


Instantiation Example

The following HTML code shows a typical instantiation of a ListSheet HTC within a DIV element. The Class attribute specifies that the ListSheet behavior be associated with this DIV element.

Note

  • In order for the Class attribute to properly identify the ListSheet HTC, you must make sure that your pages use the Bizdesk.css style sheet.

The DataXML and MetaXML attributes specify the data and configuration data-islands that are defined elsewhere within the document. The Language attribute specifies that the ListSheet HTC event handlers are implemented in Microsoft Visual Basic Scripting Edition (VBScript). The remaining attributes associate methods defined elsewhere with the specific events supported by the ListSheet HTC.

Finally, temporary text is provided to inform the user that the ListSheet HTC is loading.

  <DIV Id='myListSheet'
       Class='ListSheet'
       Language='VBScript'
       DataXML='DataIslandID'
       MetaXML='MetaDataIslandID'
       OnAllRowsSelect='AllRowsSelectHandler()'
       OnAllRowsUnselect='AllRowsUnselectHandler()'
       OnError='ErrorHandler()'
       OnHeaderClick='HeaderClickHandler()'
       OnGroupOpen='GroupOpenHandler'
       OnNewPage='NewPageHandler()'
       OnRowSelect='RowSelectHandler()'
       OnRowUnselect='RowUnselectHandler()'
  >Loading ListSheet, please wait...</DIV>


QueryBuilder

The QueryBuilder HTML component (HTC) provides users with an easy and intuitive manner in which to build queries.

Queries are built from one or more clauses combined with logical operators. Clauses are operations or comparisons performed on one or more profiles. The QueryBuilder HTC currently supports a variety of property types and operators. The types and operators supported by the QueryBuilder HTC can be customized as well.

The queries are represented in an Extensible Markup Language (XML) format that can be used as is, or that can be converted (via Extensible Stylesheet Language (XSL) transforms or other methods) to other formats, such as SQL that can be used against an actual database.

This section contains:

  • Events. Describes the events supported by the QueryBuilder HTC.

  • Properties. Describes the properties supported by the QueryBuilder HTC.

  • Methods. Describes the methods supported by the QueryBuilder HTC.

  • Container Attributes. Describes the attributes that the QueryBuilder HTC expects to be set on the element in which it is contained.

  • Configuration Data. Describes the data passed to the QueryBuilder HTC via the ID used as the value of the XMLCfgID container attribute.

  • Instantiation Example. Demonstrates how the QueryBuilder HTC is instantiated in script on an ASP page.


Events

The QueryBuilder HTC supports the following events:

  • OnActive

  • OnError

  • OnQueryChange

  • OnReady

OnActive

The OnActive event fires when the QueryBuilder HTC enters the active state as a result of the Activate method being called and successfully executed. This event is most useful when the QueryBuilder HTC is being activated as part of the activation of a containing control, which itself cannot be successfully activated unless all of its sub-controls have been successfully activated.

Return to top

OnError

The OnError event fires when activation of the QueryBuilder HTC fails.

Return to top

OnQueryChange

The OnQueryChange event fires when the current query changes, such as when a clause is added, deleted, or modified.

Return to top

OnReady

The OnReady event fires when the QueryBuilder HTC is fully loaded and initialized, indicating that its programmatic interface is ready to use. No properties or methods (including the Activate method) of the QueryBuilder HTC should be called before this event fires.

Return to top


Properties

The QueryBuilder HTC supports the following properties:

  • IsActive

  • IsReady

IsActive

The IsActive property indicates whether the QueryBuilder HTC is currently active. The value of this property is True when the QueryBuilder control is active, that is, when the user can interact with it. The value is False when the control is inactive.

This property is read-only.

Return to top

IsReady

The IsReady property indicates whether the QueryBuilder HTC is ready for programmatic access. The value of this property is False before the OnReady event fires, and True after that event fires. It allows polling to be used to determine whether the control is ready.

This property is read-only.

Return to top


Methods

The QueryBuilder HTC supports the following methods:

  • Activate

  • Deactivate

  • GetExprBody

  • GetExprBodyXML

  • GetProfileList

  • SetExprBody

  • SetExprBodyXML

  • SetExprListXML

Activate(bEdit)

The Activate method activates the QueryBuilder HTC. When the bEdit parameter is True, editing of the displayed query is allowed. If the bEdit parameter is False, editing is not allowed.

This method returns False if a fatal error occurs, and True otherwise.

Return to top

Deactivate

The Deactivate method deactivates the user interface of the QueryBuilder HTC without clearing the current query. It does not take any parameters or return a value.

Return to top

GetExprBody

The GetExprBody method returns a string containing an XML representation of the current query. If there is no current query, it returns NULL.

Return to top

GetExprBodyXML

The GetExprBodyXML method returns an XML DOMDocument object that represents the current query. If there is no current query, it returns nothing.

Return to top

GetProfileList

The GetProfileList method returns a Microsoft Visual Basic Scripting Edition (VBScript) SAFEARRAY containing the names of all of the profiles that are currently loaded in the QueryBuilder HTC. It does not take any parameters.

Return to top

SetExprBody(strExprBody)

The SetExprBody method allows the current query to be set. The only parameter is a string containing XML that specifies the query to be set. It returns True if it can successfully parse the query, and False if the parsing fails.

An empty string or NULL can be passed to clear the current query.

Return to top

SetExprBodyXML(xmlExprBody)

The SetExprBodyXML method allows the current query to be set. The only parameter is an XML DOMDocument object that specifies the query to be set. It returns True if it can successfully parse the query, and False if the parsing fails.

An empty XML DOMDocument object, or the "Nothing" keyword, can be passed to clear the current query.

Return to top

SetExprListXML

The SetExprListXML method allows the caller to provide the QueryBuilder HTC with a list of named expressions from which the QueryBuilder HTC can build other expressions. This method is not likely to be used when the QueryBuilder HTC is being used by itself. Rather, it exists primarily for use by the ExpressionBuilder HTC when it needs to provide the QueryBuilder HTC with a list of named expressions.

Return to top


Container Attributes

In order to pass data to the QueryBuilder HTC, the following attributes must be set on the element that is using the QueryBuilder behavior (this element is typically a DIV):

XMLCfgID

The value of this attribute must be set to the value of the id attribute of the Extensible Markup Language (XML) data-island containing the configuration information for this instance of the QueryBuilder HTC.

AutoActivate

The value of this attribute controls whether the QueryBuilder HTC automatically activates when loading is complete. Legal values are True and False. A value of True causes auto-activation to occur, and a value of False suppresses auto-activation. The default value is False.

Automatic activation allows editing of the displayed query.


Configuration Data

The QueryBuilder HTC requires that its configuration information be passed to it in the form of an Extensible Markup Language (XML) data-island. This information consists of configuration information that controls the behavior of the QueryBuilder HTC, such as what profiles and site terms are available for use in building queries.

For detailed information about the structure of this XML data-island, see QueryBuilder Configuration.

For more information about the ways in which an XML document can be included on a page (creating an XML data-island), see XML Data-Islands.


Instantiation Example

The following HTML code shows a typical instantiation of a QueryBuilder HTC within a DIV element. The Style attribute specifies that the QueryBuilder behavior be associated with this DIV element.

Note

  • In order for the Class attribute to properly identify the QueryBuilder HTC, you must make sure that your pages use the Bizdesk.css style sheet.

The XMLCfgID attribute specifies a configuration data-island that is defined elsewhere within the document. The Language attribute specifies that the QueryBuilder HTC event handlers are implemented in Microsoft Visual Basic Scripting Edition (VBScript). The remaining attributes associate methods defined elsewhere with the specific events supported by the QueryBuilder HTC. Since the AutoActivate attribute is not present, the Activate method must be called explicitly.

Finally, temporary text is provided to inform the user that the QueryBuilder HTC is loading.

  <DIV Id='myQueryBuilder'
       Class='clsQueryBldr'
       Style='behavior:url(/widgets/exprbldrHTC/QueryBuilder.htc); width:100%'
       Language='VBScript'
       XMLCfgID='DataIslandID'
       OnAction='ActionHandler()'
       OnError='ErrorHandler()'
       OnQueryChange='QueryChangeHandler()'
       OnReady='ReadyHandler()'
  >Loading QueryBuilder, please wait...</DIV>


TreeView

The TreeView HTML Component (HTC) directly translates an Extensible Markup Language (XML) hierarchy into an expandable tree structure for use in selection.

It is important to note that the TreeView HTC makes a distinction between a tree item being selected and being active. Selection is visible to the user. The most recently clicked item is the active item, which may or may not cause the item to be selected as well. The active item can also be changed programmatically without changing the selected item. Programmatically setting an active node enables you to then use several methods without having to specify the node again (enableActive, expandActive, and so on).

This section contains:

  • Events. Describes the events supported by the TreeView HTC.

  • Methods. Describes the methods supported by the TreeView HTC.

  • Container Attributes. Describes the attributes that the TreeView HTC expects to be set on the element in which it is contained.

  • Configuration Data. Describes the data passed to the TreeView HTC via the ID used as the value of the DataXML container attribute.

  • Instantiation Example. Demonstrates how the TreeView HTC is instantiated in script on an Active Server Pages (ASP) page.

The TreeView HTC does not expose any properties.


Events

The TreeView HTC supports the following events:

  • OnError

  • OnItemClose

  • OnItemExecute

  • OnItemOpen

  • OnItemSelect

  • OnItemUnselect

OnError

The OnError event fires when the TreeView HTC encounters a developer error condition. In addition, if the m_bDebug variable in the HTC is set to True, an alert box appears. This switch can be very helpful in debugging problems that occur when you get the error message "The control could not load."

The event object property window.event.error contains a string with details about the error.

Return to top

OnItemClose

The OnItemClose event fires when a container item in the tree is closed.

The event object property window.event.XMLitem contains the XML node for the item that has been closed.

Return to top

OnItemExecute

The OnItemExecute event fires when an item in the tree is double-clicked.

The event object property window.event.XMLitem contains the XML node for the item that has been double-clicked.

Return to top

OnItemOpen

The OnItemOpen event fires when a container item in the tree is opened.

The event object property window.event.XMLitem contains the XML node for the item that has been opened.

When the item being opened contains the subordinate element expand (and no other subordinate elements), the event handling routine for this event must attach arguments to the corresponding form element. When it completes, the TreeView HTC calls the reload method with its sOp parameter set to 'expand'. The tree data returned by the form response then replaces the expand element itself in the DataXML data-island, which completes the deferred loading of that section of the tree.

Return to top

OnItemSelect

The OnItemSelect event fires when an item in the tree is selected.

The event object property window.event.XMLitem contains the XML node for the item that has been selected.

Return to top

OnItemUnselect

The OnItemUnselect event fires when a selected item in the tree becomes unselected.

The event object property window.event.XMLitem contains the XML node for the item that is no longer selected.

Return to top


Methods

The TreeView HTC supports the following methods:

  • areRelated

  • enableActive

  • expandActive

  • expandAll

  • hideActive

  • reload

  • selectNode

  • setActive

  • unselectAll

areRelated(sFrom, sTo)

The areRelated method is used to determine whether the two tree items specified by the required parameters sFrom and sTo are related. In other words, one is a descendent of the other. If they are related, this method returns True. If they are not related, this method returns False.

The parameters sFrom and sTo can be either the data contained by the item, or the value of the caption attribute, in the DataXML data-island.

Return to top

enableActive(bEnable)

The enableActive method is used to enable and disable the active item based on the value of the required parameter bEnable. Legal values for bEnable are True and False. A value of True causes the active node to be enabled. A value of False causes it to be disabled.

Return to top

expandActive(bExpand)

The expandActive method is used to expand or collapse the active item based on the value of the required parameter bExpand. Legal values for bExpand are True and False. A value of True causes the active node to be expanded. A value of False causes it to be collapsed.

Return to top

expandAll(bExpand)

The expandAll method is used to expand or collapse the entire tree based on the value of the required parameter bExpand. Legal values for bExpand are True and False. A value of True causes the entire tree to be expanded. A value of False causes the entire tree to be collapsed.

Return to top

hideActive(bHide)

The hideActive method is used to hide and show the active item and its children based on the value of the required parameter bHide. Legal values for bHide are True and False. A value of True causes the active node and its children to be hidden. A value of False causes them to be shown.

Return to top

reload(sOp)

The reload method reloads the data into the TreeView HTC using an operation configured in the DataXML data-island.

The operation is identified by the required sOp parameter, which specifies the name of a child element of the operations element in the DataXML data-island. In general, the element name is an arbitrary name associated with a custom operation.

The exception is a special operation indicated by the expand element. This operation does not reload the entire tree. Rather, it replaces a particular occurrence of an expand element with the data returned from the server, effectively expanding a previously closed section of the tree. Such expansion typically occurs only once for each expand element.

The formid attribute of the matching operation element identifies the form that is posted as a result of this operation. The action attribute of the form specifies the page to which the form is posted.

Any child elements of the form are sent with the form posting.

This method does not have any return values.

Example:

elTreeView.reload("alpha_sort")

Return to top

selectNode(sValue)

The selectNode method selects the first item in the tree that has a data value or caption matching the string passed in the required parameter sValue. If no match is found, no item is selected. This method does not have any return value.

Return to top

setActive(sValue)

The setActive method looks for an item in the tree that has a data value or caption matching the string passed in the required parameter sValue, and sets the first such item as the active item. If no match is found, the currently active item, if any, remains active. This method does not have any return value.

Return to top

unselectAll

The unselectAll method unselects all items in the tree. It does not take any parameters and does not have any return value.

Return to top


Container Attributes

In order to pass data to the TreeView HTC, the following attribute must be set on the element that is using the TreeView behavior (this element is typically a DIV):

DataXML

The value of this attribute must be set to the value of the id attribute of the Extensible Markup Language (XML) data-island containing the combination of operations configuration and data to be displayed.


Configuration Data

The TreeView HTC requires that the tree to be displayed be passed to it in the form of an Extensible Markup Language (XML) data-island. This data-island contains the data to be displayed in the tree, configuration attributes about how that data should be displayed, and configuration information about any custom operations defined for this instance of the TreeView HTC. The container attribute DataXML is set to the value of the id attribute of this data-island.

It is important to note that the TreeView HTC is the only Commerce Server Business Desk HTC for which configuration information is combined into the same data-island with the data itself. In other words, there is no MetaXML container attribute to specify for the TreeView HTC. Data and configuration information are provided in a single data-island, specified by the DataXML container attribute. The nested nature of the elements provides the nesting shown in the displayed tree.

The names of all of the elements in the data-island for the TreeView HTC are arbitrary, though there are circumstances where the element name itself is displayed to the user. The XML elements and attributes in the TreeView HTC configuration may be expressed in uppercase or lowercase letters. The arbitrary elements may contain data, but need not.

For detailed information about the structure of this XML data-island, see TreeView Configuration.

For more information about the ways in which an XML document can be included on a page (creating an XML data-island), see XML Data-Islands.


Instantiation Example

The following HTML code shows a typical instantiation of a TreeView HTC within a DIV element. The Class attribute specifies that the TreeView behavior be associated with this DIV element.

Note

  • In order for the Class attribute to properly identify the TreeView HTC, you must make sure that your pages use the Bizdesk.css style sheet.

The DataXML attribute specifies the ID of the data-island that specifies the tree structure, behavior, and any special operations defined for the tree. This data-island must be defined elsewhere within the document. The Language attribute specifies that the TreeView HTC event handlers are implemented in Microsoft Visual Basic Scripting Edition (VBScript). The remaining attributes associate methods defined elsewhere with the specific events supported by the TreeView HTC.

Finally, temporary text is provided to inform the user that the TreeView HTC is loading.

  <DIV Id='myTreeView'
       Class='TreeView'
       Language='VBScript'
       DataXML='DataIslandID'
       OnError='ErrorHandler()'
       OnItemSelect='ItemSelectHandler()'
       OnItemUnselect='ItemUnselectHandler()'
       OnItemExecute='ExecuteHandler()'
       OnItemOpen='OpenHandler()'
       OnItemClose='CloseHandler()'
  >Loading TreeView, please wait...</DIV>


Include Files

The Commerce Server Business Desk Include directory contains a number of files that provide a variety of functionality for use within Business Desk modules. Not all of them are relevant to authors of Business Desk modules. The following table provides a brief description of the purpose of each relevant file in the Include directory.

File name | Description
ActionPageUtil.asp This Active Server Pages (ASP) file contains much of the implementation of the Business Desk Framework. It contains both server-side and client-side utility functions, constants, and global variables that are useful for module development. It also performs certain universal action page initialization tasks, such as displaying the taskbar.

Nested include files: BizDeskPaths.asp, HTTPXMLUtil.htm, BizDeskStrings.asp, SharedStrings.asp.
ASPUtil.asp This ASP file contains miscellaneous functions that are useful on pages that do not need all of the display-related code that is in the file ActionPageUtil.asp. An example is a page that performs server-side processing and then redirects to another page.

This file contains localizable strings.

Nested include files: None. The file ASPUtil.asp is not dependent on code in any other file.
BDHALUtil.htm This ASP file contains code to resize buttons and select controls to uniform sizes. It is primarily intended for use in HTML dialog boxes.

Nested include files: None. The file BDHALUtil.asp is not dependent on code in any other file.
BDHeader.asp This ASP file contains code to set the codepage, response headers, and script language for HTML pages. It should be included at the top of any page that displays HTML in the Business Desk content pane.

Nested include files: None. The file BDHeader.asp is not dependent on code in any other file.
BDXMLHeader.asp This ASP file contains code to set the codepage, response headers, script language, and XML declaration node for pages that return XML. It should be included at the top of any page that returns XML to one of the Business Desk HTML Components (HTCs) that execute XMLHTTP operations (for example, the ListSheet HTC and the TreeView HTC).

Nested include files: None. The file BDXMLHeader.asp is not dependent on code in any other file.
BizDesk.css | This file is the Cascading Style Sheet for Business Desk. Global changes to how Business Desk appears, such as the colors and fonts used, should be made in this file. All module action pages should specify this file as their style sheet so that they participate in any such global changes. This enhances the overall consistency of Business Desk as new modules are added.
BizDeskObjects.asp The routines in this file are intended for internal framework use only.

This file contains localizable strings for Business Desk developer errors that show only when initially loading the application in DEVELOPER mode.

Nested include files: None. The file BizDeskObjects.asp is not dependent on code in any other file.
BizDeskPaths.asp This ASP file contains the declarations of a number of server-side global variables that store Business Desk paths and Internet Information Server (IIS) virtual roots useful to module code. For more information about these global variables, see Server-Side Global Variables.

Nested include files: None. The file BizDeskPaths.asp is not dependent on code in any other file.
BizDeskStrings.asp This ASP file contains the definitions of string constants used within the Business Desk Framework, greatly reducing the effort required to translate the Business Desk Framework into other languages.

Refer to the include file itself for the particular constants and corresponding strings, as well as documentation about the naming convention used for the constants.

This file contains localizable strings.

Nested include files: None. The file BizDeskStrings.asp is not dependent on code in any other file.
BizDeskUtil.asp This ASP file is normally included by Business Desk module action pages. Its main purpose is to consolidate the inclusion of several other files.

It also contains code to prevent module action pages from being browsed outside the Business Desk Framework. If this code does not detect the Business Desk Framework, it redirects the page to Business Desk.

Nested include files: DBUtil.asp, ASPUtil.asp, BDHALUtil.asp, ActionPageUtil.asp.
DBUtil.asp This ASP file contains a number of server-side functions for creating ActiveX Data Objects (ADO) connections, performing SQL queries, and then converting the data in the resultant Recordset objects into XML data-islands. It also provides numerous ADO constant definitions.

Nested include files: None. The file DBUtil.asp is not dependent on code in any other file.
DialogUtil.asp This ASP file is normally included by Business Desk module dialog pages. Its main purpose is to consolidate the inclusion of several other files, without the redirect code in the file BizDeskUtil.asp.

Nested include files: DBUtil.asp, ASPUtil.asp, BDHALUtil.asp, ActionPageUtil.asp.
dlg_confirm.asp This ASP file is useful for showing a standard confirmation dialog box, and can be passed as an argument to the showModalDialog DOM method. See the file ActionPageUtil.asp for examples.

Nested include files: BDHeader.asp, SharedStrings.asp, BizDeskStrings.asp, BizDeskPaths.asp, ASPUtil.asp.
dlg_debug.htm This ASP file is useful for showing a standard debug dialog box, and can be passed as an argument to the showModalDialog DOM method. See the file HTTPXMLUtil.htm for examples.

Nested include files: None. The file dlg_debug.htm is not dependent on code in any other file.
dlg_error.asp This ASP file is useful for showing a standard error dialog box, and can be passed as an argument to the showModalDialog DOM method. See the file ActionPageUtil.asp for examples.

Nested include files: BDHeader.asp, SharedStrings.asp, BizDeskPaths.asp, ASPUtil.asp.
dlg_warn.asp This ASP file is useful for showing a standard warning dialog box, and can be passed as an argument to the showModalDialog DOM method. See the file ActionPageUtil.asp for examples.

Nested include files: BDHeader.asp, SharedStrings.asp, BizDeskStrings.asp, BizDeskPaths.asp, ASPUtil.asp.
HTTPXMLUtil.asp This ASP file contains a number of server-side functions for creating XML documents, adding nodes to a document in a standard way, converting an XML document to a Dictionary object and vice versa. It also provides functions for retrieving XML posted to an XMLHTTP response page.

Nested include files: None. The file HTTPXMLUtil.asp is not dependent on code in any other file.
HTTPXMLUtil.htm This HTM file contains a number of client-side functions for creating XML documents, adding nodes to a document in a standard way, converting an XML document to a Dictionary object and vice versa. It also provides functions for posting XML to an XMLHTTP response page and various server-side state routines as well (using the response_session.asp response page).

Nested include files: None. The file HTTPXMLUtil.htm is not dependent on code in any other file.
NavTree.css | This style sheet file is used by the navigation pane frame and is not intended to be linked to by any other Business Desk files.
response_session.asp | This file contains code used to set, get, and clear server state via XMLHTTP. Routines in this file are intended for internal framework use only.
SharedStrings.asp This ASP file contains the definitions of string constants used within multiple Business Desk modules that ship as part of Commerce Server 2000. Having such string constants centralized greatly reduces the effort required to translate them into other languages.

Refer to the include file itself for the particular constants and corresponding strings, as well as documentation about the naming convention used for the constants.

Module writers who are authoring multiple modules that share strings or functions can easily add another file for their shared code in the Common folder, provided for this purpose. Microsoft discourages adding code to the file SharedStrings.asp since this may create multiple versions for different third parties.

This file contains localizable strings.

Nested include files: None. The file SharedStrings.asp is not dependent on code in any other file.


Constants

The Commerce Server Business Desk Framework defines a variety of client-side and server-side constants that provide a means to symbolically express values that are likely to be useful when writing Business Desk modules. Wherever possible, module developers should use these constants rather than defining their own equivalent constants or using the underlying values directly.

This section contains:

  • Client-Side Constants. Provides an alphabetized list of all client-side constants provided by the Business Desk Framework.

  • Server-Side Constants. Provides an alphabetized list of all server-side constants provided by the Business Desk Framework.


Client-Side Constants

The Commerce Server Business Desk Framework defines the following client-side constants:

Error Type Constants (from file ActionPageUtil.asp):

Constants to use as the nErrorType parameter of the client-side routine ShowErrorDlg. The passed value communicates the type of the error and the type of error icon displayed by the routine.

Constants:

ERROR_ICON_ALERT, ERROR_ICON_CRITICAL, ERROR_ICON_QUESTION, ERROR_ICON_INFORMATION

Webdings Font Arrow Constants (from file ActionPageUtil.asp):

Character-code constants for elements formatted with the Webdings FONT-FAMILY. These constants correspond to left, right, up, and down arrows.

Constants:

LEFT_ARROW, RIGHT_ARROW, UP_ARROW, DOWN_ARROW


Server-Side Constants

The Commerce Server Business Desk Framework defines the following server-side constants:

Environment Mode Constants (from file BizDeskUtil.asp):

Constants used to set the MSCSEnv variable in the Global.asa file. PRODUCTION mode sets all debug flags to values that should be used for Business Desk in a production environment. DEVELOPMENT mode sets the debug flags to allow greater feedback and functionality useful when developing new Business Desk modules.

Constants:

PRODUCTION, DEVELOPMENT

Error Type Constants (from file ASPUtil.asp):

Constants to use as the nErrorType parameter of the server-side routine SetError. The passed value communicates the type of the error and the type of error icon displayed by the routine.

Constants:

ERROR_ICON_ALERT, ERROR_ICON_CRITICAL, ERROR_ICON_QUESTION, ERROR_ICON_INFORMATION

ADO Constants (from file DBUtil.asp):

Constants to use with ActiveX Data Objects (ADO).

Constants:

Refer to the file DBUtils.asp for details.

Special Date Splitting Constants (from file DBUtil.asp):

A special constant to use in the formatting Dictionary object passed to the Recordset-to-XML conversion routines. It is used to indicate that a single ADO datatime field should be split into two separate fields for separate editing in date and time EditField HTCs. The date portion will be placed in an Extensible Markup Language (XML) element named date_colId and the time portion will be placed in an XML element named time_colId.

Constants:

COMMERCE_SPLIT_DATE

XML Conversion Routine Constant (from file DBUtil.asp):

Constant to use as the recordcount parameter to Recordset-to-XML conversion routines, indicating that the recordset should not be counted.

Constants:

TOO_BIG_TO_COUNT

Locale Constants (from file DBUtil.asp):

Constants to use with the DataFunctions object GetLocaleInfo method.

Constants:

LOCALE_SDECIMAL, LOCALE_STHOUSAND


Global Variables

The Commerce Server Business Desk Framework defines a variety of client-side and server-side global variables that are initialized to values that are useful when writing Business Desk modules. Wherever possible, module developers should use the values already in these global variables rather than constructing their own equivalents.

This section contains:

  • Client-Side Global Variables. Provides an alphabetized list of all client-side global variables provided by the Business Desk Framework.

  • Server-Side Global Variables. Provides an alphabetized list of all server-side global variables provided by the Business Desk Framework.


Client-Side Global Variables

The Commerce Server Business Desk Framework defines the following client-side global variables:

g_bDirty

A Boolean value indicating whether any fields on the page have changed since the last save operation. True indicates that changes have been made since the last save operation, and False indicates that no changes have been made.

This variable is declared and initialized to False in the file ActionPageUtil.asp, and its scope is the action page itself.

g_bRequired

A Boolean value indicating whether any fields on the page still require values to be provided. True indicates that at least one required field does not yet have a value, and False indicates that all required fields have values.

This variable is declared and initialized to False in the file ActionPageUtil.asp, and its scope is the action page itself.

g_bUnloading

A Boolean used to indicate when the page is unloading because a task button was clicked. This forces the framework to suppress the display of the normal Internet Explorer unloading page warning that is displayed after the user clicks the close button for Business Desk.

g_bValid

A Boolean value indicating whether any fields on the page contain values that are not valid. False indicates that one or more fields have a value that is not valid, and True indicates that all fields contain valid values.

This variable is declared and initialized to True in the file ActionPageUtil.asp, and its scope is the action page itself.

g_nFindByHeight

An integer height in pixels for the find pane, initially set to 55 pixels. This variable is set by the SetFindByHeight routine before the ShowFindBy routine is called to display it.


Server-Side Global Variables

The Commerce Server Business Desk Framework defines the following server-side global variables:

ALLOW_CONTEXT_MENUS

A Boolean value that controls whether normal right-click menus will be disabled within Business Desk. A value of True allows normal right-click menus, and a value of False suppresses normal right-click menus.

In the Global.asa file, when the variable MSCSEnv is set to PRODUCTION, the variable ALLOW_CONTEXT_MENUS is set to False. When the variable MSCSEnv is set to DEVELOPMENT, the variable ALLOW_CONTEXT_MENUS is set to True.

There is also an Application object variable with the same name as this global variable.

AUTO_REDIRECT_ENABLED

A Boolean value that controls whether action pages can be displayed outside the Business Desk Framework. A value of True causes any such attempt to be redirected to Business Desk, and a value of False suppresses this redirection behavior.

In the Global.asa file, when the variable MSCSEnv is set to PRODUCTION, the variable AUTO_REDIRECT_ENABLED is set to True. When the variable MSCSEnv is set to DEVELOPMENT, the variable AUTO_REDIRECT_ENABLED is set to False.

There is also an Application object variable with the same name as this global variable.

FORCE_HTA_ONLY

A Boolean value that controls whether an attempt to run Business Desk outside of an HTML application (HTA) environment will result in an error being displayed. A value of True causes any such attempt to result in an error being displayed, and a value of False suppresses this error display behavior.

In the Global.asa file, when the variable MSCSEnv is set to PRODUCTION, the variable FORCE_HTA_ONLY is set to True. When the variable MSCSEnv is set to DEVELOPMENT, the variable FORCE_HTA_ONLY is set to False.

There is also an Application object variable with the same name as this global variable.

g_dActionPage

A reference to a Dictionary object containing the configuration information for the current page, such as the tasks associated with the action that the page implements.

The Dictionary object accessed through this global variable is created in the file ActionPageUtil.asp by calling the routine dGetAction. The scope of the variable is the action page itself.

g_imgInvalid

A string containing HTML that displays the icon used to indicate a value is not valid in edit pages.

g_imgLoadingAnimation

A string containing HTML that displays the loading animation icon.

g_imgRequired

A string containing HTML that displays the required icon used in edit pages.

g_MSCSAdminEventLog

A reference to an object (ProgID = Commerce.AdminEventLog) that provides a mechanism for writing errors to the event log. For more information, see AdminEventLog Object.

Do not call the Initialize method on this shared object.

The object accessed through this global variable is created and initialized in the Global.asa file, and its scope is Application.

g_MSCSAppConfig

A reference to an object (ProgID = Commerce.AppConfig) that provides a mechanism for reading application configuration values. For more information, see AppConfig Object.

Do not call the Initialize method on this shared object.

The object accessed through this global variable is created and initialized in the Global.asa file, and its scope is Application.

g_MSCSBizDeskRoot

A string containing the virtual root name for the current instance of Business Desk.

This variable is declared and initialized in the file BizDeskPaths.asp, and its scope is the action page itself. It is initialized to the value of the Application object setting the variable MSCSBizDeskRoot, which is read from the file Csapp.ini in the Global.asa file.

g_MSCSBizDeskSecurity

A reference to an object (ProgID = Commerce.BizDeskSecurity) that provides a mechanism for filtering the contents of the navigation frame based on the identity of the user. For more information, see BizDeskSecurity Object.

The object accessed through this global variable is created and initialized in the Global.asa file, and its scope is Application.

g_MSCSConfiguration

A reference to an object (ProgID = Commerce.SiteConfigReadOnly) that is instantiated with the site name and is used to retrieve site configuration information from the site store. For more information, see SiteConfigReadOnly Object.

Do not call the Initialize method on this shared object.

The object accessed through this global variable is created and initialized in the Global.asa file, and its scope is Application.

g_MSCSCurrencyLocale

The currency locale ID (LCID) from the Site Configuration Store.

This variable is declared and initialized in the file ActionPageUtil.asp, and its scope is the action page itself. It is initialized to the value of the Application object setting the variable MSCSCurrencyLocale, which is read from the site store in the Global.asa file.

The global variable g_DBCurrencyLocale, set in the file DBUtil.asp, contains the same value.

g_MSCSDataFunctions

A reference to an object (ProgID = Commerce.DataFunctions) that provides generic data functions, such as for data formatting and validation. For more information, see DataFunctions Object.

Do not reset the locale property on this shared object.

The object accessed through this global variable is created and initialized in the Global.asa file, and its scope is Application.

g_MSCSDefaultLocale

The default LCID from the Site Configuration Store.

This variable is declared and initialized in the file ActionPageUtil.asp, and its scope is the action page itself. It is initialized to the value of the Application object setting the variable MSCSDefaultLocale, which is read from the site store in the Global.asa file.

The global variable g_DBDefaultLocale, set in the file DBUtil.asp, contains the same value.

g_MSCSEnv

A number set to one of the server-side constants PRODUCTION or DEVELOPMENT.

Based on the setting of the MSCSEnv variable in the Global.asa file, the default values for the following global variables are established:

VERBOSE_OUTPUT

SHOW_OBJECT_ERRORS

AUTO_REDIRECT_ENABLED

FORCE_HTA_ONLY

ALLOW_CONTEXT_MENU

This global variable is defined and initialized in the file BizDeskUtil.asp. It is initialized to the value of the Application object variable MSCSEnv, which is set in the Global.asa file.

g_MSCSMessageManager

Contains a reference to an object (ProgID = Commerce.MessageManager) that provides a mechanism for retrieving user interface strings from a centralized location. For more information, see MessageManager Object.

Do not reset the DefaultLanguage property on this shared object.

The object accessed through this global variable is created and initialized in the Global.asa file, and its scope is Application.

g_mscsPage

A reference to an object (ProgID = Commerce.Page) that contains useful page helper functions. For more information, see Page Object.

The object accessed through this global variable is created and initialized in the file ActionPageUtil.asp, and the scope of the variable is the action page itself.

g_MSCSSiteName

A string containing the name of the site corresponding to this instance of Business Desk.

This variable is declared and initialized in the file BizDeskPaths.asp, and its scope is the action page itself. It is initialized to the value of the Application object setting the variable MSCSSiteName, which is read from the file Csapp.ini in the Global.asa file.

g_sActionId

A string that contains the Uniform Resource Locator (URL) path and query string of the current page, relative to the Business Desk root folder. This string is known as the Action ID. This value corresponds to the id attribute of one of the action elements in one of the module configuration files.

This variable is declared and initialized in the file ActionPageUtil.asp, and its scope is the action page itself.

g_sBDAssetRoot

A string containing the complete URL path to the Business Desk Assets folder where all shared images are stored.

This variable is declared and initialized in the file BizDeskPaths.asp, and its scope is the action page itself. It is constructed by appending the name of the assets folder ('Assets/') to the end of the string contained in the global variable g_sBizDeskRoot.

g_sBDConfigPath

A string containing the complete file system path to the Business Desk configuration folder where all Business Desk XML configuration files are stored.

This variable is declared and initialized in the file BizDeskPaths.asp, and its scope is the action page itself. It is the file system path equivalent of the virtual path specified by the global variable g_sBizDeskRoot.

g_sBDConfigRoot

A string containing the complete URL path to the Business Desk configuration folder where all XML configuration files are stored.

This variable is declared and initialized in the file BizDeskPaths.asp, and its scope is the action page itself. It is constructed by appending the name of the configuration folder ('Config/') to the end of the string contained in the global variable g_sBizDeskRoot.

g_sBDIncludeRoot

A string containing the complete URL path to the Business Desk include folder.

This variable is declared and initialized in the file BizDeskPaths.asp, and its scope is the action page itself. It is constructed by appending the name of the include folder ('Include/') to the end of the string contained in the global variable g_sBizDeskRoot.

g_sBizDeskRoot

A string containing the complete URL path to the Business Desk folder.

This variable is declared and initialized in the file BizDeskPaths.asp, and its scope is the action page itself. It is constructed by adding slash characters ('/') to the beginning and end of the string contained in the global variable g_MSCSBizDeskRoot.

g_sBizDeskRootPage

A string containing the complete URL path to the master start page of the Business Desk.

This variable is declared and initialized in the file BizDeskPaths.asp, and its scope is the action page itself. It is constructed by appending the name of the master start page (Bizdesk.asp) to the end of the string contained in the global variable g_sBizDeskRoot.

g_sMSCSCurrencyFormat

A string containing a currency format to be used as the data associated with the format element within a numeric element of the currency subtype in the meta-data for an HTML component (HTC).

This variable is declared and initialized in the file ActionPageUtil.asp, and its scope is the action page itself. It is initialized to the value of the Application object setting MSCSCurrencyFormat, which the Global.asa file reads from the site store.

g_sMSCSDateFormat

A string containing a date format to be used as the data associated with the format element within a date element in the meta-data for an HTML component (HTC).

This variable is declared and initialized in the file ActionPageUtil.asp, and its scope is the action page itself. It is initialized to the value of the Application object setting MSCSDateFormat, which the Global.asa file reads from the site store.

g_sMSCSNumberFormat

A string containing a number format to be used as the data associated with the format element within a numeric element of the integer or float sub-type in the meta-data for an HTML component (HTC).

This variable is declared and initialized in the file ActionPageUtil.asp, and its scope is the action page itself. It is initialized to the value of the Application object setting the variable MSCSNumberFormat, which the Global.asa file reads from the site store.

g_sMSCSWeekStartDay

A string specifying the first day of the week, to be used as the data associated with the firstday attribute of a date element in the meta-data for an HTML component (HTC).

This variable is declared and initialized in the file ActionPageUtil.asp, and its scope is the action page itself. It is initialized to the value of the Application object setting the variable MSCSWeekStartDay, which is obtained from the DataFunctions object using the site default locale.

SHOW_DEBUG_TEXT

A Boolean value that controls whether debug text is displayed during certain routines. A value of True causes the debug text to be displayed, and a value of False suppresses the display of the debug text.

In the Global.asa file, when the variable MSCSEnv is set to PRODUCTION, SHOW_DEBUG_TEXT is set to False. When MSCSEnv is set to DEVELOPMENT, SHOW_DEBUG_TEXT is set to True.

There is also an Application object variable with the same name as this global variable.

SHOW_OBJECT_ERRORS

A Boolean value that controls whether object loading errors are displayed in a dialog box upon completion of loading. A value of True causes the dialog box to be displayed, and a value of False suppresses the display of the dialog box.

In the Global.asa file, when the variable MSCSEnv is set to PRODUCTION, SHOW_OBJECT_ERRORS is set to False. When MSCSEnv is set to DEVELOPMENT, SHOW_OBJECT_ERRORS is set to True.

There is also an Application object variable with the same name as this global variable.

VERBOSE_OUTPUT

A Boolean value that controls whether verbose output is provided while page objects are loading for the first time after an Internet Information Service (IIS) reset. A value of True provides verbose output, and a value of False suppresses verbose output.

By default, both possible settings of the variable MSCSEnv in the Global.asa file, PRODUCTION and DEVELOPMENT, result in VERBOSE_OUTPUT being set to False. Modify the Global.asa file as necessary to set this variable to True.

There is also an Application object variable with the same name as this global variable.


Utility Routines

The Commerce Server Business Desk Framework defines a variety of client-side and server-side utility routines that provide standard functionality to Business Desk modules. Wherever possible, module developers should use these routines rather than writing their own.

This section contains:

  • Client-Side Routines. Provides an alphabetized list of all client-side utility routines provided by the Business Desk Framework.

  • Server-Side Routines. Provides an alphabetized list of all server-side utility routines provided by the Business Desk Framework.


Client-Side Routines

The Commerce Server Business Desk Framework defines the following client-side routines for use by modules developers.

Routine | Description
AddCDATANode | Adds a CDATA type item node to the specified Extensible Markup Language (XML) document. Defined in the file HTTPXMLUtil.htm.
AddClass | Adds an additional customizable style sheet (CSS) class to an HTML element. Defined in the file ActionPageUtil.asp.
AddItemNode | Adds an item node to the specified XML document. Defined in the file HTTPXMLUtil.htm.
bHasClass | Determines whether an HTML element has a specific CSS class associated with it. Defined in the file ActionPageUtil.asp.
bIsDate | Determines whether a string contains a valid date. Defined in the file ActionPageUtil.asp.
ClearStatusText | Clears the text in the status bar. Defined in the file ActionPageUtil.asp.
ClearTemp | Removes a value from the Client State Dictionary. Defined in the file ActionPageUtil.asp.
dClearServerState | Clears the server-state Dictionary object stored in the Session object on the server. Defined in the file HTTPXMLUtil.htm.
dDictFromXML | Converts a standard XML document into a Dictionary object. Defined in the file HTTPXMLUtil.htm.
dGetServerState | Makes a client-side copy of the server-state Dictionary object stored in the Session object on the server. Defined in the file HTTPXMLUtil.htm.
DisableTask | Disables the specified task. Defined in the file ActionPageUtil.asp.
DisableTaskMenuItem | Disables the specified task menu item. Defined in the file ActionPageUtil.asp.
dSetServerState | Saves a client-side version of the server-state Dictionary object to the Session object on the server. Defined in the file HTTPXMLUtil.htm.
dtGetDate | Formats a date string into a date variant. Defined in the file ActionPageUtil.asp.
elGetTaskBtn | Returns the specified task button element. Defined in the file ActionPageUtil.asp.
EnableAllTaskMenuItems | Enables or disables all menu items for the specified task. Defined in the file ActionPageUtil.asp.
EnableAllTasks | Enables or disables all tasks. Defined in the file ActionPageUtil.asp.
EnableTask | Enables the specified task. Defined in the file ActionPageUtil.asp.
EnableTaskMenuItem | Enables the specified task menu item. Defined in the file ActionPageUtil.asp.
GetTemp | Returns a specific value from the Client State Dictionary. Defined in the file ActionPageUtil.asp.
HideFindBy | Hides the find pane. Defined in the file ActionPageUtil.asp.
HideStatusAnimation | Hides the status animation and text. Defined in the file ActionPageUtil.asp.
HideStatusLegend | Hides the status legend in the status bar. Defined in the file ActionPageUtil.asp.
HideWaitDisplay | Hides the wait display. Defined in the file ActionPageUtil.asp.
nGetDay | Returns the day from a date string, as a number. Defined in the file ActionPageUtil.asp.
nGetMonth | Returns the month from a date string, as a number. Defined in the file ActionPageUtil.asp.
nGetYear | Returns the year from a date string, as a number. Defined in the file ActionPageUtil.asp.
OpenEditPage | Opens a nested edit page. Defined in the file ActionPageUtil.asp.
OpenHelp | Opens the help window and displays the specified topic. Defined in the file ActionPageUtil.asp.
RemoveClass | Removes a specified CSS class from an HTML element. Defined in the file ActionPageUtil.asp.
ReplaceClass | Replaces one CSS class with another within an HTML element. Defined in the file ActionPageUtil.asp.
ResetSaveBtns | Enables or disables the save buttons (Save, SaveBack, and SaveNew) based on the dirty, valid, and required states. Defined in the file ActionPageUtil.asp.
SetDirty | Sets the dirty flag for the page and establishes a confirmation message. Defined in the file ActionPageUtil.asp.
SetFindByHeight | Sets the height of the find pane. Defined in the file ActionPageUtil.asp.
SetPageTitleText | Sets the page title. Defined in the file ActionPageUtil.asp.
SetRequired | Sets the required flag for the page and establishes a warning message. Defined in the file ActionPageUtil.asp.
SetStatusText | Displays a specified string in the status area. Defined in the file ActionPageUtil.asp.
SetTaskTooltip | Sets a tooltip string for the specified task. Defined in the file ActionPageUtil.asp.
SetTemp | Stores a value in the Client State Dictionary. Defined in the file ActionPageUtil.asp.
SetValid | Sets the valid flag for the page and establishes a warning message. Defined in the file ActionPageUtil.asp.
SetWaitDisplayText | Sets new text in the wait display. Defined in the file ActionPageUtil.asp.
sFormatString | Performs string formatting using a format string with variable insertion points, similar to the C++ printf function. Defined in the file ActionPageUtil.asp.
sGetFormattedDate | Returns a date string constructed from numbers representing day, month, and year. Defined in the file ActionPageUtil.asp.
sGetScriptError | Formats a script error into a string containing HTML table formatting directives. Defined in the file ActionPageUtil.asp.
sGetXMLError | Formats an XML error into a string containing HTML table formatting directives. Defined in the file ActionPageUtil.asp.
ShowErrorDlg | Displays a standard error dialog box. Defined in the file ActionPageUtil.asp.
ShowFindBy | Shows the find pane. Defined in the file ActionPageUtil.asp.
ShowWaitDisplay | Shows the wait display. Defined in the file ActionPageUtil.asp.
ShowXMLNodeErrors | Displays an error dialog box for each error node in the specified XML document. Defined in the file HTTPXMLUtil.htm.
sMergeGroups2 | Merges two single-tiered XML documents in the standard XML data record format into a single two-tiered XML document in the same format, returning the result as a string. Defined in the file ActionPageUtil.asp.
sMergeGroups3 | Merges three single-tiered XML documents in the standard XML data record format into a single three-tiered XML document in the same format, returning the result as a string. Defined in the file ActionPageUtil.asp.
ToggleFindBy | Displays or hides the find pane to the opposite of its current display state. Defined in the file ActionPageUtil.asp.
ToggleTask | Toggles the enabled/disabled state of the specified task. Defined in the file ActionPageUtil.asp.
xmlGetSiteTermsValue | Displays a standard Site Terms Picker dialog box, allowing the user to choose one of several values for a given property. Defined in the file ActionPageUtil.asp.
xmlGetXMLDOMDoc | Returns an empty XML DOM Document. Defined in HTTPXMLUtil.htm.
xmlMergeGroups2 | Merges two single-tiered XML documents in the standard XML data record format into a single two-tiered XML document in the same format, returning the result as an XML document node. Defined in the file ActionPageUtil.asp.
xmlMergeGroups3 | Merges three single-tiered XML documents in the standard XML data record format into a single three-tiered XML document in the same format, returning the result as an XML document node. Defined in the file ActionPageUtil.asp.
xmlMergeGroupsByID2 | Merges two single-tiered XML data-islands in the standard XML data record format into a single two-tiered XML document in the same format, returning the result as an XML document node. Defined in the file ActionPageUtil.asp.
xmlMergeGroupsByID3 | Merges three single-tiered XML data-islands in the standard XML data record format into a single three-tiered XML document in the same format, returning the result as an XML document node. Defined in the file ActionPageUtil.asp.
xmlPostFormViaXML | Posts a form via XMLHTTP transfer and then returns the XML response from the action page. Defined in the file HTTPXMLUtil.htm.
xmlXMLFromDict | Converts a Dictionary object into a standard XML document. Defined in the file HTTPXMLUtil.htm.
xmlXMLFromForm | Converts the element values within a form element to a standard XML format. Defined in the file HTTPXMLUtil.htm.

The following lists show client-side routines that are not intended to be called by module code, organized alphabetically and by the include file in which they appear.

ActionPageUtil.asp

bCheckTask, CloseMenu, DoTask, ExecuteTask, GotoAction, nGetDatePart, PosttoAction, RemoveSelection, SetEditMode, SetSelection, doc_onContextMenu, doc_onDragStart, doc_onKeyDown, doc_onSelectStart, menu_onClick, menu_onKeyDown, menu_onMouseMove, menu_onMouseOver, task_onKeyDown, task_onMouseDown, task_onMouseOut, task_onMouseOver, taskWindow_onBeforeUnload, taskWindow_onLoad, taskWindow_onMouseOver

dlg_confirm.asp

closeWindow

dlg_error.asp

closeWindow, sFormatString, toggleDetails

dlg_warn.asp

closeWindow

HTTPXMLUtil.asp

xmlUpdateServerState


AddCDATANode (client-side)

Use this routine to add a CDATA type item element to the specified XML document, using the passed strings to initialize the element.

Definition

AddCDATANode(byRef xmlDoc,

             byVal sName,

             byVal sValue)

Parameters

xmlDoc

A reference to the XML DOMDocument object to which the new node is added.

sName

A string containing a value assigned to the name attribute of the new item element.

sValue

A string containing the value to be placed within the CDATA construct that is assigned as the text of the item element.

Return Value

None.

Remarks

The string version of the added element has the following form:

<item name="sName"><![CDATA[sValue]]></item>

This routine is available in the include file HTTPXMLUtil.htm.

There is a functionally equivalent version of this routine defined for server-side use in the file HTTPXMLUtil.asp. Note that this other routine does not make use of the xmlDoc parameter, but instead adds the CDATA node to a globally accessible XML document.

See Also

Client-Side Routines

AddItemNode (client-side)

xmlGetXMLDOMDoc (client-side)

Server-Side Routines

AddCDATANode (server-side)


AddClass (client-side)

Use this routine to add a customizable style sheet (CSS) class to the space-delimited list of classes associated with the className attribute of a specific HTML element.

Definition

AddClass(elItem,

         sNewClass)

Parameters

elItem

An HTML element to which the specified CSS class will be added.

sNewClass

A string containing the name of the CSS class to be added to the specified HTML element.

Return Value

None.

Remarks

The new CSS class is added to any existing CSS classes, the latter of which are not affected.

This routine is available in the include file ActionPageUtil.asp.

See Also

Client-Side Routines

bHasClass (client-side)

RemoveClass (client-side)

ReplaceClass (client-side)

Server-Side Routines


AddItemNode (client-side)

Use this routine to add an item element to the specified XML document using the passed parameters.

Definition

AddItemNode(byRef xmlDoc,

            byVal sName,

            byVal sValue)

Parameters

xmlDoc

A reference to the XML DOMDocument object to which the new item element will be added.

sName

A string containing the value to be assigned to the name attribute of the new item element.

sValue

A string containing the value to be assigned to the value attribute of the new item element.

Return Value

None.

Remarks

The string version of the added element has the following form:

<item name="sName" value="sValue"/>

This routine is available in the include file HTTPXMLUtil.htm.

There is a functionally equivalent version of this routine defined for server-side use in the file HTTPXMLUtil.asp. Note that this other routine does not make use of the xmlDoc parameter, but instead adds the CDATA node to a globally accessible XML document.

See Also

Client-Side Routines

AddCDATANode (client-side)

xmlGetXMLDOMDoc (client-side)

Server-Side Routines

AddItemNode (server-side)


bHasClass (client-side)

Use this routine to determine whether a particular customizable style sheet (CSS) class is associated with a specific HTML element.

Definition

bHasClass(elItem,

          sClass)

Parameters

elItem

An HTML element to be checked for the specified CSS class.

sClass

A string containing the name of the CSS class for which to check.

Return Value

A Boolean value indicating whether the specified CSS class is associated with the specified HTML element. A return value of True indicates that the CSS class was found in the className attribute of the element, and a return value of False indicates it was not found.

Remarks

This routine is available in the include file ActionPageUtil.asp.

See Also

Client-Side Routines

AddClass (client-side)

RemoveClass (client-side)

ReplaceClass (client-side)

Server-Side Routines


bIsDate (client-side)

Use this routine to test whether a specified string contains a valid date in the format of the default locale for the site.

Definition

bIsDate(sValue)

Parameters

sValue

A string containing the date to be tested against the format indicated by the global variable g_sMSCSDateFormat.

Return Value

A Boolean value indicating whether the passed date string is formatted appropriately for the default locale of the site. A return value of True indicates that the date is valid. A return value of False indicates that the date is not valid.

Remarks

This routine is available in the include file ActionPageUtil.asp.

See Also

Client-Side Routines

dtGetDate (client-side)

nGetDay (client-side)

nGetMonth (client-side)

nGetYear (client-side)

sGetFormattedDate (client-side)

Server-Side Routines


ClearStatusText (client-side)

Use this routine to clear the text in the status area.

Definition

ClearStatusText

Parameters

None.

Return Value

None.

Remarks

This routine is only available after the taskbar has been inserted by invoking either InsertTaskBar or InsertEditTaskBar.

This routine is available in the include file ActionPageUtil.asp.

See Also

Client-Side Routines

HideStatusAnimation (client-side)

HideStatusLegend (client-side)

SetStatusText (client-side)

Server-Side Routines


ClearTemp (client-side)

Use this routine to remove a value or object from the Client State Dictionary stored in the parent frame. A specific key is passed to identify the value or object.

Definition

ClearTemp(sName)

Parameters

sName

A string used as the key of the value or object to be removed from the Client State Dictionary.

Return Value

None.

Remarks

This routine is only available after the taskbar has been inserted by invoking either InsertTaskBar or InsertEditTaskBar.

This routine is available in the include file ActionPageUtil.asp.

See Also

Client-Side Routines

GetTemp (client-side)

SetTemp (client-side)

Server-Side Routines


dClearServerState (client-side)

Use this routine to clear a server-state Dictionary object stored in the Session object on the server.

Definition

dClearServerState(byVal sDictName)

Parameters

sDictName

A string containing the name of session variable with which the server-state Dictionary object is associated.

Return Value

An empty Dictionary object.

Remarks

This routine clears the Dictionary object by posting an XML request to the server, removing the Commerce Dictionary object from the session, and then returning an empty Scripting Dictionary object. This routine posts to the file response_session.asp.

This routine is available in the include file HTTPXMLUtil.htm.

See Also

Client-Side Routines

dGetServerState (client-side)

dSetServerState (client-side)

Server-Side Routines


dDictFromXML (client-side)

Use this routine to convert an XML document with child nodes of the form <item name="keyname" value="value"/> into a Dictionary object.

Definition

dDictFromXML(byRef xmlDOMDoc)

Parameters

xmlDOMDoc

An XML DOMDocument object to be converted.

Return Value

A Dictionary object containing the converted XML document contents.

Remarks

Each name and value attribute becomes an entry in the Dictionary object where the name is the key and the value attribute contains the value.

This routine is available in the include file HTTPXMLUtil.htm.

There is a functionally equivalent version of this routine defined for server-side use in the file HTTPXMLUtil.asp.

See Also

Client-Side Routines

xmlXMLFromDict (client-side)

xmlXMLFromForm (client-side)

Server-Side Routines

dDictFromXML (server-side)


dGetServerState (client-side)

Use this routine to make a client-side copy of a server-state Dictionary object stored in the Session object on the server.

Definition

dGetServerState(byVal sDictName)

Parameters

sDictName

Name of the session variable associated with the server-state Dictionary object.

Return Value

A Dictionary object initialized with the current values set in the specified Dictionary object stored in the Session object on the server.

Remarks

This routine gets the Dictionary object by posting an XML request to the server, converting the Commerce Dictionary object stored in the Session object to XML, and then returning it to the client where the XML is converted back to a scripting Dictionary object. This routine posts to the file response_session.asp.

This routine is available in the include file HTTPXMLUtil.htm.

See Also

Client-Side Routines

dClearServerState (client-side)

dSetServerState (client-side)

Server-Side Routines


DisableTask (client-side)

Use this routine to disable a specific task, dimming the button associated with the task.

Definition

DisableTask(sID)

Parameters

sID

A string that matches the id attribute of the corresponding task element in the relevant module configuration file.

Return Value

None.

Remarks

Given the ID of a task button element, this routine disables the task by setting the following attributes of the task element to the indicated values:

  • disabled set to True

  • className with "bdtaskdisabled" appended

This routine is only available after the taskbar has been inserted by calling either the InsertTaskBar method or the InsertEditTaskBar method.

This routine is available in the include file ActionPageUtil.asp.

See Also

Client-Side Routines

EnableAllTasks (client-side)

EnableTask (client-side)

ToggleTask (client-side)

Server-Side Routines


DisableTaskMenuItem (client-side)

Use this routine to disable a specific task menu item.

Definition

DisableTaskMenuItem(sID,

                    nItem)

Parameters

sID

A string that matches the id attribute of the corresponding task element in the relevant module configuration file.

nItem

A number indicating the position of the menu item to be disabled, counting from 0 (zero) rather than 1 (one).

Return Value

None.

Remarks

Given the ID of a task button menu element and the zero-based position of an item in the menu, this routine disables the task menu item by setting the following attributes of the task element menu to the indicated values:

  • className with "bdtaskdisabled" appended

This routine is only available after the taskbar has been inserted by calling either InsertTaskBar or InsertEditTaskBar.

This routine is available in the include file ActionPageUtil.asp.

See Also

Client-Side Routines

EnableAllTaskMenuItems (client-side)

EnableTaskMenuItem (client-side)

Server-Side Routines


dSetServerState (client-side)

Use this routine to store the contents of a client-side Dictionary object in a server-side Dictionary object saved within the Session object on the server.

Definition

dSetServerState(byVal sDictName,

                byRef dServerState)

Parameters

sDictName

A string containing the session variable name to associate with the stored Dictionary object.

dServerState

A Dictionary object containing the entries to be copied to an equivalent Dictionary object on the server.

Return Value

A Dictionary object containing a copy of the current state of the Server State Dictionary in the Session object.

Remarks

This routine transfers the Dictionary object by converting it to XML, posting to the server, converting the XML to a Commerce Dictionary object, and then adding it to the Session object using the given name. This routine posts to the file response_session.asp.

This routine is available in the include file HTTPXMLUtil.htm.

See Also

Client-Side Routines

dClearServerState (client-side)

dGetServerState (client-side)

Server-Side Routines


dtGetDate (client-side)

Use this routine to convert a date string into a date variant.

Definition

dtGetDate(sValue)

Parameters

sValue

A string containing a date in the format indicated by the g_sMSCSDateFormat global variable, from which the day is retrieved.

Return Value

A date variant initialized to the same date as provided in the passed string. If an error is encountered, the date variant is initialized to the current date.

Remarks

This routine is available in the include file ActionPageUtil.asp.

See Also

Client-Side Routines

bIsDate (client-side)

nGetDay (client-side)

nGetMonth (client-side)

nGetYear (client-side)

sGetFormattedDate (client-side)

Server-Side Routines


elGetTaskBtn (client-side)

Use this routine to retrieve a specific task button element.

Definition

elGetTaskBtn(sID)

Parameters

sID

A string identifier that matches the id attribute of the corresponding task element in the relevant module configuration file.

Return Value

The task button element corresponding to the specified identifier.

Remarks

This routine is only available after the taskbar has been inserted by calling either InsertTaskBar or InsertEditTaskBar.

This routine is available in the include file ActionPageUtil.asp.

See Also

Client-Side Routines

Server-Side Routines


EnableAllTaskMenuItems (client-side)

Use this routine to either enable or disable all menu items for a specified task. Menu items are enabled or disabled based on a passed Boolean parameter.

Definition

EnableAllTaskMenuItems(sID,

                       bEnable)

Parameters

sID

A string identifier that matches the id attribute of the corresponding task element in the relevant module configuration file.

bEnable

A Boolean value that specifies whether all menu items for the specified task should be enabled or disabled. A value of True enables all menu items; a value of False disables all menu items.

Return Value

None.

Remarks

This routine is only available after the taskbar has been inserted by calling either InsertTaskBar or InsertEditTaskBar.

This routine is available in the include file ActionPageUtil.asp.

See Also

Client-Side Routines

DisableTaskMenuItem (client-side)

EnableTaskMenuItem (client-side)

Server-Side Routines


EnableAllTasks (client-side)

Use this routine to either enable or disable all tasks. The tasks are enabled or disabled based on a passed Boolean parameter.

Definition

EnableAllTasks(bEnable)

Parameters

bEnable

A Boolean value that specifies whether all tasks should be enabled or disabled. A value of True enables all tasks; a value of False disables all tasks.

Return Value

None.

Remarks

This routine is only available after the taskbar has been inserted by calling either InsertTaskBar or InsertEditTaskBar.

This routine is available in the include file ActionPageUtil.asp.

See Also

Client-Side Routines

DisableTask (client-side)

EnableTask (client-side)

ToggleTask (client-side)

Server-Side Routines


EnableTask (client-side)

Use this routine to enable the specified task, undimming the button associated with the task.

Definition

EnableTask(sID)

Parameters

sID

A string identifier that matches the id attribute of the corresponding task element in the relevant module configuration file.

Return Value

None.

Remarks

Given the ID of a task button element, this routine enables the task by setting the following attributes of the task element to the indicated values:

  • disabled set to False

  • className with "bdtaskdisabled" removed

This routine is only available after the taskbar has been inserted by calling either InsertTaskBar or InsertEditTaskBar.

This routine is available in the include file ActionPageUtil.asp.

See Also

Client-Side Routines

DisableTask (client-side)

DisableTaskMenuItem (client-side)

EnableAllTaskMenuItems (client-side)

EnableAllTasks (client-side)

EnableTaskMenuItem (client-side)

ToggleTask (client-side)

Server-Side Routines


EnableTaskMenuItem (client-side)

Use this routine to enable a specific task menu item.

Definition

EnableTaskMenuItem(sID,

                   nItem)

Parameters

sID

A string identifier that matches the id attribute of the corresponding task element in the relevant module configuration file.

nItem

The position of the menu item to be enabled, counting from 0 (zero) rather than 1 (one).

Return Value

None.

Remarks

Given the ID of a task button menu element and the zero-based position of an item in the menu, this routine enables the task menu item by setting the following attributes of the task element menu to the indicated values:

  • className with "bdtaskdisabled" removed

This routine is only available after the taskbar has been inserted by calling either InsertTaskBar or InsertEditTaskBar.

This routine is available in the include file ActionPageUtil.asp.

See Also

Client-Side Routines

DisableTaskMenuItem (client-side)

EnableAllTaskMenuItems (client-side)

EnableTask (client-side)

Server-Side Routines


GetTemp (client-side)

Use this routine to retrieve a value or object from the Client State Dictionary stored in the parent frame. A specific key is passed as a parameter to identify the value or object.

Definition

GetTemp(sName)

Parameters

sName

A string used as the key of the value or object to be retrieved from the Client State Dictionary.

Return Value

The value or object being retrieved from the Client State Dictionary. If the key is not found, Nothing is returned.

Remarks

This routine is only available after the taskbar has been inserted by invoking either InsertTaskBar or InsertEditTaskBar.

This routine is available in the include file ActionPageUtil.asp.

See Also

Client-Side Routines

ClearTemp (client-side)

SetTemp (client-side)

Server-Side Routines


HideFindBy (client-side)

Use this routine to hide the find pane.

Definition

HideFindBy

Parameters

None.

Return Value

None.

Remarks

This routine is only available after the taskbar has been inserted by calling either InsertTaskBar or InsertEditTaskBar.

This routine is available in the include file ActionPageUtil.asp.

See Also

Client-Side Routines

ShowFindBy (client-side)

ToggleFindBy (client-side)

SetFindByHeight (client-side)

Server-Side Routines


HideStatusAnimation (client-side)

Use this routine to hide the status animation icon and the text in the status area.

Definition

HideStatusAnimation

Parameters

None.

Return Value

None.

Remarks

This routine is called automatically by the taskbar upon loading.

You may want to show the status animation while the page is busy, and then use this routine to hide it again when the page becomes idle.

This routine is only available after the taskbar has been inserted by calling either InsertTaskBar or InsertEditTaskBar.

This routine is available in the include file ActionPageUtil.asp.

See Also

Client-Side Routines

ClearStatusText (client-side)

HideStatusLegend (client-side)

SetStatusText (client-side)

Server-Side Routines


HideStatusLegend (client-side)

Use this routine to hide the status legend in the status area.

Definition

HideStatusLegend

Parameters

None.

Return Value

None.

Remarks

This routine is only available after the taskbar has been inserted by calling either InsertTaskBar or InsertEditTaskBar.

This routine is available in the include file ActionPageUtil.asp.

See Also

Client-Side Routines

ClearStatusText (client-side)

HideStatusAnimation (client-side)

SetStatusText (client-side)

Server-Side Routines


HideWaitDisplay (client-side)

Use this routine to hide the wait display.

Definition

HideWaitDisplay

Parameters

None.

Return Value

None.

Remarks

This routine is called automatically by the taskbar upon loading.

This routine is only available after the taskbar has been inserted by calling either InsertTaskBar or InsertEditTaskBar.

This routine is available in the include file ActionPageUtil.asp.

See Also

Client-Side Routines

SetWaitDisplayText (client-side)

ShowWaitDisplay (client-side)

Server-Side Routines


nGetDay (client-side)

Use this routine to retrieve the day portion of a specified date string, returned as a number between 1 and 31.

Definition

nGetDay(sValue)

Parameters

sValue

A string containing a date in the format indicated by the g_sMSCSDateFormat global variable, from which the day is retrieved.

Return Value

A number representing the day portion of the specified date string. A return value of –1 indicates an error.

Remarks

This routine is available in the include file ActionPageUtil.asp.

See Also

Client-Side Routines

bIsDate (client-side)

dtGetDate (client-side)

nGetMonth (client-side)

nGetYear (client-side)

sGetFormattedDate (client-side)

Server-Side Routines


nGetMonth (client-side)

Use this routine to retrieve the month portion of a specified date string, returned as a number between 1 and 12.

Definition

nGetMonth(sValue)

Parameters

sValue

A string containing a date in the format indicated by the g_sMSCSDateFormat global variable, from which the month is retrieved.

Return Value

A number representing the month portion of the specified date string. A return value of –1 indicates an error.

Remarks

This routine is available in the include file ActionPageUtil.asp.

See Also

Client-Side Routines

bIsDate (client-side)

dtGetDate (client-side)

nGetDay (client-side)

nGetYear (client-side)

sGetFormattedDate (client-side)

Server-Side Routines


nGetYear (client-side)

Use this routine to retrieve the year portion of a specified date string, returned as a four-digit number.

Definition

nGetYear(sValue)

Parameters

sValue

A string containing a date in the format indicated by the g_sMSCSDateFormat global variable, from which the year is retrieved.

Return Value

A number representing the year portion of the specified date string. A return value of –1 indicates an error.

Remarks

This routine is available in the include file ActionPageUtil.asp.

See Also

Client-Side Routines

bIsDate (client-side)

dtGetDate (client-side)

nGetDay (client-side)

nGetMonth (client-side)

sGetFormattedDate (client-side)

Server-Side Routines


OpenEditPage (client-side)

Use this routine to display a nested edit page in a new frame, hiding the frame of the calling edit page. This routine also records the callback routine to be invoked when the nested edit page is closed.

Definition

OpenEditPage(sPage,

             fnCallback)

Parameters

sPage

The URL of the nested edit page, including any appended arguments. The URL can be relative or absolute.

fnCallback

The name of a callback routine to be invoked when the nested edit page is closed.

Return Value

None.

Remarks

Since this routine does not support posting to a form, any arguments needed by the nested edit page must be appended to its URL.

This routine is only available after the taskbar has been inserted by calling either InsertTaskBar or InsertEditTaskBar.

This routine is available in the include file ActionPageUtil.asp.

See Also

Client-Side Routines

OpenHelp (client-side)

dGetServerState (client-side)

dSetServerState (client-side)

dClearServerState (client-side)

Server-Side Routines


OpenHelp (client-side)

Use this routine to open the help window to the specified topic.

Definition

OpenHelp(sHelpTopicPage)

Parameters

sHelpTopicPage

The (pathless) name of the help topic page in the folder 'bizdesk\docs\htm'.

Return Value

None.

Remarks

If the topic string is empty, the help window is opened to the initial page.

The name of the help topic page must include the '.htm' extension.

This routine is available in the include file ActionPageUtil.asp.

See Also

Client-Side Routines

Server-Side Routines


RemoveClass (client-side)

Use this routine to remove a class from the space-delimited list of classes associated with the className attribute of a specific HTML element.

Definition

RemoveClass(elItem,

            sClass)

Parameters

elItem

The HTML element for which the specified class will be removed.

sClass

A string containing the name of the class to be removed from the specified HTML element.

Return Value

None.

Remarks

The specified class is removed from the existing set of classes without affecting any of the other classes.

This routine is available in the include file ActionPageUtil.asp.

See Also

Client-Side Routines

AddClass (client-side)

bHasClass (client-side)

ReplaceClass (client-side)

Server-Side Routines


ReplaceClass (client-side)

Use this routine to replace one class with another class in the space-delimited list of classes associated with the className attribute of a specific HTML element.

Definition

ReplaceClass(elItem,

             sOldClass,

             sNewClass)

Parameters

elItem

The HTML element for which a new class will replace an existing class.

sOldClass

A string containing the name of the class being replaced in the specified HTML element.

sNewClass

A string containing the name of the class to replace the class specified by the sOldClass parameter.

Return Value

None.

Remarks

The new class replaces the specified old class without affecting any other existing classes.

This routine is available in the include file ActionPageUtil.asp.

See Also

Client-Side Routines

AddClass (client-side)

bHasClass (client-side)

RemoveClass (client-side)

Server-Side Routines


ResetSaveBtns (client-side)

Enables or disables the save buttons (Save, SaveBack, and SaveNew) based on the current dirty, valid, and required states.

Definition

ResetSaveBtns

Parameters

None.

Return Value

None.

Remarks

This routine is only available after the taskbar has been inserted by calling either InsertTaskBar or InsertEditTaskBar.

This routine is automatically called by the routines SetDirty, SetRequired, and SetValid after they update their corresponding flags.

If the page is not marked as dirty and all required data is present and valid, the save buttons are enabled. Otherwise they are disabled.

This routine is available in the include file ActionPageUtil.asp.

See Also

Client-Side Routines

SetDirty (client-side)

SetRequired (client-side)

SetValid (client-side)

Server-Side Routines


SetDirty (client-side)

Use this routine to set the dirty flag for the page and set a confirmation message to be displayed in the event that the page is closed without having been saved.

Definition

SetDirty(sConfirmMsg)

Parameters

sConfirmMsg

A string containing a confirmation message phrased as "Save XXX before exiting?" For example, "Save product description before exiting?"

Return Value

None.

Remarks

There are three common ways in which this routine can be called:

  • Directly from script code on the page when the page logic determines that something must be saved before the page is closed.

  • As the handler of the OnChange event of the master EditSheet for the page (set as an attribute of the container element of the EditSheet HTC):
    onchange='SetDirty("Save product description before exiting?")'
  • From within the handler of the OnChange event of the master EditSheet for the page.

This routine is only available after the taskbar has been inserted by calling either InsertTaskBar or InsertEditTaskBar.

This routine is available in the include file ActionPageUtil.asp.

See Also

Client-Side Routines

SetRequired (client-side)

SetValid (client-side)

Server-Side Routines


SetFindByHeight (client-side)

This routine sets the height of the find pane to the specified number of pixels.

Definition

SetFindByHeight(nNewHeight)

Parameters

nNewHeight

An integer that specifies a new height, in pixels, for the find pane.

Return Value

None.

Remarks

The default height of the find pane is 55 pixels.

This routine is only available after the taskbar has been inserted by calling either InsertTaskBar or InsertEditTaskBar.

This routine is available in the include file ActionPageUtil.asp.

See Also

Client-Side Routines

HideFindBy (client-side)

ShowFindBy (client-side)

Server-Side Routines


SetPageTitleText (client-side)

Use this routine to display specific text in the title bar of the page.

Definition

SetPageTitleText(sText)

Parameters

sText

A string containing text to be displayed in the title bar of the page.

Return Value

None.

Remarks

The page title to be displayed cannot contain HTML tags.

This routine is only available after the taskbar has been inserted by calling either InsertTaskBar or InsertEditTaskBar.

This routine is available in the include file ActionPageUtil.asp.

See Also

Client-Side Routines

SetStatusText (client-side)

SetWaitDisplayText (client-side)

Server-Side Routines


SetRequired (client-side)

Use this routine to set the required flag for the page and set a warning message to be displayed in the event that an attempt is made to save the page when one or more required fields are empty.

Definition

SetRequired(sWarnMsg)

Parameters

sWarnMsg

A string containing a warning message phrased as "You have made incomplete changes to properties. Click 'OK' to discard the changes and exit."

Return Value

None.

Remarks

There are two common ways in which this routine can be called:

  • As the handler of the OnRequire event of the master EditSheet for the page (set as an attribute of the container element of the EditSheet HTC):
    sWarnMsg = "You have made incomplete changes to properties. " & _
           "Click 'OK' to discard the changes and exit."
. . .
onrequire="SetRequired(sWarnMsg)"
  • From within the handler of the OnRequire event of the master EditSheet for the page.

This routine is only available after the taskbar has been inserted by calling either InsertTaskBar or InsertEditTaskBar.

This routine is available in the include file ActionPageUtil.asp.

See Also

Client-Side Routines

SetDirty (client-side)

SetValid (client-side)

Server-Side Routines


SetStatusText (client-side)

Use this routine to display the specified text in the status area of the page.

Definition

SetStatusText(sText)

Parameters

sText

A string containing a status message to be displayed in the status area.

Return Value

None.

Remarks

The status message to be displayed cannot contain HTML tags.

Any status text displayed is automatically cleared after approximately 10 seconds.

This routine is only available after the taskbar has been inserted by calling either InsertTaskBar or InsertEditTaskBar.

This routine is available in the include file ActionPageUtil.asp.

See Also

Client-Side Routines

ClearStatusText (client-side)

HideStatusAnimation (client-side)

HideStatusLegend (client-side)

Server-Side Routines


SetTaskTooltip (client-side)

Use this routine to set a new tooltip for a specific task.

Definition

SetTaskTooltip(sID,

               sTooltip)

Parameters

sID

A string identifier that matches the id attribute of the corresponding task element in the relevant module configuration file.

sTooltip

A string containing the new tooltip to be associated with the specified task.

Return Value

None.

Remarks

This routine sets the title attribute of the specified task element to the specified string. This string is displayed as the tooltip for the associated task button.

The string passed as the sTooltip parameter should not contain any HTML markup directives.

This routine is only available after the taskbar has been inserted by calling either InsertTaskBar or InsertEditTaskBar.

This routine is available in the include file ActionPageUtil.asp.

See Also

Client-Side Routines

SetPageTitleText (client-side)

SetStatusText (client-side)

SetWaitDisplayText (client-side)

Server-Side Routines


SetTemp (client-side)

Use this routine to save a value or object in the Client State Dictionary stored in the parent frame.

Definition

SetTemp(sName,

        oValue)

Parameters

sName

A string used as the dictionary key for the value to be stored. This key is used for retrieval of the value at a later time.

oValue

Any Variant value (string, numeric, array, object, and so on) to be stored in the Client State Dictionary for later retrieval.

Return Value

None.

Remarks

If another value with the specified key already exists in the dictionary, it is overwritten with the new value.

This routine is only available after the taskbar has been inserted by calling either InsertTaskBar or InsertEditTaskBar.

This routine is available in the include file ActionPageUtil.asp.

See Also

Client-Side Routines

ClearTemp (client-side)

GetTemp (client-side)

Server-Side Routines


SetValid (client-side)

Use this routine to set the valid flag for the page and set a warning message to be displayed in the event that an attempt is made to save the page when one or more fields have values that are not valid.

Definition

SetValid(sWarnMsg)

Parameters

sWarnMsg

A string containing a warning message phrased as "You have made incomplete changes to properties. Click 'OK' to discard the changes and exit."

Return Value

None.

Remarks

There are two common ways in which this routine can be called:

  • As the handler of the OnValid event of the master EditSheet for the page (set as an attribute of the container element of the EditSheet HTC):
    sWarnMsg = "You have made incomplete changes to properties. " & _
           "Click 'OK' to discard the changes and exit."
. . .
onvalid="SetValid(sWarnMsg)"
  • From within the handler of the OnValid event of the master EditSheet for the page.

This routine is only available after the taskbar has been inserted by calling either InsertTaskBar or InsertEditTaskBar.

This routine is available in the include file ActionPageUtil.asp.

See Also

Client-Side Routines

SetDirty (client-side)

SetRequired (client-side)

Server-Side Routines


SetWaitDisplayText (client-side)

Use this routine to set new text in the wait display.

Definition

SetWaitDisplayText(sWaitText)

Parameters

sWaitText

A string that contains the new text to be displayed.

Return Value

None.

Remarks

This routine is only available after the taskbar has been inserted by calling either InsertTaskBar or InsertEditTaskBar.

This routine is available in the include file ActionPageUtil.asp.

See Also

Client-Side Routines

HideWaitDisplay (client-side)

ShowWaitDisplay (client-side)

SetStatusText (client-side)

Server-Side Routines


sFormatString (client-side)

Use this routine to insert arguments into a string in a manner similar to that used by the C++ printf function. It is useful for formatting strings in a way that is much easier to localize than some other hard-coded methods.

Definition

sFormatString(sFormat,

              aArgs)

Parameters

sFormat

A string containing a combination of text and sequentially-numbered variables in the format %1, %2, and so forth. These variables are replaced with the elements from the corresponding positions in the aArgs array.

aArgs

An array of strings to be inserted into the string specified by the sFormat parameter, in the positions of the sequentially-numbered variables. Any extra arguments are ignored, and any extra variables in the string remain unchanged.

Return Value

A string containing the contents of the sFormat parameter with the appropriate substitutions performed.

Remarks

The following example shows how the string "A and B" is returned and assigned to the variable sFormattedString:

sFormattedString = sFormatString("%1 and %2", Array("A", "B"))

The returned string can easily be changed to "B and A" by changing the format string to "%2 and %1" (without changing the array).

This routine is only available after the taskbar has been inserted by calling either InsertTaskBar or InsertEditTaskBar.

This routine is available in the include file ActionPageUtil.asp.

There is a functionally equivalent version of this routine defined for server-side use in the file ASPUtil.asp.

See Also

Client-Side Routines

sGetFormattedDate (client-side)

Server-Side Routines

sFormatString (server-side)


sGetFormattedDate (client-side)

Use this routine to create a date string out of integer values representing the day, month, and year. The string returned is in the default locale format.

Definition

sGetFormattedDate(nYear,

                  nMonth,

                  nDay)

Parameters

nYear

A number representing the year portion of the date being constructed.

nMonth

A number representing the month portion of the date being constructed.

nDay

A number representing the day portion of the date being constructed.

Return Value

A string containing the constructed date, or an empty string if a valid date string could not be constructed.

Remarks

This routine is available in the include file ActionPageUtil.asp.

See Also

Client-Side Routines

bIsDate (client-side)

dtGetDate (client-side)

nGetDay (client-side)

nGetMonth (client-side)

nGetYear (client-side)

Server-Side Routines


sGetScriptError (client-side)

Use this routine to format particular properties of the global Microsoft Visual Basic Scripting Edition (VBScript) Err object into an HTML table. The table includes the following property values from the object, in the order shown: ASPCode, number, description, source, fileName, and lineNumber. The table is returned as an HTML-formatted string. This routine is typically called to construct a string to use as the sErrorDetail parameter of the routine ShowErrorDlg.

Definition

sGetScriptError(oErr)

Parameters

oErr

The VBScript Err object to be formatted.

Return Value

A string containing the HTML that displays the formatted table.

Remarks

The following is an example of the table to be displayed.

Script Error
Number | 0x345
Description | xxx
Source | xxx
Help file | xxx
Help context | xxx

This routine is available in the include file ActionPageUtil.asp.

There is a functionally equivalent version of this routine defined for server-side use in the file ASPUtil.asp.

See Also

Client-Side Routines

sGetXMLError (client-side)

ShowErrorDlg (client-side)

Server-Side Routines

sGetADOError (server-side)

sGetASPError (server-side)

sGetErrorById (server-side)

sGetScriptError (server-side)

sGetXMLError (server-side)


sGetXMLError (client-side)

Use this routine to format particular properties of the XMLDOMParseError object into an HTML table. The table includes the following property values from the object, in the order shown: errorCode, filePos, line, linePos, reason, srcText, and URL. The table is returned as an HTML-formatted string. This routine is typically called to construct a string to use as the sErrorDetail parameter of the routine ShowErrorDlg.

Definition

sGetXMLError(oXMLDocParseError)

Parameters

oXMLDocParseError

The XMLDOMParseError object to be formatted.

Return Value

A string containing the HTML that displays the formatted table.

Remarks

The XMLDOMParseError object is retrieved by calling the parseError method of an XML document.

The following is an example of the table to be displayed.

XML Error
Error code | 123
File pos | 456
Line | 789
Line pos | 123
Source text | xxx
URL | xxx

This routine is available in the include file ActionPageUtil.asp.

There is a functionally equivalent version of this routine defined for server-side use in the file ASPUtil.asp.

See Also

Client-Side Routines

sGetScriptError (client-side)

ShowErrorDlg (client-side)

Server-Side Routines

sGetADOError (server-side)

sGetASPError (server-side)

sGetErrorById (server-side)

sGetScriptError (server-side)

sGetXMLError (server-side)


ShowErrorDlg (client-side)

Use this routine to display an error dialog box. The passed strings and error type specify the details of the error.

Definition

ShowErrorDlg(sErrorTitle,

             sFriendlyError,

             sErrorDetails,

             nErrorType)

Parameters

sErrorTitle

A string to be displayed in the title bar of the error dialog box.

sFriendlyError

A string containing a plain-language description of the error that has been encountered.

sErrorDetails

A string containing details about the error that has been encountered, often formatted as an HTML table using one of the error formatting routines: sGetScriptError or sGetXMLError. This string can also be formatted using other methods.

nErrorType

A number that corresponds to the severity of the error, and which determines the type of icon displayed in the error dialog box. See Remarks for more information about constants provided for use as this parameter.

Return Value

None.

Remarks

The following constants are provided as the valid values for the nErrorType parameter:

ERROR_ICON_ALERT, ERROR_ICON_CRITICAL,

ERROR_ICON_INFORMATION, ERROR_ICON_QUESTION

This routine is available in the include file ActionPageUtil.asp.

See Also

Client-Side Routines

sGetScriptError (client-side)

sGetXMLError (client-side)

Server-Side Routines

SetError (server-side)


ShowFindBy (client-side)

Use this routine to show the find pane.

Definition

ShowFindBy

Parameters

None.

Return Value

None.

Remarks

This routine is only available after the taskbar has been inserted by calling either InsertTaskBar or InsertEditTaskBar.

This routine is available in the include file ActionPageUtil.asp.

See Also

Client-Side Routines

HideFindBy (client-side)

SetFindByHeight (client-side)

ToggleFindBy (client-side)

Server-Side Routines


ShowWaitDisplay (client-side)

Use this routine to show the wait display.

Definition

ShowWaitDisplay

Parameters

None.

Return Value

None.

Remarks

This routine is only available after the taskbar has been inserted by calling either InsertTaskBar or InsertEditTaskBar.

This routine is available in the include file ActionPageUtil.asp.

See Also

Client-Side Routines

HideWaitDisplay (client-side)

SetWaitDisplayText (client-side)

Server-Side Routines


ShowXMLNodeErrors (client-side)

Use this routine to display information from XML error nodes in error dialog boxes.

Definition

ShowXMLNodeErrors(xmlErrorNodes)

Parameters

xmlErrorNodes

A collection of error nodes from an XML document.

Return Value

None.

Remarks

This routine displays one error dialog box per error node.

This routine expects XML in the format output by the server routine AddErrorNode. Usually that routine is used to add error nodes to return XML in response to a ListSheet XMLHTTP operation or a form post from the routine xmlPostFormViaXML.

This routine is available in the include file HTTPXMLUtil.htm.

See Also

Client-Side Routines

xmlPostFormViaXML (client-side)

Server-Side Routines

AddErrorNode (server-side)


sMergeGroups2 (client-side)

Use this routine to merge two sets of XML records containing different information about the same entities, returning the result as a string containing XML tagging.

One set of records, known as the master set, contains higher-level information about each entity represented in the set. The other set of records, known as the detail set, contains more detailed information about the same set of entities. Both sets of records are contained in XML documents.

The records from each set are matched up and merged into a resulting set of records containing two tiers. The first tier contains the higher-level information, and the second tier contains the detailed information.

Definition

sMergeGroups2(xmlMaster,

              xmlDetail,

              sKeyId)

Parameters

xmlMaster

An XML DOMDocument object containing a set of record elements and associated data elements in the standard XML data record structure. These record elements contain the data that appears in the first tier of the resulting standard XML data record structure, and are presumably considered to contain higher-level information.

xmlDetail

An XML DOMDocument object containing a set of record elements and associated data elements in the standard XML data record format. These record elements contain the data that appears in the second tier of the resulting standard XML data record structure, and are presumably considered to contain more detailed information.

sKeyId

A string that corresponds to the name of a field element that exists in both of the XML documents passed as the other parameters. The values for this element are used to match up records from one XML document with the records in the other.

Return Value

A string that contains the merged, two-tiered set of records, represented in the standard XML data record format.

Remarks

This routine is useful for preparing a two-tiered XML data record structure for use by a two-level ListSheet HTC. For more information about how the ListSheet HTC expects its data in one-, two-, and three-tiered data record structures, see ListSheet and Standard XML Data Record Format.

For more information about how single-tiered XML data record structures are merged to created two- and three-tiered XML data record structures, see XML Data Merging.

This routine is available in the include file ActionPageUtil.asp.

There is a functionally equivalent version of this routine defined for server-side use in the file ASPUtil.asp.

See Also

Client-Side Routines

sMergeGroups3 (client-side)

xmlMergeGroups2 (client-side)

xmlMergeGroups3 (client-side)

xmlMergeGroupsByID2 (client-side)

xmlMergeGroupsByID3 (client-side)

Server-Side Routines

sMergeGroups2 (server-side)


sMergeGroups3 (client-side)

Use this routine to merge three sets of XML records containing different information about the same entities, returning the result as a string containing XML tagging.

One set of records, known as the master set, contains higher-level information about each entity represented in the set. A second set of records, known as the group set, contains more detailed information about the same set of entities. A third set of records, known as the detail set, contains the most detailed information about the same set of entities. All three sets of records are contained in XML documents.

The records from each set are matched up and merged into a resulting set of records containing three tiers. The first tier contains the higher-level information, the second tier contains the group level of detail, and the third tier contains the most detailed information.

Definition

sMergeGroups3(xmlMaster,

              xmlGroup,

              xmlDetail,

              sMasterKeyId,

              sDetailKeyId)

Parameters

xmlMaster

An XML DOMDocument object containing a set of record elements and associated data elements in the standard XML data record structure. These record elements contain the data that appears in the first tier of the resulting standard XML data record structure, and are presumably considered to contain higher-level information.

xmlGroup

An XML DOMDocument object containing a set of record elements and associated data elements in the standard XML data record format. These record elements contain the data that appears in the second tier of the resulting standard XML data record structure, and are presumably considered to contain information of a medium level of detail.

xmlDetail

An XML DOMDocument object containing a set of record elements and associated data elements in the standard XML data record format. These record elements contain the data that appears in the third tier of the resulting standard XML data record structure, and are presumably considered to contain the most detailed information.

sMasterKeyId

A string that corresponds to the name of a data element that exists in both the xmlMaster and xmlGroup XML documents. The values for this element are used to match up records in one XML document with records in the other.

sDetailKeyId

A string that corresponds to the name of a data element that exists in both the xmlGroup and xmlDetail XML documents. The values for this element are used to match up records in one XML document with records in the other.

Return Value

A string that contains the merged, three-tiered set of records, represented in the standard XML data record format.

Remarks

This routine is useful for preparing a three-tiered XML data record structure for use by a three-level ListSheet HTC. For more information about how the ListSheet HTC expects its data in one-, two-, and three-tiered data record structures, see ListSheet and Standard XML Data Record Format.

For more information about how single-tiered XML data record structures are merged to created two- and three-tiered XML data record structures, see XML Data Merging.

This routine is available in the include file ActionPageUtil.asp.

There is a functionally equivalent version of this routine defined for server-side use in the file ASPUtil.asp.

See Also

Client-Side Routines

sMergeGroups2 (client-side)

xmlMergeGroups2 (client-side)

xmlMergeGroups3 (client-side)

xmlMergeGroupsByID2 (client-side)

xmlMergeGroupsByID3 (client-side)

Server-Side Routines

sMergeGroups3 (server-side)


ToggleFindBy (client-side)

Use this routine to display or hide the find pane to the opposite of its current display state. In other words, if it is currently hidden, display it, and if it is currently displayed, hide it.

Definition

ToggleFindBy

Parameters

None.

Return Value

None.

Remarks

This routine toggles the display state of the find pane by calling either the ShowFindBy routine or the HideFindBy routine, depending on the current state.

This routine is only available after the taskbar has been inserted by calling either InsertTaskBar or InsertEditTaskBar.

This routine is available in the include file ActionPageUtil.asp.

See Also

Client-Side Routines

HideFindBy (client-side)

ShowFindBy (client-side)

SetFindByHeight (client-side)

Server-Side Routines


ToggleTask (client-side)

Use this routine to toggle the enabled/disabled state of a task, changing it from enabled to disabled, or from disabled to enabled. The button for the task reflects the changed state, dimming when disabled.

Definition

ToggleTask(sID)

Parameters

sID

A string identifier that matches the id attribute of the corresponding task element in the relevant module configuration file.

Return Value

None.

Remarks

This routine toggles the enabled/disabled state of the task by calling either the EnableTask routine or the DisableTask routine, depending on the current state.

This routine is only available after the taskbar has been inserted by calling either InsertTaskBar or InsertEditTaskBar.

This routine is available in the include file ActionPageUtil.asp.

See Also

Client-Side Routines

DisableTask (client-side)

EnableAllTasks (client-side)

EnableTask (client-side)

Server-Side Routines


xmlGetSiteTermsValue (client-side)

Use this routine to display the Site Terms Picker dialog box using a specific site terms property. A default selection can be supplied.

Definition

xmlGetSiteTermsValue(xmlSiteTermNode,

                     sSelected)

Parameters

xmlSiteTermNode

A site terms PROPERTY element (an XML XMLDOMElement object), with its choices as subordinate ATTRIBUTE elements (also XML XMLDOMElement objects).

sSelected

A string that is matched against the displayvalue attribute of each child ATTRIBUTE element. If a match is found, that attribute initially displays as selected.

Return Value

The site terms ATTRIBUTE element (an XML XMLDOMElement object) selected by the user.

Remarks

To prevent an initial selection in the Site Terms Picker dialog box, pass a string for the sSelected parameter that does not match the displayname attribute of any of the ATTRIBUTE elements within the specified PROPERTY element.

This routine is available in the include file ActionPageUtil.asp.

See Also

Client-Side Routines

Server-Side Routines


xmlGetXMLDOMDoc (client-side)

Use this routine to create an XML DOMDocument object with an empty documentElement property.

Definition

xmlGetXMLDOMDoc

Parameters

None.

Return Value

An XML DOMDocument object with an empty documentElement property.

Remarks

The string version of the returned document has the following form:

<document />

This routine is available in the include file HTTPXMLUtil.htm.

There is a functionally equivalent version of this routine defined for server-side use in the file HTTPXMLUtil.asp.

See Also

Client-Side Routines

AddCDATANode (client-side)

AddItemNode (client-side)

Server-Side Routines

xmlGetXMLDOMDoc (server-side)


xmlMergeGroups2 (client-side)

Use this routine to merge two sets of XML records containing different information about the same entities, returning the result as an XML document.

One set of records, known as the master set, contains higher-level information about each entity represented in the set. The other set of records, known as the detail set, contains more detailed information about the same set of entities. Both of these sets of records are contained in XML documents.

The records from each set are matched up and merged into a resulting set of records containing two tiers. The first tier contains the higher-level information, and the second tier contains the detailed information.

Definition

xmlMergeGroups2(xmlMaster,

                xmlDetail,

                sKeyId)

Parameters

xmlMaster

An XML DOMDocument object containing a set of record elements and associated data elements in the standard XML data record structure. These record elements contain the data that appears in the first tier of the resulting standard XML data record structure, and are considered to contain higher-level information.

xmlDetail

An XML DOMDocument object containing a set of record elements and associated data elements in the standard XML data record format. These record elements contain the data that appears in the second tier of the resulting standard XML data record structure, and are considered to contain more detailed information.

sKeyId

A string that corresponds to the name of a field element that exists in both of the XML documents passed as the other parameters. The values for this element are used to match up records from one XML document with the records in the other.

Return Value

An XML document that contains the merged, two-tiered set of records, represented in the standard XML data record format.

Remarks

This routine is useful for preparing a two-tiered XML data record structure for use by a two-level ListSheet HTC. For more information about how the ListSheet HTC expects its data in one-, two-, and three-tiered data record structures, see ListSheet and Standard XML Data Record Format.

For more information about how single-tiered XML data record structures are merged to create two- and three-tiered XML data record structures, see XML Data Merging.

This routine is available in the include file ActionPageUtil.asp.

There is a functionally equivalent version of this routine defined for server-side use in the file ASPUtil.asp.

See Also

Client-Side Routines

sMergeGroups2 (client-side)

sMergeGroups3 (client-side)

xmlMergeGroups3 (client-side)

xmlMergeGroupsByID2 (client-side)

xmlMergeGroupsByID3 (client-side)

Server-Side Routines

xmlMergeGroups2 (server-side)


xmlMergeGroups3 (client-side)

Use this routine to merge three sets of XML records containing different information about the same entities, returning the result as an XML document.

One set of records, known as the master set, contains higher-level information about each entity represented in the set. A second set of records, known as the group set, contains more detailed information about the same set of entities. A third set of records, known as the detail set, contains the most detailed information about the same set of entities. All three sets of records are contained in XML documents.

The records from each set are matched up and merged into a resulting set of records containing three tiers. The first tier contains the higher-level information, the second tier contains the group level of detail, and the third tier contains the most detailed information.

Definition

xmlMergeGroups3(xmlMaster,

                xmlGroup,

                xmlDetail,

                sMasterKeyId,

                sDetailKeyId)

Parameters

xmlMaster

An XML DOMDocument object containing a set of record elements and associated data elements in the standard XML data record structure. These record elements contain the data that appears in the first tier of the resulting standard XML data record structure, and are considered to contain higher-level information.

xmlGroup

An XML DOMDocument object containing a set of record elements and associated data elements in the standard XML data record format. These record elements contain the data that appears in the second tier of the resulting standard XML data record structure, and are considered to contain information of a medium level of detail.

xmlDetail

An XML DOMDocument object containing a set of record elements and associated data elements in the standard XML data record format. These record elements contain the data that appears in the third tier of the resulting standard XML data record structure, and are considered to contain the most detailed information.

sMasterKeyId

A string that corresponds to the name of a data element that exists in both the xmlMaster and xmlGroup XML documents. The values for this element are used to match up records in one XML document with records in the other.

sDetailKeyId

A string that corresponds to the name of a data element that exists in both the xmlGroup and xmlDetail XML documents. The values for this element are used to match up records in one XML document with records in the other.

Return Value

An XML DOMDocument object that contains the merged, three-tiered set of records, represented in the standard XML data record format.

Remarks

This routine is useful for preparing a three-tiered XML data record structure for use by a three-level ListSheet HTC. For more information about how the ListSheet HTC expects its data in one-, two-, and three-tiered data record structures, see ListSheet and Standard XML Data Record Format.

For more information about how single-tiered XML data record structures are merged to create two- and three-tiered XML data record structures, see XML Data Merging.

This routine is available in the include file ActionPageUtil.asp.

There is a functionally equivalent version of this routine defined for server-side use in the file ASPUtil.asp.

See Also

Client-Side Routines

sMergeGroups2 (client-side)

sMergeGroups3 (client-side)

xmlMergeGroups2 (client-side)

xmlMergeGroupsByID2 (client-side)

xmlMergeGroupsByID3 (client-side)

Server-Side Routines

xmlMergeGroups3 (server-side)


xmlMergeGroupsByID2 (client-side)

Use this routine to merge two sets of XML records containing different information about the same entities, returning the result as an XML document.

One set of records, known as the master set, contains higher-level information about each entity represented in the set. The other set of records, known as the detail set, contains more detailed information about the same set of entities. Both of these sets of records are contained in XML data-islands in the current document.

The records from each set are matched up and merged into a resulting set of records containing two tiers. The first tier contains the higher-level information, and the second tier contains the detailed information.

Definition

xmlMergeGroupsByID2(sMaster,

                    sDetail,

                    sKeyId)

Parameters

sMaster

A string that matches the id attribute of an XML data-island containing a set of record elements and associated data elements in the standard XML data record structure. These record elements contain the data that appears in the first tier of the resulting standard XML data record structure, and are considered to contain higher-level information.

sDetail

A string that matches the id attribute of an XML data-island containing a set of record elements and associated data elements in the standard XML data record format. These record elements contain the data that appears in the second tier of the resulting standard XML data record structure, and are considered to contain more detailed information.

sKeyId

A string that corresponds to the name of a field element that exists in both of the XML data-islands whose id attributes are passed as the other parameters. The values for this element are used to match up records from one XML data-island with the records in the other.

Return Value

An XML DOMDocument object that contains the merged, two-tiered set of records, represented in the standard XML data record format.

Remarks

This routine is useful for preparing a two-tiered XML data record structure for use by a two-level ListSheet HTC. For more information about how the ListSheet HTC expects its data in one-, two-, and three-tiered data record structures, see ListSheet and Standard XML Data Record Format.

For more information about how single-tiered XML data record structures are merged to create two- and three-tiered XML data record structures, see XML Data Merging.

This routine is available in the include file ActionPageUtil.asp.

See Also

Client-Side Routines

sMergeGroups2 (client-side)

sMergeGroups3 (client-side)

xmlMergeGroups2 (client-side)

xmlMergeGroups3 (client-side)

xmlMergeGroupsByID3 (client-side)

Server-Side Routines


xmlMergeGroupsByID3 (client-side)

Use this routine to merge three sets of XML records containing different information about the same entities, returning the result as an XML document.

One set of records, known as the master set, contains higher-level information about each entity represented in the set. A second set of records, known as the group set, contains more detailed information about the same set of entities. A third set of records, known as the detail set, contains the most detailed information about the same set of entities. All three sets of records are contained in XML data-islands in the current document.

The records from each set are matched up and merged into a resulting set of records containing three tiers. The first tier contains the higher-level information, the second tier contains the group level of detail, and the third tier contains the most detailed information.

Definition

xmlMergeGroupsByID3(sMaster,

                    sGroup,

                    sDetail,

                    sMasterKeyId,

                    sDetailKeyId)

Parameters

sMaster

A string that matches the id attribute of an XML data-island containing a set of record elements and associated data elements in the standard XML data record structure. These record elements contain the data that appears in the first tier of the resulting standard XML data record structure, and are considered to contain higher-level information.

sGroup

A string that matches the id attribute of an XML data-island containing a set of record elements and associated data elements in the standard XML data record format. These record elements contain the data that appears in the second tier of the resulting standard XML data record structure, and are considered to contain information of a medium level of detail.

sDetail

A string that matches the id attribute of an XML data-island containing a set of record elements and associated data elements in the standard XML data record format. These record elements contain the data that appears in the third tier of the resulting standard XML data record structure, and are considered to contain the most detailed information.

sMasterKeyId

A string that corresponds to the name of a field element that exists in both the xmlMaster and xmlGroup XML documents. The values for this element are used to match up records in one XML document with records in the other.

sDetailKeyId

A string that corresponds to the name of a field element that exists in both the xmlGroup and xmlDetail XML documents. The values for this element are used to match up records in one XML document with records in the other.

Return Value

An XML DOMDocument object that contains the merged, three-tiered set of records, represented in the standard XML data record format.

Remarks

This routine is useful for preparing a three-tiered XML data record structure for use by a three-level ListSheet HTC. For more information about how the ListSheet HTC expects its data in one-, two-, and three-tiered data record structures, see ListSheet and Standard XML Data Record Format.

For more information about how single-tiered XML data record structures are merged to create two- and three-tiered XML data record structures, see XML Data Merging.

This routine is available in the include file ActionPageUtil.asp.

See Also

Client-Side Routines

sMergeGroups2 (client-side)

sMergeGroups3 (client-side)

xmlMergeGroups2 (client-side)

xmlMergeGroups3 (client-side)

xmlMergeGroupsByID2 (client-side)

Server-Side Routines


xmlPostFormViaXML (client-side)

Use this routine to post elements within the specified form element to the server as an XML document.

Definition

xmlPostFormViaXML(byRef elForm)

Parameters

elForm

A form element on the page.

Return Value

An XML DOMDocument object returned from the page specified by the ACTION attribute of the form element.

Remarks

Converts form elements to XML where each element name becomes a name attribute and each element value becomes a value attribute on child item elements of the document. These items are posted to the action page as XML and then the routine returns any response XML.

This routine is useful when posting arguments to an HTTPXML response page.

This routine is available in the include file HTTPXMLUtil.htm.

See Also

Client-Side Routines

Server-Side Routines

dGetRequestXMLAsDict (server-side)


xmlXMLFromDict (client-side)

Use this routine to convert a Dictionary object into an XML document.

Definition

xmlXMLFromDict(byRef dDict)

Parameters

dDict

A Dictionary object to be converted to XML.

Return Value

An XML DOMDocument object containing an item element for each entry in the Dictionary object.

Remarks

Each item element is given two attributes, name and value, initialized to the name and value of each entry in the Dictionary object, as follows:

<item name="keyname" value="value"/>

This routine is available in the include file HTTPXMLUtil.htm.

There is a functionally equivalent version of this routine defined for server-side use in the file HTTPXMLUtil.asp.

See Also

Client-Side Routines

xmlXMLFromForm (client-side)

Server-Side Routines

dDictFromXML (server-side)

xmlXMLFromDict (server-side)


xmlXMLFromForm (client-side)

Use this routine to convert form elements to items in an XML document.

Definition

xmlXMLFromForm(byRef elForm)

Parameters

elForm

A form element on the page.

Return Value

An XML DOMDocument object containing the copied contents of the form elements.

Remarks

This routine converts the child elements of a form element to XML where each element name becomes a name attribute and each element value becomes a value attribute on child item elements of the document.

This routine is available in the include file HTTPXMLUtil.htm.

See Also

Client-Side Routines

xmlPostFormViaXML (client-side)

xmlXMLFromDict (client-side)

Server-Side Routines

xmlXMLFromDict (server-side)


Server-Side Routines

The Commerce Server Business Desk Framework defines the following server-side routines:

Routine Name | Description
AddCDATANode | Adds a CDATA type item node to the specified XML document. Defined in the file HTTPXMLUtil.asp.
AddErrorNode | Adds an error node to the specified XML document, causing the ListSheet HTC to display an error dialog box. Defined in the file HTTPXMLUtil.asp.
AddItemNode | Adds an item node to the specified XML document. Defined in the file HTTPXMLUtil.asp.
AddWarningNode | Adds a warning node to the specified XML document, causing the ListSheet HTC to display a warning dialog box. Defined in the file HTTPXMLUtil.asp.
BDHALsizeButtons | Ensures that all button elements in the specified collection with the specified class name have the same width. Defined in the file BDHALUtil.htm.
BDHALsizeSelects | Ensures that all EditField elements of type 'select' in the specified collection with the specified class name have the same width. Defined in the file BDHALUtil.htm.
dDictFromXML | Converts a standard XML document into a Dictionary object. Defined in the file HTTPXMLUtil.asp.
dGetAction | Creates a Dictionary object and initializes it with the configuration information for a particular action page. Defined in the file ActionPageUtil.asp.
dGetRequestXMLAsDict | Returns the XML posted with a request as a Dictionary object. Defined in the file HTTPXMLUtil.asp.
GetSiteConfigField | Retrieves a value from the Site Configuration store. Defined in the file ASPUtil.asp.
InsertEditTaskBar | Causes Business Desk to display the action page in edit mode, with the navigation frame hidden, including the display of the task buttons and initial status message. Defined in the file ActionPageUtil.asp.
InsertTaskBar | Causes Business Desk to display the action page in list mode, with the navigation frame visible, including the display of the task buttons and initial status message. Defined in the file ActionPageUtil.asp.
oGetADOCommand | Creates and initializes an ADO Command object. Defined in the file DBUtil.asp.
oGetADOConnection | Creates and opens an ADO Connection object. Defined in the file DBUtil.asp.
rsGetRecordset | Retrieves an ADO Recordset object based on the specified connection string, query, cursor, and lock type. Defined in the file DBUtil.asp.
SetError | Saves server-side error information for synchronized display in the client. Defined in the file ASPUtil.asp.
sFormatString | Performs string formatting using a format string with variable insertion points, similar to the C++ printf function. Defined in the file ASPUtil.asp.
sGetADOError | Formats an ADO error into a string containing HTML table formatting directives. Defined in the file ASPUtil.asp.
sGetASPError | Formats an ASP error into a string containing HTML table formatting directives. Defined in the file ASPUtil.asp.
sGetErrorById | Retrieves an error message from the Message Manager. Defined in the file ASPUtil.asp.
sGetScriptError | Formats a script error into a string containing HTML table formatting directives. Defined in the file ASPUtil.asp.
sGetXMLError | Formats an XML error into a string containing HTML table formatting directives. Defined in the file ASPUtil.asp.
sMergeGroups2 | Merges two single-tiered XML documents in the standard XML data record format into a single two-tiered XML document in the same format, returning the result as a string. Defined in the file ASPUtil.asp.
sMergeGroups3 | Merges three single-tiered XML documents in the standard XML data record format into a single three-tiered XML document in the same format, returning the result as a string. Defined in the file ASPUtil.asp.
sRelURL2AbsURL | Converts a URL that is relative to the folder of an action page into its equivalent absolute URL. Defined in the file ASPUtil.asp.
xmlGetRequestXML | Returns the XML posted with a request as an XML DOMDocument object. Defined in the file HTTPXMLUtil.asp.
xmlGetXMLDOMDoc | Returns an empty XML DOMDocument object. Defined in the file HTTPXMLUtil.asp.
xmlGetXMLFromQuery | Creates an XML document node and populates it with record nodes corresponding to all of the records returned by the specified query. Defined in the file DBUtil.asp.
xmlGetXMLFromQueryEx | Creates an XML document node and populates it with record nodes corresponding to some or all of the records returned by the specified query. Defined in the file DBUtil.asp.
xmlGetXMLFromRS | Creates an XML document node and populates it with record nodes corresponding to all of the records in the specified ADO Recordset object. Defined in the file DBUtil.asp.
xmlGetXMLFromRSEx | Creates an XML document node and populates it with record nodes corresponding to some or all of the records in the specified ADO Recordset object. Defined in the file DBUtil.asp.
xmlMergeGroups2 | Merges two single-tiered XML documents in the standard XML data record format into a single two-tiered XML document in the same format, returning the result as an XML document node. Defined in the file ASPUtil.asp.
xmlMergeGroups3 | Merges three single-tiered XML documents in the standard XML data record format into a single three-tiered XML document in the same format, returning the result as an XML document node. Defined in the file ASPUtil.asp.
xmlXMLFromDict | Converts a Dictionary object into a standard XML document. Defined in the file HTTPXMLUtil.asp.

The following lists show server-side routines that are not intended to be called by module code, organized alphabetically and by the include file in which they appear:

ActionPageUtil.asp

InsertHelpIconBtn, InsertIconBtn, InsertIconBtns, InsertNonClientArea

ASPUtil.asp

dGetErrorDict, sESCErrorText, sStripHTML

BizDeskObjects.asp

BDError, dGetCategory, DumpDict, DumpList, DumpResults, DumpSubObject, LoadActions, LoadCategories, LoadModuleConfigs, LoadModules, LoadObjects, LoadTasks, PutObjectsInApp, SetDumpStyles, sGetChildText, ShowProgress, ValidateActions, VBError, XMLError, xmlLoadConfig

DBUtil.asp

AddEmptyRecordNode, AddField, AddFormattedNode, sESCText, sStripGroupName

response_session.asp

xmlGetResponseFromRequest, xmlGetResponseXML


AddCDATANode (server-side)

Use this routine to add a CDATA type item node to a global XML document, setting the name attribute and element data to the values passed.

Definition

AddCDATANode(byVal sName,

             byVal sValue)

Parameters

sName

A string containing the name of the item.

sValue

A string containing the value of the item.

Return Value

None.

Remarks

The new item will be added to the XML document retrieved from the documentElement property of the DOMDocument object referenced by the global variable g_xmlReturn.

The string version of the added element has the following form:

<item name="sName"><![CDATA[sValue]]></item>

This routine is available in the include file HTTPXMLUtil.asp.

There is a functionally equivalent version of this routine defined for client-side use in the file HTTPXMLUtil.htm. Note that this other routine does not add the CDATA node to a globally accessible XML document, but instead is passed an xmlDoc parameter that references the XML document to which the node will be added.

See Also

Server-Side Routines

AddErrorNode (server-side)

AddItemNode (server-side)

AddWarningNode (server-side)

xmlGetXMLDOMDoc (server-side)

Client-Side Routines

AddCDATANode (client-side)


AddErrorNode (server-side)

Use this routine to add an ERROR element to the specified XML document.

Definition

AddErrorNode(byRef xmlDOMDoc,

             byVal sId,

             byVal sSource,

             byVal sDetail)

Parameters

xmlDOMDoc

A reference to the XML DOMDocument object to which the ERROR element is added.

sId

A string containing a value for the id attribute of the element.

sSource

A string containing a value for the source attribute of the element.

sDetail

An HTML string containing the error details, assigned as the innerHTML of the element.

Return Value

None.

Remarks

This routine adds a node of the form:

<ERROR id="id" source="source">detail</ERROR>

This is the format expected by client routine ShowXMLNodeErrors.

This routine is available in the include file HTTPXMLUtil.asp.

See Also

Server-Side Routines

AddCDATANode (server-side)

AddItemNode (server-side)

AddWarningNode (server-side)

xmlGetXMLDOMDoc (server-side)

Client-Side Routines

ShowXMLNodeErrors (client-side)


AddItemNode (server-side)

Use this routine to add an item element to a global XML document, establishing name and value attributes using the passed parameters.

Definition

AddItemNode(byVal sName,

            byVal sValue)

Parameters

sName

A string containing a value for the name attribute of the item.

sValue

A string containing a value for the value attribute of the item.

Return Value

None.

Remarks

The new item will be added to the XML document retrieved from the documentElement property of the DOMDocument object referenced by the global variable g_xmlReturn.

The string version of the added element has the following form:

<item name="sName" value="sValue"/>

This routine is available in the include file HTTPXMLUtil.asp.

There is a functionally equivalent version of this routine defined for client-side use in the file HTTPXMLUtil.htm. Note that this other routine does not add the CDATA node to a globally accessible XML document, but instead is passed an xmlDoc parameter that references the XML document to which the node will be added.

See Also

Server-Side Routines

AddCDATANode (server-side)

AddErrorNode (server-side)

AddWarningNode (server-side)

xmlGetXMLDOMDoc (server-side)

Client-Side Routines

AddItemNode (client-side)


AddWarningNode (server-side)

Use this routine to add a WARNING element to the specified XML document.

Definition

AddWarningNode(byRef xmlDoc,

               byVal sMessage)

Parameters

xmlDoc

A reference to the XML DOMDocument object to which the WARNING element is added.

A string containing the error details, assigned as the text of with the element.

sMessage

A string containing a warning message, assigned as the text of the element.

Return Value

None.

Remarks

This routine adds a node of the form:

<WARNING>sMessage</WARNING>

This routine is available in the include file HTTPXMLUtil.asp.

See Also

Server-Side Routines

AddCDATANode (server-side)

AddErrorNode (server-side)

AddItemNode (server-side)

xmlGetXMLDOMDoc (server-side)

Client-Side Routines


BDHALsizeButtons (server-side)

Use this routine to ensure that all buttons in the specified collection with the specified class name have the same width.

Definition

BDHALsizeButtons(elButtons,

                 sButtonClass,

                 bEnforceMinWidth)

Parameters

elButtons

A collection of HTML button elements.

sButtonClass

A string containing the name of the class of button elements for which the width will be adjusted.

bEnforceMinWidth

A Boolean value, where True means that a minimum width should be enforced, and False means that a minimum width should not be enforced.

Return Value

None.

Remarks

The standard minimum button width is 74 pixels.

This routine is available in the include file BDHALUtil.htm.

See Also

Server-Side Routines

BDHALsizeSelects (server-side)

Client-Side Routines


BDHALsizeSelects (server-side)

Use this routine to ensure that all EditFields of type 'select' in the specified collection with the specified class name have the same width.

Definition

BDHALsizeSelects(elSelects,

                 sSelectClass)

Parameters

elSelects

A collection of elements containing EditField HTCs of type 'select'.

sSelectClass

A string containing the name of the class of elements containing EditField HTCs of type 'select' for which the width will be adjusted.

Return Value

None.

Remarks

This routine is available in the include file BDHALUtil.htm.

See Also

Server-Side Routines

BDHALsizeButtons (server-side)

Client-Side Routines


dDictFromXML (server-side)

Use this routine to convert an XML document with child nodes of the form <item name="keyname" value="value"/> into a Dictionary object.

Definition

dDictFromXML(byRef xmlDOMDoc)

Parameters

xmlDOMDoc

The XML DOMDocument object to be converted.

Return Value

A Dictionary object containing the converted XML document contents.

Remarks

Each name and value attribute becomes an entry in the Dictionary object where the name is the key and the value attribute contains the value.

This routine is available in the include file HTTPXMLUtil.asp.

There is a functionally equivalent version of this routine defined for client-side use in the file HTTPXMLUtil.htm.

See Also

Server-Side Routines

xmlXMLFromDict (server-side)

Client-Side Routines

dDictFromXML (client-side)

xmlXMLFromDict (client-side)


dGetAction (server-side)

Use this routine to create a Dictionary object containing the configuration information for an action page.

Definition

dGetAction(byVal sLookupActionID)

Parameters

sLookupActionID

A string containing the action ID, which is the path and file name of the action page relative to the Commerce Server Business Desk root.

Return Value

A Dictionary object containing the action page configuration.

Remarks

This routine returns a Dictionary object containing all of the action page configuration information, such as name, tooltip, and associated tasks. The tasks associated with this action page are relatively complex, and are returned using a subordinate SimpleList object.

This routine is available in the include file ActionPageUtil.asp.

See Also

Server-Side Routines

Client-Side Routines


dGetRequestXMLAsDict (server-side)

Use this routine to retrieve the XML in a request as a Dictionary object.

Definition

dGetRequestXMLAsDict

Parameters

None.

Return Value

A Dictionary object containing the values expressed using XML in the request.

Remarks

This routine expects XML in the form that is posted by the client routine xmlPostFormViaXML. The Dictionary object returned can be treated like the Internet Information Services (IIS) Request object.

This routine is available in the include file HTTPXMLUtil.asp.

See Also

Server-Side Routines

dDictFromXML (server-side)

xmlGetRequestXML (server-side)

Client-Side Routines

xmlPostFormViaXML (client-side)


GetSiteConfigField (server-side)

Use this routine to retrieve a field value from the Site Configuration store.

Definition

GetSiteConfigField(sResourceName,

                   sPropertyName)

Parameters

sResourceName

A string containing the name of the resource associated with the field being requested.

sPropertyName

A string containing the name of the property corresponding to the field being requested.

Return Value

The value currently associated with the sPropertyName property of the sResourceName resource in the Site Configuration store.

Remarks

This routine is available in the include file ASPUtil.asp.

See Also

Server-Side Routines

Client-Side Routines


InsertEditTaskBar (server-side)

Use this routine to insert the configured taskbar and display the page in edit mode, that is, with the module navigation frame hidden and the action page frame expanded to the left.

Definition

InsertEditTaskBar(sPageTitle,

                  sStatusText)

Parameters

sPageTitle

A string containing the text to be displayed in the title bar at the top of the expanded action page frame.

sStatusText

A string containing the text to be initially displayed in the status bar at the bottom of the expanded action page frame.

Return Value

None.

Remarks

The title bar and status bar are displayed in the color red, indicating that Commerce Server Business Desk is in edit mode, from which modification of data values can occur.

It is common for an action page to overwrite the initial status text using the routine SetStatusText.

This routine should be invoked immediately after the opening BODY element in the action page.

This routine is available in the include file ActionPageUtil.asp.

See Also

Server-Side Routines

InsertTaskBar (server-side)

Client-Side Routines


InsertTaskBar (server-side)

Use this routine to insert the configured taskbar and display the page in list mode, that is, with the module navigation frame visible to the left of the action page frame.

Definition

InsertTaskBar(sPageTitle,

              sStatusText)

Parameters

sPageTitle

A string containing the text to be displayed in the title bar at the top of the action page frame.

sStatusText

A string containing the text to be initially displayed in the status bar at the bottom of the action page frame.

Return Value

None.

Remarks

The title bar and status bar are displayed in the color blue, indicating that Commerce Server Business Desk is in list mode, from which no modification of data values can occur.

It is common for an action page to overwrite the initial status text using the routine SetStatusText.

This routine should be invoked immediately after the opening BODY element in the action page.

This routine is available in the include file ActionPageUtil.asp.

See Also

Server-Side Routines

InsertEditTaskBar (server-side)

Client-Side Routines


oGetADOCommand (server-side)

Use this routine to create an ActiveX Data Object (ADO) Command object, and initialize it with the specified connection and command types.

Definition

oGetADOCommand(oConn,

               nCommandType)

Parameters

oConn

An ADO Connection object to be set as the active connection for the newly created Command object. This is usually the object returned from a call to the oGetADOConnection routine.

nCommandType

A number containing a valid value representing an ADO command type to be set for the newly created Command object.

Return Value

An ADO Command object, ready to use.

Remarks

The following constants for ADO parameter values are defined in the file DBUtil.asp:

Command Types

AD_CMD_TEXT

AD_CMD_TABLE

AD_CMD_STORED_PROC

AD_CMD_UNKNOWN

This routine is available in the include file DBUtil.asp.

See Also

Server-Side Routines

oGetADOConnection (server-side)

rsGetRecordset (server-side)

Client-Side Routines


oGetADOConnection (server-side)

Use this routine to create and open an ActiveX Data Object (ADO) connection, and establish connection and command timeouts of 15 and 30 seconds, respectively.

Definition

oGetADOConnection(sConnectionString)

Parameters

sConnectionString

A string containing an ADO connection string describing the database with which to connect. This is usually a property retrieved from a resource in the Site Configuration Store using the GetSiteConfigField routine in the file ASPUtil.asp.

Return Value

An ADO Connection object, ready to use.

Remarks

This routine is available in the include file DBUtil.asp.

See Also

Server-Side Routines

oGetADOCommand (server-side)

rsGetRecordset (server-side)

Client-Side Routines


rsGetRecordset (server-side)

Use this routine to retrieve an ActiveX Data Object (ADO) recordset based on a specified connection string, query, and cursor and lock types.

Definition

rsGetRecordset(sConnectionString,

               sQuery,

               nCursorType,

               nLockType)

Parameters

sConnectionString

A string containing an ADO connection string describing the database with which to connect. This is usually a property retrieved from a resource in the Site Configuration Store using the GetSiteConfigField routine in the file ASPUtil.asp.

sQuery

A string containing a valid SQL query.

nCursorType

A number containing a valid value representing an ADO cursor type.

nLockType

A number containing a valid value representing an ADO lock type.

Return Value

An ADO Recordset object containing the results of the query.

Remarks

The following constants for ADO parameter values are defined in the file DBUtil.asp:

Cursor Types

AD_OPEN_FORWARD_ONLY

AD_OPEN_KEYSET

AD_OPEN_DYNAMIC

AD_OPEN_STATIC

Lock Types

AD_LOCK_READ_ONLY

AD_LOCK_PESSIMISTIC

AD_LOCK_OPTIMISTIC

AD_LOCK_BATCH_OPTIMISTIC

This routine is available in the include file DBUtil.asp.

See Also

Server-Side Routines

xmlGetXMLFromRS (server-side)

xmlGetXMLFromRSEx (server-side)

Client-Side Routines


SetError (server-side)

Use this routine to save information about errors that occur in server-side code for display to the user. The error information is saved in the Active Server Pages (ASP) Session object, and used to automatically call the client-side routine ShowErrorDialog the next time the taskbar is displayed.

Definition

SetError(sErrorTitle,

         sFriendlyError,

         sErrorDetails,

         nErrorType)

Parameters

sErrorTitle

A string to be displayed in the title bar of the error dialog box.

sFriendlyError

A string containing a plain-language description of the error that has been encountered.

sErrorDetails

A string containing details about the error that has been encountered, often formatted as an HTML table using one of the error formatting routines: sGetASPError, sGetADOError, sGetScriptError, or sGetXMLError. This string can also be formatted using other methods.

nErrorType

A number that corresponds to the severity of the error, and which determines the type of icon displayed in the error dialog box. See Remarks for more information about constants provided for use as this parameter.

Return Value

None.

Remarks

The following constants are provided as the valid values for the nErrorType parameter:

ERROR_ICON_ALERT, ERROR_ICON_CRITICAL,

ERROR_ICON_INFORMATION, ERROR_ICON_QUESTION

If the error type is ERROR_ICON_ALERT or ERROR_ICON_CRITICAL, then the error is logged to the application event log.

This routine is available in the include file ASPUtil.asp.

See Also

Server-Side Routines

sGetADOError (server-side)

sGetASPError (server-side)

sGetErrorById (server-side)

sGetScriptError (server-side)

sGetXMLError (server-side)

Client-Side Routines

ShowXMLNodeErrors (client-side)


sFormatString (server-side)

Use this routine to insert arguments into a string in a manner similar to that used by the C++ printf function. It is useful for formatting strings in a way that is much easier to localize than some other hard-coded methods.

Definition

sFormatString(sFormat,

              aArgs)

Parameters

sFormat

A string containing a combination of text and sequentially-numbered variables in the format %1, %2, and so forth. These variables are replaced with the elements from the corresponding positions in the aArgs array.

aArgs

An array of strings to be inserted into the string specified by the sFormat parameter, in the positions of the sequentially-numbered variables. Any extra arguments are ignored, and any extra variables in the string remain unchanged.

Return Value

A string containing the contents of the sFormat parameter with the appropriate substitutions performed.

Remarks

The following example shows how the string "A and B" is returned and assigned to the variable sFormattedString:

sFormattedString = sFormatString("%1 and %2", Array("A", "B"))

The returned string can easily be changed to "B and A" by changing the format string to "%2 and %1" (without changing the array at all).

This routine is available in the include file ASPUtil.asp.

There is a functionally equivalent version of this routine defined for client-side use in the file ActionPageUtil.asp.

See Also

Server-Side Routines

Client-Side Routines

sFormatString (client-side)


sGetADOError (server-side)

Use this routine to format particular properties of an ADO Error object into an HTML table. The table includes the following property values from the object, in the order shown: number, description, source, SQLState, and NativeError. The table is returned as an HTML-formatted string. This routine is typically called to construct a string to use as the sErrorDetail parameter of the routine SetError.

Definition

sGetADOError(oConnectionErrorsError)

Parameters

oConnectionErrorsError

The ADO Error object to be formatted.

Return Value

A string containing the HTML that displays the formatted table.

Remarks

The following is an example of the table to be displayed.

ADO Error
Number | 0x456
Description | xxx
Source | xxx
SQL state | xxx
Native error | xxx

This routine is available in the include file ASPUtil.asp.

See Also

Server-Side Routines

SetError (server-side)

sGetASPError (server-side)

sGetScriptError (server-side)

sGetXMLError (server-side)

Client-Side Routines

sGetScriptError (client-side)


sGetASPError (server-side)

Use this routine to format particular properties of the object returned by a call to the Internet Information Services (IIS) routine GetLastError into an HTML table. The table includes the following property values from the object, in the order shown: number, description, source, helpFile, and helpContext. The table is returned as an HTML-formatted string. This routine is typically called to construct a string to use as the sErrorDetail parameter of the routine SetError.

Definition

sGetASPError(oServerGetLastError)

Parameters

oServerGetLastError

The object returned by the IIS routine GetLastError, which this routine uses to format the HTML table.

Return Value

A string containing the HTML that displays the formatted table.

Remarks

The following is an example of the table to be displayed.

ASP Error
Asp code | xxx
Number | 345
Description | xxx
Source | xxx
File name | xxx
Line number | 432

This routine is available in the include file ASPUtil.asp.

See Also

Server-Side Routines

SetError (server-side)

sGetADOError (server-side)

sGetScriptError (server-side)

sGetXMLError (server-side)

Client-Side Routines


sGetErrorById (server-side)

Use this routine to retrieve an error string from the global MessageManager object corresponding to a specific identifier. This routine is typically called to get a string to use as the sFriendlyError parameter of the routine SetError.

Definition

sGetErrorById(sErrorId)

Parameters

sErrorId

A string that uniquely identifies a particular error string in the global MessageManager object.

Return Value

A string containing the retrieved error text.

Remarks

This routine helps enable simplified localization of a Web site by providing access to a centralized message store that can be localized independently from the code.

This routine retrieves strings from the global MessageManager object referenced by the global variable g_MSCSMessageManager.

This routine is available in the include file ASPUtil.asp.

See Also

Server-Side Routines

SetError (server-side)

sFormatString (server-side)

Client-Side Routines


sGetScriptError (server-side)

Use this routine to format particular properties of a Microsoft Visual Basic Scripting Edition (VBScript) Err object into an HTML table. The table includes the following property values from the object, in the order shown: number, description, source, helpFile, and helpContext. The table is returned as an HTML-formatted string. This routine is typically called to construct a string to use as the sErrorDetail parameter of the routine SetError.

Definition

sGetScriptError(oErr)

Parameters

oErr

The VBScript Err object to be formatted.

Return Value

A string containing the HTML that displays the formatted table.

Remarks

The following is an example of the table to be displayed.

Script Error
Number | 0x345
Description | xxx
Source | xxx
Help file | xxx
Help context | xxx

This routine is available in the include file ASPUtil.asp.

There is a functionally equivalent version of this routine defined for client-side use in the file ActionPageUtil.asp.

See Also

Server-Side Routines

SetError (server-side)

sFormatString (server-side)

sGetADOError (server-side)

sGetASPError (server-side)

sGetXMLError (server-side)

Client-Side Routines

sGetScriptError (client-side)


sGetXMLError (server-side)

Use this routine to format particular properties of the XML parseError object into an HTML table. The table includes the following property values from the object, in the order shown: errorCode, filePos, line, linePos, reason, srcText, and URL. The table is returned as an HTML-formatted string. This routine is typically called to construct a string to use as the sErrorDetail parameter of the routine SetError.

Definition

sGetXMLError(oXMLDocParseError)

Parameters

oXMLDocParseError

The XML parseError object to be formatted.

Return Value

A string containing the HTML that displays the formatted table.

Remarks

The XML parseError object is retrieved by calling the parseError method of an XML document.

The following is an example of the table to be displayed.

XML Error
Error code | 123
File pos | 456
Line | 789
Line pos | 123
Source text | xxx
URL | xxx

This routine is available in the include file ASPUtil.asp.

There is a functionally equivalent version of this routine defined for client-side use in the file ActionPageUtil.asp.

See Also

Server-Side Routines

SetError (server-side)

sGetADOError (server-side)

sGetASPError (server-side)

sGetScriptError (server-side)

Client-Side Routines

sGetXMLError (client-side)


sMergeGroups2 (server-side)

Use this routine to merge two sets of XML records containing different information about the same entities, returning the result as an XML string.

One set of records, known as the master set, contains higher-level information about each entity represented in the set. The other set of records, known as the detail set, contains more detailed information about the same set of entities. Both sets of records are contained in XML documents.

The records from each set are matched up and merged into a resulting set of records containing two tiers. The first tier contains the higher-level information, and the second tier contains the detailed information.

Definition

sMergeGroups2(xmlMaster,

              xmlDetail,

              sKeyId)

Parameters

xmlMaster

An XML DOMDocument object containing a set of record elements and associated data elements in the standard XML data record structure. These record elements contain the data that appears in the first tier of the resulting standard XML data record structure, and are considered to contain higher-level information.

xmlDetail

An XML DOMDocument object containing a set of record elements and associated data elements in the standard XML data record format. These record elements contain the data that appears in the second tier of the resulting standard XML data record structure, and are considered to contain more detailed information.

sKeyId

A string that corresponds to the name of a data element that exists in both of the XML documents passed as the other parameters. The values for this element are used to match up records from one XML document with the records in the other.

Return Value

A string that contains the merged, two-tiered set of records, represented in the standard XML data record format.

Remarks

This routine is useful for preparing a two-tiered XML data record structure for use by a two-level ListSheet HTC. For more information about how the ListSheet HTC expects its data in one-, two-, and three-tiered data record structures, see ListSheet and Standard XML Data Record Format.

For more information about how single-tiered XML data record structures are merged to created two- and three-tiered XML data record structures, see XML Data Merging.

This routine is available in the include file ASPUtil.asp.

There is a functionally equivalent version of this routine defined for client-side use in the file ActionPageUtil.asp.

See Also

Server-Side Routines

sMergeGroups3 (server-side)

xmlMergeGroups2 (server-side)

xmlMergeGroups3 (server-side)

Client-Side Routines

sMergeGroups2 (client-side)


sMergeGroups3 (server-side)

Use this routine to merge three sets of XML records containing different information about the same entities, returning the result as an XML string.

One set of records, known as the master set, contains higher-level information about each entity represented in the set. A second set of records, known as the group set, contains more detailed information about the same set of entities. A third set of records, known as the detail set, contains the most detailed information about the same set of entities. All three sets of records are contained in XML documents.

The records from each set are matched up and merged into a resulting set of records containing three tiers. The first tier contains the higher-level information, the second tier contains the group level of detail, and the third tier contains the most detailed information.

Definition

sMergeGroups3(xmlMaster,

              xmlGroup,

              xmlDetail,

              sMasterKeyId,

              sDetailKeyId)

Parameters

xmlMaster

An XML DOMDocument object containing a set of record elements and associated data elements in the standard XML data record structure. These record elements contain the data that appears in the first tier of the resulting standard XML data record structure, and are considered to contain higher-level information.

xmlGroup

An XML DOMDocument object containing a set of record elements and associated data elements in the standard XML data record format. These record elements contain the data that appears in the second tier of the resulting standard XML data record structure, and are considered to contain information of a medium level of detail.

xmlDetail

An XML DOMDocument object containing a set of record elements and associated data elements in the standard XML data record format. These record elements contain the data that appears in the third tier of the resulting standard XML data record structure, and are considered to contain the most detailed information.

sMasterKeyId

A string that corresponds to the name of a data element that exists in both the xmlMaster and xmlGroup XML documents. The values for this element are used to match up records in one XML document with records in the other.

sDetailKeyId

A string that corresponds to the name of a data element that exists in both the xmlGroup and xmlDetail XML documents. The values for this element are used to match up records in one XML document with records in the other.

Return Value

A string that contains the merged, three-tiered set of records, represented in the standard XML data record format.

Remarks

This routine is useful for preparing a three-tiered XML data record structure for use by a three-level ListSheet HTC. For more information about how the ListSheet HTC expects its data in one-, two-, and three-tiered data record structures, see ListSheet and Standard XML Data Record Format.

For more information about how single-tiered XML data record structures are merged to created two- and three-tiered XML data record structures, see XML Data Merging.

This routine is available in the include file ASPUtil.asp.

There is a functionally equivalent version of this routine defined for client-side use in the file ActionPageUtil.asp.

See Also

Server-Side Routines

sMergeGroups2 (server-side)

xmlMergeGroups2 (server-side)

xmlMergeGroups3 (server-side)

Client-Side Routines

sMergeGroups3 (client-side)


sRelURL2AbsURL (server-side)

Use this routine to convert a Uniform Resource Locator (URL) that is relative to the folder of the current action page into an absolute URL.

Definition

sRelURL2AbsURL(sRelURL)

Parameters

sRelURL

A string containing a URL that is relative to the folder of the current action page.

Return Value

A string containing an absolute URL that is functionally equivalent to the relative URL passed in the sRelURL parameter.

Remarks

This routine is available in the include file ASPUtil.asp.

See Also

Server-Side Routines

Client-Side Routines


xmlGetRequestXML (server-side)

Use this routine to copy the XML in the request to an XML document.

Definition

xmlGetRequestXML

Parameters

None.

Return Value

An XML DOMDocument object containing the XML in the request.

Remarks

This routine expects XML in the form sent by the client routine xmlPostFormViaXML.

This routine is available in the include file HTTPXMLUtil.asp.

See Also

Server-Side Routines

dGetRequestXMLAsDict (server-side)

Client-Side Routines

xmlPostFormViaXML (client-side)


xmlGetXMLDOMDoc (server-side)

Use this routine to create an XML DOMDocument object with an empty documentElement property.

Definition

xmlGetXMLDOMDoc

Parameters

None.

Return Value

An XML DOMDocument object with an empty documentElement property.

Remarks

The string version of the returned document has the following form:

<document />

This routine is available in the include file HTTPXMLUtil.asp.

There is a functionally equivalent version of this routine defined for client-side use in the file HTTPXMLUtil.htm.

See Also

Server-Side Routines

AddCDATANode (server-side)

AddErrorNode (server-side)

AddItemNode (server-side)

AddWarningNode (server-side)

Client-Side Routines

xmlGetXMLDOMDoc (client-side)


xmlGetXMLFromQuery (server-side)

Use this routine to create an XML document element and populate it with record elements corresponding to all of the records returned by the specified query.

This conversion process results in an XML XMLDOMElement object containing the standard XML data record format.

Definition

xmlGetXMLFromQuery(sConnectionString,

                   sQuery)

Parameters

sConnectionString

A string containing an ActiveX Data Object (ADO) connection string describing the database with which to connect. This is usually a property retrieved from a resource in the Site Configuration Store using the GetSiteConfigField routine in the file ASPUtil.asp.

sQuery

A string containing a valid SQL query.

Return Value

An XMLDOMElement object containing record nodes that mirrors the data returned by the specified query.

Remarks

The conversion results in all of the data returned by the specified query being represented as an XML document element (an XMLDOMElement object) containing a number of record elements (more XMLDOMElement objects).

This routine is available in the include file DBUtil.asp.

See Also

Server-Side Routines

xmlGetXMLFromQueryEx (server-side)

xmlGetXMLFromRS (server-side)

xmlGetXMLFromRSEx (server-side)

Client-Side Routines


xmlGetXMLFromQueryEx (server-side)

Use this routine to create an XML document element and populate it with record elements corresponding to some or all of the records returned by the specified query.

This conversion process results in an XML XMLDOMElement object containing the standard XML data record format.

Definition

xmlGetXMLFromQueryEx(sConnectionString,

                     sQuery,

                     nStartRecord,

                     nPageSize,

                     nExRecordCount,

                     dFormats)

Parameters

sConnectionString

A string containing an ActiveX Data Object (ADO) connection string describing the database with which to connect. This is usually a property retrieved from a resource in the Site Configuration store using the GetSiteConfigField routine in the file ASPUtil.asp.

sQuery

A string containing a valid SQL query.

nStartRecord

A number specifying the position in the query results of the first record to be converted. Positions are counted from 0 (zero). A value of –1 causes this parameter to be ignored, which has the same effect as passing a value of 0 (zero).

nPageSize

A number specifying the number of consecutive records to convert. A value of –1 causes all records in the recordset to be converted.

nExRecordCount

A number specifying a record count to override the count from the recordset. A value of –1 causes this parameter to be ignored, resulting in the record count from the Recordset object being used. Pass a value of 'TOO_BIG_TOO_COUNT' when the number of records makes it unreasonable to count them all.

dFormats

A Dictionary object that contains information used for special date/time mapping between ADO date/time formats and Commerce Server Business Desk date/time formats.

Return Value

An XML XMLDOMElement object containing record elements that mirror all or part of the data returned by the specified query.

Remarks

The conversion results in all or part of the data returned by the specified query being represented as an XML document element (an XMLDOMElement object) containing a number of record elements (more XMLDOMElement objects).

The dFormats parameter specifies a Dictionary object that is used to do special date and time related format mapping. The keys in this Dictionary object are the names of fields, and the values are either ActiveX Data Object (ADO) data type values, or a special value corresponding to the constant COMMERCE_SPLIT_DATE. Field names are looked up in this Dictionary object to determine the proper value to pass as the sType parameter of the routine AddFormattedNode. The following table shows these mappings.

Dictionary Value for Field Name Key | sType Value and Processing
AD_DATE, AD_DB_DATE, AD_DB_TIMESTAMP, AD_DB_TIME | sType parameter set to corresponding Dictionary object value.
COMMERCE_SPLIT_DATE Two calls to the AddFormattedNode routine are made with the following parameters:
  1. sName = <ADO field name>_date
    sValue = <ADO field value>
    sType = AD_DB_DATE

  2. sName = <ADO field name>_time
    sValue = <ADO field value>
    sType = AD_DB_TIME
All others. | sType parameter set to corresponding ADO Field type property.

This routine is available in the include file DBUtil.asp.

See Also

Server-Side Routines

xmlGetXMLFromQuery (server-side)

xmlGetXMLFromRS (server-side)

xmlGetXMLFromRSEx (server-side)

Client-Side Routines


xmlGetXMLFromRS (server-side)

Use this routine to create an XML document element and populate it with record elements corresponding to all of the records in the specified ActiveX Data Object (ADO) Recordset object.

This conversion process results in an XML XMLDOMElement object containing the standard XML data record format.

Definition

xmlGetXMLFromRS(rsQuery)

Parameters

rsQuery

An ADO Recordset object, from which the records to be converted are retrieved.

Return Value

An XML XMLDOMElement object containing record elements that mirror the data in the specified ADO Recordset object.

Remarks

The conversion results in all of the data in the specified ADO recordset being represented as an XML document element (an XMLDOMElement object) containing a number of record elements (more XMLDOMElement objects).

This routine is available in the include file DBUtil.asp.

See Also

Server-Side Routines

xmlGetXMLFromQuery (server-side)

xmlGetXMLFromQueryEx (server-side)

xmlGetXMLFromRSEx (server-side)

Client-Side Routines


xmlGetXMLFromRSEx (server-side)

Use this routine to create an XML document element and populate it with record elements corresponding to some or all of the records in the specified ActiveX Data Object (ADO) Recordset object.

This conversion process results in an XML XMLDOMElement object containing the standard XML data record format.

Definition

xmlGetXMLFromRSEx(rsQuery,

                  nStartRecord,

                  nPageSize,

                  nExRecordCount,

                  dFormats)

Parameters

rsQuery

An ADO Recordset object, from which the records to be converted are retrieved.

nStartRecord

A number specifying the position in the recordset of the first record to be converted. Positions are counted from 0 (zero). A value of –1 causes this parameter to be ignored, which has the same effect as passing a value of 0 (zero).

nPageSize

A number specifying the number of consecutive records to convert. A value of –1 causes all records in the recordset to be converted.

nExRecordCount

A number specifying a record count to override the count from the recordset. A value of –1 causes this parameter to be ignored, resulting in the record count from the Recordset object being used. Pass a value of 'TOO_BIG_TOO_COUNT' when the number of records makes it unreasonable to count them all.

dFormats

A Dictionary object that contains information used for special date/time mapping between ADO date/time formats and Commerce Server Business Desk date/time formats.

Return Value

An XML XMLDOMElement object containing record elements that mirror all or part of the data in the specified ADO Recordset object.

Remarks

The conversion results in all or part of the data in the specified ADO recordset being represented as an XML document element (an XMLDOMElement object) containing a number of record elements (more XMLDOMElement objects).

The dFormats parameter specifies a Dictionary object that is used to do special date and time related format mapping. The keys in this Dictionary object are the names of fields, and the values are either ActiveX Data Object (ADO) data type values, or a special value corresponding to the constant COMMERCE_SPLIT_DATE. Field names are looked up in this Dictionary object to determine the proper value to pass as the sType parameter of the routine AddFormattedNode. The following table shows these mappings.

Dictionary Value for Field Name Key | sType Value and Processing
AD_DATE, AD_DB_DATE, AD_DB_TIMESTAMP, AD_DB_TIME | sType parameter set to corresponding Dictionary object value.
COMMERCE_SPLIT_DATE Two calls to the AddFormattedNode routine are made with the following parameters:
  1. sName = <ADO field name>_date
    sValue = <ADO field value>
    sType = AD_DB_DATE

  2. sName = <ADO field name>_time
    sValue = <ADO field value>
    sType = AD_DB_TIME
All others. | sType parameter set to corresponding ADO Field type property.

This routine is available in the include file DBUtil.asp.

See Also

Server-Side Routines

xmlGetXMLFromQuery (server-side)

xmlGetXMLFromQueryEx (server-side)

xmlGetXMLFromRS (server-side)

Client-Side Routines


xmlMergeGroups2 (server-side)

Use this routine to merge two sets of XML records containing different information about the same entities, returning the result as an XML document.

One set of records, known as the master set, contains higher-level information about each entity represented in the set. The other set of records, known as the detail set, contains more detailed information about the same set of entities. Both of these sets of records are contained in XML documents.

The records from each set are matched up and merged into a resulting set of records containing two tiers. The first tier contains the higher-level information, and the second tier contains the detailed information.

Definition

xmlMergeGroups2(xmlMaster,

                xmlDetail,

                sKeyId)

Parameters

xmlMaster

An XML DOMDocument object containing a set of record elements and associated data elements in the standard XML data record structure. These record elements contain the data that appears in the first tier of the resulting standard XML data record structure, and are considered to contain higher-level information.

xmlDetail

An XML DOMDocument object containing a set of record elements and associated data elements in the standard XML data record format. These record elements contain the data that appears in the second tier of the resulting standard XML data record structure, and are considered to contain more detailed information.

sKeyId

A string that corresponds to the name of a data element that exists in both of the XML documents passed as the other parameters. The values for this element are used to match up records from one XML document with the records in the other.

Return Value

An XML DOMDocument object that contains the merged, two-tiered set of records, represented in the standard XML data record format.

Remarks

This routine is useful for preparing a two-tiered XML data record structure for use by a two-level ListSheet HTC. For more information about how the ListSheet HTC expects its data in one-, two-, and three-tiered data record structures, see ListSheet and Standard XML Data Record Format.

For more information about how single-tiered XML data record structures are merged to created two- and three-tiered XML data record structures, see XML Data Merging.

This routine is available in the include file ASPUtil.asp.

There is a functionally equivalent version of this routine defined for client-side use in the file ActionPageUtil.asp.

See Also

Server-Side Routines

sMergeGroups2 (server-side)

sMergeGroups3 (server-side)

xmlMergeGroups3 (server-side)

Client-Side Routines

xmlMergeGroups2 (client-side)


xmlMergeGroups3 (server-side)

Use this routine to merge three sets of XML records containing different information about the same entities, returning the result as an XML document.

One set of records, known as the master set, contains higher-level information about each entity represented in the set. A second set of records, known as the group set, contains more detailed information about the same set of entities. A third set of records, known as the detail set, contains the most detailed information about the same set of entities. All three sets of records are contained in XML documents.

The records from each set are matched up and merged into a resulting set of records containing three tiers. The first tier contains the higher-level information, the second tier contains the group level of detail, and the third tier contains the most detailed information.

Definition

xmlMergeGroups3(xmlMaster,

                xmlGroup,

                xmlDetail,

                sMasterKeyId,

                sDetailKeyId)

Parameters

xmlMaster

An XML DOMDocument object containing a set of record elements and associated data elements in the standard XML data record structure. These record elements contain the data that appears in the first tier of the resulting standard XML data record structure, and are considered to contain higher-level information.

xmlGroup

An XML DOMDocument object containing a set of record elements and associated data elements in the standard XML data record format. These record elements contain the data that appears in the second tier of the resulting standard XML data record structure, and are considered to contain information of a medium level of detail.

xmlDetail

An XML DOMDocument object containing a set of record elements and associated data elements in the standard XML data record format. These record elements contain the data that appears in the third tier of the resulting standard XML data record structure, and are considered to contain the most detailed information.

sMasterKeyId

A string that corresponds to the name of a data element that exists in both the xmlMaster and xmlGroup XML documents. The values for this element are used to match up records in one XML document with records in the other.

sDetailKeyId

A string that corresponds to the name of a data element that exists in both the xmlGroup and xmlDetail XML documents. The values for this element are used to match up records in one XML document with records in the other.

Return Value

An XML DOMDocument object that contains the merged, three-tiered set of records, represented in the standard XML data record format.

Remarks

This routine is useful for preparing a three-tiered XML data record structure for use by a three-level ListSheet HTC. For more information about how the ListSheet HTC expects its data in one-, two-, and three-tiered data record structures, see ListSheet and Standard XML Data Record Format.

For more information about how single-tiered XML data record structures are merged to created two- and three-tiered XML data record structures, see XML Data Merging.

This routine is available in the include file ASPUtil.asp.

There is a functionally equivalent version of this routine defined for client-side use in the file ActionPageUtil.asp.

See Also

Server-Side Routines

sMergeGroups2 (server-side)

sMergeGroups3 (server-side)

xmlMergeGroups2 (server-side)

Client-Side Routines

xmlMergeGroups3 (client-side)


xmlXMLFromDict (server-side)

Use this routine to convert a Dictionary object into an XML document.

Definition

xmlXMLFromDict(byRef dDict)

Parameters

dDict

A Dictionary object to be converted to XML.

Return Value

An XML DOMDocument object containing an item element for each entry in the Dictionary object.

Remarks

Each item element is given two attributes, name and value, initialized to the name and value of each entry in the Dictionary object, as follows:

<item name="keyname" value="value"/>

This routine is available in the include file HTTPXMLUtil.asp.

There is a functionally equivalent version of this routine defined for client-side use in the file HTTPXMLUtil.htm.

See Also

Server-Side Routines

dDictFromXML (server-side)

Client-Side Routines

dDictFromXML (client-side)

xmlXMLFromDict (client-side)

xmlXMLFromForm (client-side)


Debugging Business Desk

The Business Desk Framework includes a number of debugging capabilities of which you should be aware. There are also some miscellaneous factors that you should keep in mind. These can be divided into the following categories:

  • XML Configuration File Changes

  • Debugging HTC Problems

  • XMLHTTP Debugging in Framework Routines

  • XMLHTTP Debugging in the ListSheet and TreeView HTCs

  • Global Flags for Debugging

XML Configuration File Changes

Remember that after making changes to XML configuration files in the Config folder, you must restart the Internet Information Services (IIS) application before the changes will be visible in the user interface.

The output generated by the SHOW_OBJECT_ERRORS and VERBOSE_OUTPUT flags will only display the first time Commerce Server Business Desk is run after the IIS application is restarted. See Global Flags for Debugging for more information.

Debugging HTC Problems

The m_bDebug variable in each HTC file, when set to True, will show developer errors in alerts. You should try this technique whenever an HTC fails to load on the page.

Whenever you change settings in the HTCs, you may want to verify that Internet Explorer is configured to load pages every time they are requested.

To verify that Internet Explorer is configured to load pages every time they are requested

  1. In Internet Explorer, on the Tools menu, click Internet Options.

  2. On the General tab, in the Temporary Internet Files section, click Settings.

  3. In the Settings dialog box, verify that the Every visit to the page option is selected.

XMLHTTP Debugging in Framework Routines

The bDebug variable in the routines xmlPostFormViaXML and xmlUpdateServerState in the file HTTPXMLUtil.htm, when set to True, displays the data being sent and received when using XMLHTTP to post to server. These debug messages are displayed using the dlg_debug.htm page.

XMLHTTP Debugging in the ListSheet and TreeView HTCs

The m_bDebugHTTPXML variable in the HTC files ListSheet.htc and TreeView.htc, when set to True, will display debug information from within the routine xmlPostToServer. It will display the data being sent and received when using XMLHTTP operations. It will display three alerts for each XMLHTTP fetch operation: one for the data that is sent, one for the returned text, and one for the returned XML.

Whenever you change settings in the HTCs, you may want to verify that Internet Explorer is configured to load pages every time they are requested.

To verify that Internet Explorer is configured to load pages every time they are requested

  1. In Internet Explorer, on the Tools menu, click Internet Options.

  2. On the General tab, in the Temporary Internet Files section, click Settings.

  3. In the Settings dialog box, verify that the Every visit to the page option is selected.

Global Flags for Debugging

The MSCSEnv variable in the Global.asa file for Business Desk, when changed from PRODUCTION to DEVELOPMENT, or vice versa, will modify many of the following debug flags at once:

VERBOSE_OUTPUT

When set to True, shows detailed output while loading the XML configuration upon application start, then shows tables representing Dictionary objects stored in the application. Click Refresh to load Business Desk when you are done looking at the output.

SHOW_OBJECT_ERRORS

When set to True, shows XML and other errors in a modeless dialog box upon loading the XML configuration.

AUTO_REDIRECT_ENABLED

When set to True, keeps users from loading a Business Desk page outside the normal Business Desk frame structure (which is enforced in the file BizDeskUtil.asp).

FORCE_HTA_ONLY

When set to True, disallows browsing Business Desk outside of the HTML Application (HTA) provided by the client installation. Setting this variable to False allows you to use the URL "//servername/bizdeskrootname/bizdesk.asp" to run Business Desk in a normal browser.

ALLOW_CONTEXT_MENUS

When set to True, allows right-click context menus so that you can use Refresh and View Source to investigate page failures.

SHOW_DEBUG_TEXT

When set to True, shows a variety of debug information in various ways, as follows:

1. Task and module targets on mouseover.

2. Disabled modules as ERROR (usually file not found) or FILTERED (by user ACLs).

3. Contents of the Request, Session, and Application objects in legend area of status bar.

4. The state of the dirty, required, and valid flags for the page in the title bar.


XML Reference

Extensible Markup Language (XML) is used extensively by Microsoft Commerce Server 2000. Different features use XML in different ways, resulting in a variety of defined XML structures. This section provides reference documentation for these various XML structures.

This section contains:

  • Analysis/Reporting XML Structures. Describes the XML structures used to create reports by Commerce Server Analysis.

  • Catalog XML Structures. Describes the XML structure in which product catalogs must be represented in order to be imported into the Product Catalog System.

  • Business Desk XML Structures. Describes the various XML structures used by Commerce Server Business Desk, including those used to define category and module structure, and those used by the various HTML Components (HTCs).

  • Expression XML Structures. Describes the XML structure used by the expression architecture.

  • Profile XML Structures. Describes the XML schemas and data structures used by the Profile service.


Analysis/Reporting XML Structures

This section describes the minimal Extensible Markup Language (XML) structure needed for creating a dynamic report.

For online analytical processing (OLAP) reports, the cube name must be supplied. For SQL reports, a query must be provided.

After the report is displayed, the layout can be dynamically modified and the results saved from Commerce Server Business Desk.

The XML structure should not be directly edited after the report is initially created. Make any modifications to the report using the pivot control available through Business Desk.

XML Structure

<xml xmlns:x=''urn:schemas-microsoft-com:office:excel''>
<x:PivotTable>
   <x:OWCVersion>9.0.0.3821</x:OWCVersion>
   <x:DisplayFieldList/>
      <x:FieldListTop>300</x:FieldListTop>
      <x:FieldListLeft>800</x:FieldListLeft>
      <x:FieldListBottom>700</x:FieldListBottom>
      <x:FieldListRight>1000</x:FieldListRight>
   <x:CacheDetails/>
   <x:ConnectionString>ConnectionString</x:ConnectionString>
   [<x:CommandText>QueryString</x:CommandText>]
   [<x:DataMember>CubeName</x:DataMember>]
</x:PivotTable>
</xml>

The CommandText element is used only for SQL reports and contains the SQL query.

The DataMember element is used only for OLAP reports and contains the cube name.

The ConnectionString is one of the following types:

  • For SQL reports: "Provider=SQLOLEDB;Data Source=;Initial Catalog=;Integrated Security=SSPI"

  • For MDX reports: "Provider=MSOLAP;Data Source=;Initial Catalog=;Client Cache Size=25;Auto Synch Period=10000"

The values of the Data Source and Initial Catalog attributes are not specified in the connection string. These values are obtained from the Administration database at report run time.

See Also

Analysis/Reporting Schema

AsyncRpt Object

Creating Custom Reports

ReportRender Object

Running Reports


Catalog XML Structures

The Microsoft Commerce Catalog Extensible Markup Language (XML) format is designed to represent product catalogs in a format suitable for exchange between applications and for transport over the Internet.

The format itself is defined in an XML data schema, allowing it to be used with XML data-aware tools such, as BizTalk Server mapping tools.

The Commerce Catalog XML format is intended to represent a large variety of product catalogs, and for this reason uses the notion of a "meta-schema." That is, the way that a certain product may be represented in the format itself is defined in a schema definition section. This schema definition section defines the types of attributes that the catalog (or rather, catalog collection) stores to describe both products and categories, and defines the attributes recorded against different types of products and categories.

The Commerce Catalog XML format does not propose any fixed representation of particular types of products, but provides a means by which almost any product description can be recorded in a rich form.

The format also allows for multiple catalogs to be represented in one XML file.

This section contains:

  • XML Structure. Shows the XML structure.

  • XML Elements. Describes the XML elements and their relations.

  • Import Semantics. Describes the semantics that apply when importing a Commerce Server Catalog XML file.

  • XDR Schema. Shows the XML Data-Reduced (XDR) schema used to define the XML elements, attributes, and relations.


XML Structure

This section describes the Extensible Markup Language (XML) structure, elements, and attributes of the Microsoft Commerce Catalog. In the following example, unitalicized names refer to the elements of the XML structure. The first occurrence of each element is linked to documentation on that element. Names in italic are attributes associated with each element.

<MSCommerceCatalogCollection>
   <CatalogSchema>
      <AttributeDefinition name DataType Id />
      <Definition Name DefinitionType properties variantProperties />
      <PropertiesDefinition>
         <Property name DataType MinValue MaxValue DisplayName id
                   AssignAll DefaultValue DisplayInProductsList
                   DisplayOnSite ExportToDW IncludeInSpecSearch
                   IsFreeTextSearchable />
            <PropertyValue DisplayName />
         </Property>
      </PropertiesDefinition>
   </CatalogSchema>
   <Catalog catalogName description locale startDate endDate
            productIdentifier productVariantIdentifier currency>
      <Category name Definition isSearchable id parentCategories
                listprice>
         <Field fieldID fieldValue />
         <Relationship name description relation />
      </Category>
      <Product definition listprice id parentCategories pricingCategory>
         <Field fieldID fieldValue />
         <ProductVariant Id>
            <Field fieldID fieldValue />
         </ProductVariant>
         <Relationship name description relation />
      </Product>
   </Catalog>
</MSCommerceCatalogCollection>


XML Elements

The Microsoft Commerce Catalog Extensible Markup Language (XML) elements are divided into three groups:

  • MSCommerceCatalogCollection. The root node for a Commerce Catalog XML file.

  • Catalog Schema Elements. These elements are used to extend the catalog: CatalogSchema, AttributeDefinition, Definition, PropertiesDefinition, Property, and PropertyValue.

  • Catalog Data Elements. These elements are used for the actual catalog and its members: Catalog, Category, Field, Product, ProductVariant, and Relationship.

AttributeDefinition

Defines an attribute that can be used to describe an aspect of a property, such as its "display name". This allows additional attributes to be defined on fields on top of the built in ones: name, maxSize, defaultValue, and so on.

Parent Elements: CatalogSchema

Child Elements: None

Attributes:

Name | Description
DataType | Valid types are: datetime money number string bignumber real float currency boolean
id | A unique ID for each node in the document. May not contain spaces (an XML requirement).
name | The name of the attribute definition.

Catalog

Defines an individual catalog.

Parent Elements: MSCommerceCatalogCollection

Child Elements: Category, Product

Attributes:

Name | Description
catalogName | The name of the catalog.
currency | The currency used in the catalog, expressed as a three letter ISO 4217 currency code. For example "USD", "AUD", "CDN", "GBP", "DEM", "JPY".
description | A description of the catalog.
endDate | The date the catalog validity expires. Used for documentation purposes only – Commerce Server does not apply any logic to this value.
locale | The locale of the catalog, specified using a Windows Locale ID (LCID). Used for documentation purposes to indicate which locale the catalog is intended for.
productIdentifier | The name of the property that uniquely identifies products (or product families) in the catalog.
productVariantIdentifier | The name of the property that uniquely identifies product variants in the catalog. If the catalog does not contain products with variants, set this attribute to the same value as the value in the productIdentifier attribute.
startDate | The date the catalog becomes valid. Used for documentation purposes only – Commerce Server does not apply any logic to this value.

CatalogSchema

Contains the schema definition elements for the Catalog collection.

Parent Elements: MSCommerceCatalogCollection

Child Elements: AttributeDefinition, Definition, PropertiesDefinition

Attributes: None

Category

Defines an instance of a type of category.

Parent Elements: Catalog

Child Elements: Field, Relationship

Attributes:

Name | Description
Definition | The name of the category definition that the category is based on.
id | The XML ID for the category element.
isSearchable | Indicates whether this category is to be used as a starting point for specification searches. True indicates this category will be included in the record set returned by calls to the ProductCatalog.GetSearchableCategories object. The values are 0 for False; 1 for True.
name | The name of the category. This name must be unique for all categories in the same catalog.
parentCategories | The XML IDs of the categories that are immediate parents of this category.
listprice | The price that should be applied to any products that reference this category as their pricing category. Units for this value are determined by the currency attribute of the containing catalog.

Definition

Defines a type of product or category.

Parent Elements: CatalogSchema

Child Elements: None

Attributes:

Name | Description
DefinitionType | The type of the definition — either "product" or "category".
Name | The name of the property. This name must be unique within the XML document.
properties | The XML node IDs of the properties that are to be included in this product or category definition.
variantProperties | The XML node IDs of the properties that are to be included as variant properties for this product definition. Use this attribute only for definitions of type "product".

Field

Defines a name and value pair for a field.

Parent Elements: Category, Product, ProductVariant

Child Elements: None

Attributes:

Name | Description
fieldID | The name of the property a value is being supplied for.
fieldValue | The value for the property.

MSCommerceCatalogCollection

The root node for a Commerce Catalog XML file.

Parent Elements: None

Child Elements: CatalogSchema, Catalog

Attributes: None

Product

Defines an instance of a type of product.

Parent Elements: Catalog

Child Elements: Field, ProductVariant, Relationship

Attributes:

Name | Description
definition | The name of the product definition that the product is based on.
id | The XML ID for the product element.
listprice | The price for this product. Units for this value are determined by the currency attribute of the containing catalog.
parentCategories | The XML IDs of the categories that the product belongs to.
pricingCategory | The XML ID of the category that the product inherits pricing from. Use of this attribute is optional.

ProductVariant

Defines an instance of a variant of a product.

Parent Elements: Product

Child Elements: Field

Attributes:

Name | Description
id | The XML ID for the variant element.

PropertiesDefinition

Container for the individual property definitions.

Parent Elements: CatalogSchema

Child Elements: Property

Attributes: None

Property

Defines a property that can be used to describe an aspect of a product or category.

Parent Elements: PropertiesDefinition

Child Elements: PropertyValue

Attributes:

Name | Description
AssignAll | Indicates whether this property should automatically be assigned to product definitions as they are created through Commerce Server Business Desk. The values are: "1" (True) or "0" (False).
DataType | Legal values are: datetime enumeration filename float money number string bignumber currency boolean real
DefaultValue | The default value for instances of the property. This value will be interpreted according to the datatype specified for this property. Datetime values must be specified in XML Date format.
DisplayInProductsList | Indicates whether this property is to be displayed in summary lists of products in the Business Desk Catalog Editor, or in other areas where product lists are displayed. The values are: "1" (True) or "0" (False)
DisplayName | The display name for the property, for example, the label that will be shown next to the values for this property to site users.
DisplayOnSite | Indicates whether this property should be shown to users visiting the web site. The values are: "1" (True) or "0" (False).
ExportToDW | Indicates whether the Catalog DTS task should export this property into the Data Warehouse. Properties with this attribute set to True will be available for use in reports and data analysis. The values are: "1" (True) or "0" (False)
id | A unique ID for each node in the document. May not contain spaces (an XML requirement).
IncludeInSpecSearch | Indicates whether this property should be exposed to specification searches. The values are: "1" (True) or "0" (False)
IsFreeTextSearchable | Indicates whether this property should be included in the full-text index, and therefore, be free text searchable. The values are: "1" (True) or "0" (False)
MaxValue | The maximum legal value for number data types, and the maximum length for string data types.
MinValue | The minimum legal value for number data types, and the minimum length for string data types.
name | The unique name of the property.

PropertyValue

Defines a legal value for a property.

Parent Elements: Property

Child Elements: None

Attributes:

Name | Description
DisplayName | A legal value for the containing property.

Relationship

Defines a relationship between one product or category and another product or category.

Parent Elements: Category, Product

Child Elements: None

Attributes:

Name | Description
description | The description of the relationship.
name | The name of the relationship.
relation | The XML ID of a product or category in the same catalog in which to relate the containing product or category.


Import Semantics

This section describes the semantics that apply when importing a Commerce Server Catalog XML file.

Catalog Schema Semantics

Catalog Data Semantics

Catalog Schema Semantics

Schema defined in the XML file must not conflict with any schema elements (product, category, and property definitions) that are already defined in the catalog database. If there is a conflict then a descriptive error will be written to the application event log and the import will be abandoned. Schema conflicts can include:

  • Redefining a property to use a different data type than it is already defined as.

  • Redefining a product or category definition to have a different set of member properties.

Schema elements are never deleted as a result of doing a Commerce Catalog XML import — only new schema is added.

The data types that are referenced in the Commerce Catalog XML format are mapped to SQL Server data types as follows:

Catalog XML data type | SQL data type
string | nvarchar
number | int
bignumber * | bigint *
datetime | datetime
currency | money
money | money
boolean | bit
enumeration | nvarchar(128)
real | real
float | decimal
filename | nvarchar(256)

Note

  • The asterisk (*) indicates data types that are only supported on SQL Server 2000.

  • The bignumber, boolean, and real data types are not currently supported byCommerce Server Business Desk.

Catalog Data Semantics

A Catalog XML file can define new catalogs or it can define updates to catalogs that already exist in the Catalog database.

If a catalog that you want to import already exists in the database, the existing catalog can be replaced by the imported catalog, or a merge import can be performed. Follow the rules listed below if you decide to run a merge import:

  • Products can be modified or added but cannot be deleted.

  • Product variants can be modified or added but cannot be deleted.

  • Categories can be modified or added but cannot be deleted.

  • Be aware that a product element that has the same identifying properties as a product that already exists will cause the existing product to be updated. This product element can specify only a subset of the fields that apply to that product in order to update certain properties (for example, to update only the description property or the price).

  • If a product that you want to import already exists in the database (for example, it has the same identifier as an existing product), but is based on a different definition, then the existing product in the database will be deleted and replaced with the new product.

  • If a product being imported already exists in the database you must specify all the parent categories and all the relationships each time the product is imported (or else those relationships will be deleted).


XDR Schema

The XML-Data Reduced (XDR) schema defines the individual elements, attributes, and relations used in the XML structure.

<Schema name="MSCommerceCatalogCollection" xmlns="urn:schemas-microsoft-
        com:xml-data" xmlns:dt="urn:schemas-microsoft-com:datatypes">
   <AttributeType name="name" dt:type="string" required="yes" />
   <AttributeType name="id" dt:type="id" required="yes" />
   <AttributeType name="dataType" dt:type="enumeration" dt:values="string
                  number bignumber datetime money real float currency
                  boolean enumeration filename" required="yes" />
   <AttributeType name="value" />
   <AttributeType name="parentCategories" dt:type="idrefs" />
   <AttributeType name="Definition" dt:type="string" required="yes" />
   <ElementType name="MSCommerceCatalogCollection">
      <element type="CatalogSchema" minOccurs="1" maxOccurs="1" />
      <element type="Catalog" minOccurs="0" maxOccurs="*" />
   </ElementType>
   <ElementType name="PropertiesDefinition">
      <element type="Property" minOccurs="0" maxOccurs="*" />
   </ElementType>
   <ElementType name="CatalogSchema">
      <element type="PropertiesDefinition" minOccurs="0" maxOccurs="1" />
      <element type="Definition" minOccurs="0" maxOccurs="*" />
      <element type="AttributeDefinition" minOccurs="0" maxOccurs="*" />
   </ElementType>
   <ElementType name="AttributeDefinition">
      <attribute type="name" />
      <attribute type="id" />
      <attribute type="dataType" />
   </ElementType>
   <ElementType name="PropertyValue">
      <AttributeType name="displayName" dt:type="string" required="yes" />
      <attribute type="displayName" />
   </ElementType>
   <ElementType name="Property" model="open">
      <AttributeType name="DefaultValue" dt:type="string" />
      <AttributeType name="MinValue" dt:type="string" />
      <AttributeType name="MaxValue" dt:type="string" />
      <AttributeType name="IsFreeTextSearchable" dt:type="boolean" />
      <AttributeType name="IncludeInSpecSearch" dt:type="boolean" />
      <AttributeType name="DisplayOnSite" dt:type="boolean" />
      <AttributeType name="DisplayName" dt:type="string" />
      <AttributeType name="AssignAll" dt:type="boolean" />
      <AttributeType name="ExportToDW" dt:type="boolean" />
      <AttributeType name="DisplayInProductsList" dt:type="boolean" />
      <attribute type="DefaultValue" />
      <attribute type="MinValue" />
      <attribute type="MaxValue" />
      <attribute type="IsFreeTextSearchable" />
      <attribute type="IncludeInSpecSearch" />
      <attribute type="DisplayOnSite" />
      <attribute type="DisplayName" />
      <attribute type="AssignAll" />
      <attribute type="ExportToDW" />
      <attribute type="DisplayInProductsList" />
      <attribute type="name" />
      <attribute type="DataType" />
      <attribute type="id" />
      <element type="PropertyValue" minOccurs="0" maxOccurs="*" />
   </ElementType>
   <ElementType name="Definition">
      <AttributeType name="properties" dt:type="idrefs" />
      <AttributeType name="variantProperties" dt:type="idrefs" />
      <AttributeType name="DefinitionType" required="yes" dt:type=
                     "enumeration" values="product category" />
      <attribute type="name" />
      <attribute type="DefinitionType" />
      <attribute type="properties" />
      <attribute type="variantProperties" />
   </ElementType>
   <ElementType name="Catalog">
      <AttributeType name="currency" required="yes" />
      <AttributeType name="locale" dt:type="string" />
      <AttributeType name="startDate" dt:type="string" />
      <AttributeType name="endDate" dt:type="string" />
      <AttributeType name="productIdentifier" required="yes" dt:type="string" />
      <AttributeType name="productVariantIdentifier" required="yes" dt:type="string" />
      <AttributeType name="weight_measuring_unit" dt:type="string" />
      <element type="Category" minOccurs="0" maxOccurs="*" />
      <element type="Product" minOccurs="0" maxOccurs="*" />
      <attribute type="catalogName" />
      <attribute type="description" />
      <attribute type="currency" />
      <attribute type="locale" />
      <attribute type="startDate" />
      <attribute type="endDate" />
      <attribute type="productIdentifier" />
      <attribute type="productVariantIdentifier" />
   </ElementType>
   <ElementType name="Field">
      <AttributeType name="fieldID" dt:type="idref" />
      <AttributeType name="fieldValue" dt:type="string" required="yes" />
      <attribute type="fieldID" />
      <attribute type="fieldValue" />
   </ElementType>
   <ElementType name="Category">
      <AttributeType name="isSearchable" dt:type="string" />
      <AttributeType name="listprice" dt:type="string" />
      <AttributeType name="image" dt:type="string" />
      <AttributeType name="description" dt:type="string" />
      <attribute type="listprice" />
      <attribute type="id" />
      <attribute type="name" />
      <attribute type="parentCategories" />
      <attribute type="Definition" />
      <attribute type="isSearchable" />
      <element type="Field" minOccurs="1" maxOccurs="*" />
      <element type="Relationship" minOccurs="0" maxOccurs="*" />
   </ElementType>
   <ElementType name="Product">
      <AttributeType name="pricingCategory" />
      <AttributeType name="listprice" dt:type="string" required="yes" />
      <attribute type="listprice" />
      <attribute type="id" />
      <attribute type="definition" />
      <attribute type="pricingCategory" />
      <attribute type="parentCategories" />
      <element type="Field" minOccurs="1" maxOccurs="*" />
      <element type="Relationship" minOccurs="1" maxOccurs="*" />
      <element type="ProductVariant" minOccurs="0" maxOccurs="*" />
   </ElementType>
   <ElementType name="ProductVariant">
      <attribute type="Id" />
      <element type="Field" minOccurs="1" maxOccurs="*" />
   </ElementType>
   <ElementType name="Relationship">
      <AttributeType name="description" dt:type="string" />
      <AttributeType name="relation" required="yes" dt:type="idref" />
      <attribute type="name" />
      <attribute type="description" />
      <attribute type="relation" />
   </ElementType>
</Schema>


Business Desk XML Structures

The Extensible Markup Language (XML) structures used by Commerce Server Business Desk can be divided into three categories:

  • Module Configuration: XML structures used for category and module configuration. These need to be modified only when a new module is added to Business Desk, or in the event that existing modules are rearranged or removed.

  • HTML Component (HTC) Data: XML structures used to represent the data that is displayed within the various HTCs that are provided as part of the Business Desk Framework. For the most part, a single standard format is used, though it can be nested more deeply for some controls than for others. In general, an XML data-island with this structure is one of two data-islands that must exist for a particular HTC to operate correctly.

    The other XML structure in this category is used to represent the nodes in the TreeView HTC. This structure is unique because the data and configuration information are embedded into the same XML structure.

  • HTC Configuration: XML structures used to provide meta-data about the data being displayed. For example, if the data is being displayed in columns, this structure specifies information about each of those columns, such as the column heading, how the data itself should be formatted, the column width, and whether the column can be sorted. In general, an XML data-island of this type is one of two data-islands that must exist for a particular HTC to operate correctly.

This section contains:

  • Master Configuration File. Describes the XML structure of the master module configuration file that ties all other module configuration files together, including their organization into categories.

  • Module Configuration Files. Describes the XML structure of the module configuration files that specify the details of each individual module.

  • Standard XML Data Record Format. Describes the XML structure in which many of the HTCs expect data to be represented. These HTCs include the DynamicTable, EditField, EditSheet, ListEditor, and ListSheet.

  • DynamicTable Configuration. Describes the XML structure of the configuration information for the DynamicTable HTC. Since the DynamicTable HTC makes use of embedded EditField HTCs, much of the configuration information is shared between the two. For more details, see EditField Configuration.

  • EditField Configuration. Describes the XML structure of the configuration information for one or more EditField HTCs.

  • EditSheet Configuration. Describes the XML structure of the configuration information for the EditSheet HTC. Because the EditSheet HTC makes use of embedded EditField HTCs, much of the configuration information is shared between the two. For more details, see EditField Configuration.

  • ExpressionBuilder Configuration. Describes the XML structure of the configuration information for the ExpressionBuilder HTC.

  • ListEditor Configuration. Describes the XML structure of the configuration information for the ListEditor HTC. Because the ListEditor HTC makes use of embedded EditField HTCs, much of the configuration information is shared between the two. For more details, see EditField Configuration.

  • ListSheet Configuration. Describes the XML structure of the configuration information for the ListSheet HTC.

  • QueryBuilder Configuration. Describes the XML structure of the configuration information for the QueryBuilder HTC.

  • TreeView Configuration. Describes the XML structure of the combined data and configuration information used by the TreeView HTC.


Master Configuration File

The master configuration file, which contains XML, is the focal point of category and module configuration for Commerce Server Business Desk. For the sake of modularity, the specific configuration of each module or set of modules is isolated in other XML configuration files, called module configuration files, each of which is referenced by a moduleconfig element within the master configuration file. The module configuration files can be thought of as include files for the master configuration file.

This topic explains the contents of the master configuration file. Specifically, it shows the XML structure. Each element name is a link to a description of the contents of that element; the attributes of each element are shown in italic, without the equal sign and value that normally accompanies them. Required elements and attributes are shown in bold; optional elements and attributes are not in bold.

The XML schema for the master configuration file can be found in a file Bdconfig-schema.xml in the Business Desk Config folder.

Note

  • The XML elements and attributes in the master configuration file must be expressed in lowercase letters.

XML Structure

<?xml version = '1.0' encoding='windows-1252' ?>
<config>
  <categories>
    <category id>
      <name>name with underlined access key</name>
      <key>access key from above</key>
      <tooltip>category tooltip</tooltip>
    </category>
    ...
    <category id>
      <name>name with underlined access key</name>
      <key>access key from above</key>
      <tooltip>category tooltip</tooltip>
    </category>
  </categories>
  <moduleconfigs>
    <moduleconfig category id />
    ...
    <moduleconfig category id />
  </moduleconfigs>
</config>

config

This required element contains all configuration information in the master configuration file.

Parent Element

None (document root).

Required Child Elements

categories, moduleconfigs

Optional Child Elements

None.

Data

None.

Attributes

None.

Return to XML Structure

categories

This required element contains one or more category elements.

Parent Element

config

Required Child Elements

category (at least one, but typically more)

Optional Child Elements

None.

Data

None.

Attributes

None.

Return to XML Structure

category

This required element identifies and describes a Commerce Server Business Desk category.

Parent Element

categories

Required Child Elements

name, key, tooltip

Optional Child Elements

None.

Data

None.

Attributes

Attribute | Description
id | Provides an identifier for the category. Required. Legal values: Generally one word, all lowercase, with no underscores or other special characters. Default value: None. This identifier is also used as the value of the category element of the moduleconfig element to associate a module configuration file with each defined category. The value of the id attribute for each category must be unique.

Return to XML Structure

name

This required element specifies the name of the category as the Commerce Server Business Desk user sees it.

Parent Element

category

Required Child Elements

None.

Optional Child Elements

None.

Data

The category name, as the Business Desk user sees it.

Attributes

None.

Remarks

The specified category name must identify the accessibility key by underlining one of the characters in the name. Properly escaped HTML must be used to implement the underlining: the appropriate character must be preceded by the string &lt;U&gt; and followed by the string &lt;/U&gt;.

For example, if the category name is Content and the accessibility key is "c", the name must be specified as &lt;U&gt;C&lt;/U&gt;ontent. This results in the HTML string <U>C</U>ontent, which appears in the browser as Content.

Return to XML Structure

key

This required element specifies a character that serves as the accessibility key associated with the category.

Parent Element

category

Required Child Elements

None.

Optional Child Elements

None.

Data

The accessibility key, which the Commerce Server Business Desk user sees as an underlined character in the category name.

Attributes

None.

Remarks

The accessibility key for the category should specify the same character identified with underlining in the category name. For example, if the category name is specified such that the user sees the string Content, the character "c" must appear between the <key> and </key> tags.

Return to XML Structure

tooltip

This required element provides a brief description of the purpose of the modules contained within the category, and should be more descriptive than the category name itself.

Parent Element

category

Required Child Elements

None.

Optional Child Elements

None.

Data

The category tooltip string, which the Commerce Server Business Desk user sees when the cursor is over the category name.

Attributes

None.

Return to XML Structure

moduleconfigs

This required element contains references to the various module configuration files specified for this instance of Commerce Server Business Desk.

Parent Element

config

Required Child Elements

moduleconfig (typically contains at least one for each category element defined within the categories element)

Optional Child Elements

None.

Data

None.

Attributes

None.

Remarks

Multiple modules per category can be defined in two ways. First, multiple moduleconfig elements identifying the same category but different module configuration files can be defined. Modules are shown in the category in the same order that the moduleconfig elements appear.

Second, multiple modules can be defined in a single module configuration file, and linked to a category with a single moduleconfig element.

The two approaches can be combined.

Return to XML Structure

moduleconfig

This required element specifies a specific module configuration file for use in this instance of Commerce Server Business Desk.

Parent Element

moduleconfigs

Required Child Elements

None.

Optional Child Elements

None.

Data

None.

Attributes

Attribute | Description
category | Specifies the identifier of the category associated with the modules defined in the module configuration file specified by the id attribute. Required. Legal values: This identifier must match the value of the id attribute specified for one of the category elements. Default value: None.
id | Specifies the (pathless) name of the XML file containing the configuration information for the modules in the specified category. Required. Legal values: The name of an existing module configuration file. Default value: None.

Return to XML Structure


Module Configuration Files

The module configuration files, which contain XML, specify the configuration information at the module level for Commerce Server Business Desk. Each module configuration file is referenced by a moduleconfig element in the master configuration file, together making up the overall configuration of categories and modules for a particular instance of Business Desk. The module configuration files can be thought of as include files for the master configuration file.

This topic explains the contents of the module configuration files. Specifically, it shows the XML structure, where each element name is a link to a description of the contents of that element, and where the attributes of each element are shown in italic, without the equal sign and value that normally accompanies them. Required elements and attributes are shown in bold; optional elements and attributes are not bolded.

The XML schema for the master configuration file can be found in a file Bdmodule-schema.xml in the Business Desk Config folder.

Note

  • The XML elements and attributes in the module configuration files must be expressed in lowercase letters.

XML Structure

<?xml version = '1.0' encoding='windows-1252' ?>
<config>
  <actions>
    <action id helptopic>
      <name>action name</name>
      <tooltip>action tooltip</tooltip>
      <tasks>
        <task icon id type>
          <goto action>menu item name</goto>
          <postto action formname>menu item name</postto>
          <name>task name</name>
          <key>access key from above</key>
          <tooltip>task tooltip</tooltip>
        </task>
        ...
        <task icon id type>
          ...
        </task>
      </tasks>
    </action>
    ...
    <action id helptopic>
      ...
    </action>
  </actions>
  <modules>
    <module id>
      <name>module name</name>
      <tooltip>module tooltip</tooltip>
    </module>
    ...
    <module id>
      ...
    </module>
  </modules>
</config>

config

This required element contains all configuration information in the module configuration files.

Parent Element

None (document root).

Required Child Elements

actions, modules

Optional Child Elements

None.

Data

None.

Attributes

None.

Return to XML Structure

actions

This required element contains one or more action elements specified for the modules defined in this module configuration file.

Parent Element

config

Required Child Elements

action (at least one)

Optional Child Elements

None.

Data

None.

Attributes

None.

Return to XML Structure

action

This required element specifies a particular action available within the module. This includes the URL of the ASP page associated with the action, and identifies the appropriate Help topic and the tasks available within the action.

Parent Element

actions

Required Child Elements

name, tooltip, tasks

Optional Child Elements

None.

Data

None.

Attributes

Attribute | Description
helptopic | Specifies the name of the Help file that corresponds to this action. Required. Legal values: The name of an existing HTML Help file, specified without a path or a file extension. Default value: None.
id | Specifies the URL of the entry point ASP page for this action. Required. Legal values: The URL of an existing entry point ASP page, specified relative to the Commerce Server Business Desk root. Default value: None.

Remarks

Every ASP page that is referenced as the target of a task or module must be identified with an action element. This is required for the Business Desk Framework to properly manage navigation between modules and between the action pages in a module.

Return to XML Structure

name

This required element provides a name for this action.

Parent Element

action

Required Child Elements

None.

Optional Child Elements

None.

Data

The name of the action.

Attributes

None.

Remarks

If the specific action name contains any HTML formatting directives, proper escaping must be used. For example, the string &lt; must be used for the "<" character, the string &gt; must be used for the ">" character, and the string &amp; must be used for the "&" character.

Return to XML Structure

tooltip

This required element provides text that is used as the title attribute for the action.

Parent Element

action

Required Child Elements

None.

Optional Child Elements

None.

Data

The tooltip string associated with the action, which is displayed when the cursor is over the task button.

Attributes

None.

Return to XML Structure

tasks

This required element contains zero or more task elements defined for this action.

Parent Element

action

Required Child Elements

None.

Optional Child Elements

task

Data

None.

Attributes

None.

Remarks

A tasks element does not typically contain zero elements. This corresponds to an action page with no tasks.

There cannot be more than 22 task elements specified within any given tasks element.

Return to XML Structure

task

This required element specifies a particular task available from this action. This includes a specification of one or more ASP pages that serve as entry points to the task, and provides the task name and tooltip information.

Parent Element

tasks

Required Child Elements

name, key, tooltip, goto, postto

(goto and postto are mutually exclusive)

Optional Child Elements

task

Data

None.

Attributes

Attribute Description
icon Specifies the (pathless) name of an icon file to display in the corresponding task button.

Optional.

Legal values: The name of an existing icon file, specified without a path.

Default value: None.

If no icon file is supplied, the value of the name element contained in the task element is used as button text.
id Specifies an identifier for the task, which is typically set to the same value as the icon attribute, but without the "task" prefix.

Required.

Legal values: A unique string to distinguish the task from other tasks.

Default value: None.

The following id attribute values result in special framework behavior: "save", "saveback", "savenew", "back", and "find":

find: stays on the same page and toggles the display of the find pane on the page.

back: always re-enabled after a task is executed.

save, saveback and savenew: enabled/disabled automatically by the framework if you have set the proper event handlers on the associated events in the master EditSheet HTC.
type Specifies that a task menu should be used to distinguish between multiple sub-tasks.

Optional.

Legal values: The string "menu" is the only legal value

Default value: None.

This attribute should be set to the value "menu" when multiple goto or postto elements are provided and a task menu is to be used to choose between the available sub-tasks. Otherwise, this attribute should not be present.

Remarks

Each task appears as a task button at the top of the page when the action page is displayed.

Return to XML Structure

goto

This element specifies one of possibly several ASP pages that serve as entry points to this task. Every task must contain at least one goto or postto element, and may contain more than one. However, goto and postto elements cannot both appear in the same task.

Parent Element

task

Required Child Elements

None.

Optional Child Elements

None.

Data

When a task menu is being used, the element data is used as the task menu item name corresponding to this choice.

Attributes

Attribute Description
action Specifies the URL of one of possibly several entry point ASP pages for this task.

Required.

Legal values: The URL of an existing entry point ASP page, specified relative to the Commerce Server Business Desk root.

Default value: None.

This value must correspond to the value of the id attribute for one of the action elements specified in this module configuration file.

Remarks

When multiple goto elements are specified, the preferred method for allowing the user to decide between them is to use a task menu. The type attribute of the task element should be set to the value "menu", and the multiple goto elements should each contain data to be used as the name of that choice in the drop-down task menu.

When task menus are used, the icon specified by the icon attribute should specify that the task is a task menu. For more information about task icons, and task menu icons in particular, see Icons.

When task menus are used, there cannot be more than 30 task menu items (goto elements) specified.

Another method lets users choose in a selection dialog box provided by the module. At times, however, the choice is determined by other factors, such as the type of item selected in a ListSheet HTC.

Return to XML Structure

postto

This element specifies one of possibly several ASP pages that serve as entry points to this task. Every task must contain at least one postto or goto element, and may contain more than one. However, both postto and goto elements must not appear in the same task.

Parent Element

task

Required Child Elements

None.

Optional Child Elements

None.

Data

When a task menu is being used, the element data is used as the task menu item name corresponding to this choice.

Attributes

Attribute Description
action Specifies the URL of one of possibly several entry point ASP pages for this task.

Required.

Legal values: The URL of an existing entry point ASP page, specified relative to the Commerce Server Business Desk root.

Default value: None.

This value must correspond to the value of the id attribute for one of the action elements specified in this module configuration file.
formname Specifies the name of the form that is posted to the URL specified by the action attribute.

Required.

Legal values: The name of an existing form element.

Default value: None.

Remarks

When multiple postto elements are specified, the preferred method for allowing the user to decide between them is to use a task menu. The type attribute of the task element should be set to the value "menu", and the multiple postto elements should each contain data to be used as the name of that choice in the drop-down task menu.

When task menus are used, the icon specified by the icon attribute should be of the correct type to specify that the task is a task menu. For more information about task icons, and task menu icons in particular, see Icons.

When task menus are used, there cannot be more than 30 task menu items (postto elements) specified.

At times, however, the choice is determined by other factors, such as the type of item selected in a ListSheet HTC. At times, however, the choice is determined by other factors, such as the type of item selected in a ListSheet HTC.

Return to XML Structure

name

This required element specifies the name of this task.

Parent Element

task

Required Child Elements

None.

Optional Child Elements

None.

Data

The name of the task.

Attributes

None.

Remarks

This name is used as the button text if no icon file is specified for this task. Otherwise the name is not used.

If the specific task name contains any HTML formatting directives, proper escaping must be used. For example, the string &lt; must be used for the "<" character, the string &gt; must be used for the ">" character, and the string &amp; must be used for the "&" character.

Return to XML Structure

key

This required element specifies a character that serves as the accessibility key associated with the task.

Parent Element

task

Required Child Elements

None.

Optional Child Elements

None.

Data

The single character that serves as the accessibility key for this task, which should correspond to an underlined character in the task name.

Attributes

None.

Remarks

The accessibility key for the task should specify the same character identified with underlining in the task name. For example, if the task name is specified such that the user sees the string Delete, the character "d" must appear between the <key> and </key> tags.

Return to XML Structure

tooltip

This optional element provides a very brief description of the purpose of this task, and should be more descriptive than the task name itself. The provided text is set as the title attribute for the task button, and is visible when the cursor is over the task.

Parent Element

task

Required Child Elements

None.

Optional Child Elements

None.

Data

The task tooltip, as shown when the cursor is over the task button.

Attributes

None.

Return to XML Structure

modules

This required element contains one or more module elements.

Parent Element

config

Required Child Elements

module

Optional Child Elements

None.

Data

None.

Attributes

None.

Return to XML Structure

module

This required element provides information used in the display of a module entry below a category in the navigation pane. It also identifies a corresponding action. Together, this information defines the entry points into a module.

Parent Element

modules

Required Child Elements

name, tooltip

Optional Child Elements

None.

Data

None.

Attributes

Attribute Description
id Specifies the URL of the entry point ASP page for this module.

Required.

Legal values: The URL of an existing entry point ASP page, specified relative to the Commerce Server Business Desk root.

Default value: None.

This value must correspond to the value of the id attribute for one of the action elements specified in this module configuration file.

Remarks

A given (conceptual) module may have more than one entry point action associated with it.

Return to XML Structure

name

This required element specifies the name of the module as the Commerce Server Business Desk user sees it in the navigation pane.

Parent Element

module

Required Child Elements

None.

Optional Child Elements

None.

Data

The module name, as the user sees it.

Attributes

None.

Remarks

If the specific module name contains any HTML formatting directives, proper escaping must be used. For example, the string &lt; must be used for the "<" character, the string &gt; must be used for the ">" character, and the string &amp; must be used for the "&" character.

Return to XML Structure

tooltip

This optional element provides a very brief description of the purpose of this module, and should be more descriptive than the module name itself. The provided text is set as the title attribute for the module entry in the navigation pane.

Parent Element

module

Required Child Elements

None.

Optional Child Elements

None.

Data

The module tooltip, as shown when the cursor is over the module name.

Attributes

None.

Return to XML Structure


Standard XML Data Record Format

Many of the HTML components (HTCs) in the Commerce Server Business Desk Framework expect the data they display to be provided in a standard XML data record format, available as an XML document on the page. These HTCs include DynamicTable, EditField, EditSheet, ListEditor, and ListSheet. In general, this XML structure contains a single tier of record elements, where each record element contains the same set of child elements. Child element names are arbitrary (shown as dataidN in the structures below), but they do need to correspond to the value of certain id attributes in the corresponding configuration information for the HTC in question.

Note

  • Certain types of ListSheet HTCs expect more than a single tier of record elements, as described below.

For more information about how an XML document can be included on a page (creating an XML data-island), see XML Data-Islands.

This section contains:

  • Mapping Data to Meta-data. Describes how items of data from the DataXML data-island are mapped to the data descriptions provided in the MetaXML data-island.

  • Multi-Tiered Data Record Formats. Introduces two- and three-tiered data record formats, and describes which varieties of the ListSheet HTC expect which format.

  • Standard Data Record XML Structure. Provides detailed information about the elements and attributes of the standard data record format.

  • XMLlist and XMLrecord Properties. Discusses two variations of the standard data record format that are used as event object properties and normal HTC properties by the DynamicTable, ListEditor, and ListSheet HTCs.


Mapping Data to Meta-data

The following table shows how the names of the elements that are children of the record element correspond to attribute settings in the configuration information for various HTCs.

HTC Using One-Tier XML Data Data Mapping
DynamicTable

EditField

EditSheet

ListEditor

 The dataid element names contained in the record elements in the XML data should correspond to the value of the id attribute for the child elements of the fields element in the XML meta-data.

The child elements of the fields element are the set: boolean, date, numeric, select, text, and time.
ListSheet

ListEditor

 The dataid element names contained in the record elements in the XML data should correspond to the value of the id attribute for the column elements in the XML meta data.

Note

  • In the ListSheet HTC, this is the column element that is a child of the columns element, not the column element that is a child of the subobject element.

ListSheet HTCs that use this form of data display flat lists. In this case the meta data subobject element should not be used.

Note

  • Since the ListEditor HTC embeds both a ListSheet HTC and an EditSheet HTC, and its meta-data contains both field elements and column elements, the dataid element is interpreted both ways.


Multi-Tiered Data Record Formats

More complex forms of the ListSheet HTC make use of two- and three-tiered XML structures for their data. Essentially, these alternate structures allow nested record elements to two and three levels, respectively. Both of these alternate structures are shown below.

The following table shows how the ListSheet HTC makes use of the two- and three-tiered XML structures for the various types of ListSheet HTCs. Since there are two types of column elements in the meta-data for the ListSheet HTC (child elements of the columns and subobject elements, respectively), the following table qualifies instances of the column element with the appropriate parent element in parentheses.

Types of ListSheet HTC | Data Mapping
Flat List | Uses the one-tiered XML structure for data, as described above.
Two-level Homogeneous Grouped List | The dataid element names contained in the second-level record elements in the XML data should correspond to the value of the id2 attribute for the column (columns) elements in the XML meta-data. There should not be a third level in the data XML structure, and the id3 attribute of the meta-data column (columns) element is not used. In this case the meta-data subobject element should not be used.
Three-level Homogeneous Grouped List | The dataid element names contained in the second-level and third-level record elements in the XML data should correspond to the values of the id2 and id3 attributes for the column (columns) elements, respectively, in the XML meta-data. In this case the meta-data subobject element should not be used.
List-style Heterogeneous Grouped List and Properties-style Heterogeneous Grouped List | The dataid element names contained in the second-level record elements in the XML data should correspond to the value of the id attribute for the column (subobject) elements in the XML meta-data. There should not be a third level in the data XML structure, and the id2 and id3 attribute of the column (columns) element is not used.


Standard Data Record XML Structure

The following XML structures show the one-, two-, and three-tiered versions of the data record format, where element names link to a description of the contents of that element, and where the attributes of each element are shown in italic, without the equal sign and value that normally accompanies them. Required elements and attributes are shown in bold; optional elements and attributes are not in bold.

Note

  • The XML elements and attributes in the standard data record format must be expressed in lowercase letters.

XML Structure

One-Tier Format

<document recordcount>
    <record>
        <dataid1>Value</dataid1>
        <dataid2>Value</dataid2>
        <dataid3>Enumeration value</dataid3>
        <dataid3_displayname>Display name for value</dataid3_displayname>
        ...
        <dataidN>Value</dataidN>
    </record>
    ...
    <record>
        <dataid1>Value</dataid1>
        <dataid2>Value</dataid2>
        <dataid3>Enumeration value</dataid3>
        <dataid3_displayname>Display name for value</dataid3_displayname>
        ...
        <dataidN>Value</dataidN>
    </record>
</document>

Two-Tier Format

<document recordcount>
    <record>
        <dataid1>Value</dataid1>
        <dataid2>Value</dataid2>
        <record>
            <dataid21>Value</dataid21>
            <dataid22>Value</dataid22>
        </record>
    </record>
</document>

Three-Tier Format

<document recordcount>
    <record>
        <dataid1>Value</dataid1>
        <dataid2>Value</dataid2>
        <record>
            <dataid21>Value</dataid21>
            <dataid22>Value</dataid22>
            <record>
                <dataid31>Value</dataid31>
                <dataid32>Value</dataid32>
            </record>
        </record>
    </record>
</document>

document

This required element is the XML root element within the XML data-island and contains the record elements, potentially nested to three levels in depth.

Parent Element

None (document root).

Required Child Elements

record (one or more)

Optional Child Elements

None.

Data

None.

Attributes

Attribute Description
recordcount Specifies the number of (top level) record elements contained by this element.

Required only by the ListSheet HTC so that it can properly update the page controls when using HTTP fetch operations. It is not used by any other HTCs and is ignored if present.

Legal values: positive integers, 0, and -1.

A value of 0 indicates an empty list. Such a list must contain a single record element containing empty sub-elements.

A value of –1 indicates a list of unknown size. The ListSheet HTC displays such lists as a multi-page list with an unknown number of pages.

Default value: None.

Return to XML Structure

record

This required element contains all the data for a particular record. This data is represented as a series of contained elements, one for each field in the record.

Parent Element

document

Required Child Elements

None.

Optional Child Elements

dataid, record

Data

None.

Attributes

None.

Remarks

There can be one or more record elements. The record element contains dataid elements, and for two- and three-tiered XML structures, other record elements.

Return to XML Structure

dataid

These elements contain the data to be displayed in a particular field in the associated HTC. No element with a particular name is required, though a record element without any contained dataid elements would not be a very interesting record.

Parent Element

record

Required Child Elements

None.

Optional Child Elements

None.

Data

The actual data value.

Attributes

None.

Remarks

The names of these elements typically originate as field names in the ADO Recordset object from which this XML structure is derived. The standard set of functions used to convert ADO Recordset objects to XML use the Recordset field name as the corresponding element name in the produced XML.

These names are also used to associate each data value with a particular column being displayed in a particular HTC. All HTCs that are passed a data-island in this format are also passed a corresponding data-island identified by the MetaXML container attribute. Data-islands of this latter type have elements that correspond to the data to be displayed. These elements describe the data, including such information as their data types. They also include an id attribute. The value of the id attribute should be the same as the name of the dataid element in the data-island associated with the DataXML container attribute.

The following table shows, for each HTC using a DataXML data-island of this format, the MetaXML element whose id attribute corresponds to the name of a dataid element in that data-island.

HTCs | MetaXML Elements | Notes
DynamicTable | id attribute of boolean, date, numeric, select, text, and time elements. | The value of the id attribute of one of the child elements of the fields element corresponds to a dataid element in the DataXML data-island.
EditField | id attribute of boolean, date, numeric, select, text, and time elements. | The value of the id attribute of one of the child elements of the fields element corresponds to a dataid element in the DataXML data-island. It also corresponds to the value of the DataID container attribute.
EditSheet | id attribute of boolean, date, numeric, select, text, and time elements. | The value of the id attribute of one of the child elements of the fields element corresponds to a dataid element in the DataXML data-island.
ListEditor | id attribute of boolean, date, numeric, select, text, and time elements. | The value of the id attribute of one of the child elements of the fields element corresponds to a dataid element in the DataXML data-island.
ListSheet | id attribute of column (columns) element. id2 attribute of column (columns) element. id3 attribute of column (columns) element. id attribute of column (subobject) element. | The value of the dataid element can occur in these four distinct places in the corresponding MetaXML data-island, depending on the type of ListSheet HTC being employed. For more information, see the detailed explanation at the beginning of this topic.

Return to XML Structure

dataid, dataid_displayname

These elements contain enumerated data to be displayed in a particular field in the associated HTC. No such element pairs sharing a particular name root (dataid) are required.

Parent Element

record

Required Child Elements

None.

Optional Child Elements

None.

Data

dataid: The actual data value.

dataid_displayname: The display name associated with the dataid element.

Attributes

None.

Remarks

Data for enumerated types is handled somewhat differently than other data types within the data-islands corresponding to the DataXML container attribute. The data value itself is formatted the same as the other types — as data contained within an element whose name serves to identify that data.

A display name associated with the enumerated type may be supplied in the data-island as data for another, sibling XML element. The name of the sibling element is the same as for the corresponding value, with the string "_displayname" appended to it.

For example, suppose that for a select element within the MetaXML data-island associated with an EditSheet HTC (or a column element with its format attribute set to "select" within the MetaXML data-island associated with a ListSheet HTC), the id attribute is set to "eyecolor". In the corresponding DataXML data-island, there should be elements that look like the first line in the following example, and there can optionally be lines like the second line in the following example:

    <eyecolor>3</eyecolor>
    <eyecolor_displayname>Blue</eyecolor_displayname>

In this example, the value "3" corresponds to blue eyes, and the string "Blue" is displayed to the user.

If the DataXML data-island does not contain the _displayname variety of elements, the HTC inserts such elements into the DataXML data-island. This is accomplished through the following series of steps:

  1. Search the MetaXML data-island for a select element with an id attribute that matches the data element name from the DataXML data-island.

  2. If such a select element is found, search its option elements for one that has a value attribute with a value equal to the actual data in the DataXML data-island.

  3. If such an option element is found, use its data value as the data contained in the newly inserted data_element_name_displayname element.

In some situations the page itself will have to set the proper _displayname elements because there are more than one possible select elements within the MetaXML data-island that might need to be searched. Which one should be used probably depends on some other setting on the page, which only that page is in a position to know. For an example of this behavior, see the page Regionaltax.asp in the Tax module. This page contains a DynamicTable HTC with two select fields that must be kept synchronized.

Return to XML Structure


XMLlist and XMLrecord Properties

Certain properties associated with HTML Component (HTC) events, and certain properties of the HTCs themselves, return two different variations of the standard data record format, as nested XML DOM objects starting with an XMLDOMElement object. The two variations are an XMLlist, which contains multiple records, and an XMLrecord, which contains a single record.

The following table shows the circumstances under which the relevant HTCs make use of properties of these forms.

HTC XMLlist and XMLrecord Usage
DynamicTable HTC XMLlist:
  • XMLlist property of the window.event object in OnChange event.

  • XMLlist HTC property.

XMLrecord: Not used.
ListEditor HTC XMLlist:
  • XMLlist property of the window.event object in OnChange event.

  • XMLlist HTC property.

XMLrecord:

  • XMLrecord property of the window.event object in OnEdit event.

  • XMLrecord property of the window.event object in OnNew event.
ListSheet HTC XMLlist:
  • XMLlist HTC property.

XMLrecord:

  • XMLrecord property of the window.event object in OnRowSelect event.

  • XMLrecord property of the window.event object in OnRowUnselect event.

XMLlist Structure

The structure of the XMLlist property is as follows. The top level node is an XMLDOMELement object with its tagName property set to "document".

<document>
    <record>
        <dataid1>data</dataid1>
        <dataid2>data</dataid2>
        . . .
    </record>
    <record>
        <dataid1>data</dataid1>
        <dataid2>data</dataid2>
        . . .
    </record>
    . . .
</document>

When used as a property in the DynamicTable and ListEditor HTCs, both of which allow changes to the data, an additional attribute, named state, is associated with each record element. The state attribute can have four possible values: an empty string indicating that the record is unchanged, "new" indicating that the record is new, "changed" indicating that the record has been changed, and "deleted" indicating that the record has been deleted.

XMLrecord Structure

The structure of the XMLrecord property is as follows. The top level node is an XMLDOMELement object with its tagName property set to "record".

<record>
    <dataid1>data</dataid1>
    <dataid2>data</dataid2>
    . . .
</record>


DynamicTable Configuration

The XML data-island identified by the MetaXML container attribute contains the configuration information used by the DynamicTable HTML component (HTC).

For more information about how an XML document can be included on a page (creating an XML data-island), see XML Data-Islands.

The structure of this data-island is shown below, with links to more detailed explanations of each element. Element attributes are shown in italic and without the values that are normally associated with them. Required elements and attributes are shown in bold; optional elements and attributes are not in bold.

Note

  • The XML elements and attributes in the MetaXML data-island for the DynamicTable HTC must be expressed in lowercase letters.

XML Structure

<dynamictable>
  <global removebutton keycol newbutton overx
          required sortbykey uniquekey />
  <fields>
    <boolean browse browsereadonly default disabled hide
             id onbrowse onchange onerror readonly width
      <browsetooltip>Tooltip for browse button</browsetooltip>
      <name>Column heading name</name>
      <label>Checkbox label</label>
    </boolean>
    <date browse browsereadonly default disabled firstday
          hide id max min onbrowse onchange onerror
          onrequire onvalid readonly required width
      <browsetooltip>Tooltip for browse button</browsetooltip>
      <format>Date format to use</format>
      <error>Validation error message</error>
      <name>Column heading name</name>
      <prompt>Empty control prompt</prompt>
    </date>
    <numeric browse browsereadonly default disabled hide id
             max min onbrowse onchange onerror onrequire
             onvalid readonly required subtype width
      <browsetooltip>Tooltip for browse button</browsetooltip>
      <format>Number format to use</format>
      <error>Validation error message</error>
      <name>Column heading name</name>
      <prompt>Empty control prompt</prompt>
    </numeric>
    <select browse browsereadonly default disabled hide id
            onbrowse onchange onerror onvalid readonly width
      <browsetooltip>Tooltip for browse button</browsetooltip>
      <name>Column heading name</name>
      <prompt>Empty control prompt</prompt>
      <select id>
        <option value>Item display name</option>
      </select>
      ...
      <select id>
        <option value>Item display name</option>
      </select>
    </select>
    <text browse browsereadonly default disabled hide id
          maxlen minlen onbrowse onchange onerror onrequire
          onvalid readonly required subtype width
      <browsetooltip>Tooltip for browse button</browsetooltip>
      <charmask>Validation character mask</charmask>
      <error>Validation error message</error>
      <name>Column heading name</name>
      <prompt>Empty control prompt</prompt>
    </text>
    <time browse browsereadonly default disabled hide
          id max min onbrowse onchange onerror
          onrequire onvalid readonly required width
      <browsetooltip>Tooltip for browse button</browsetooltip>
      <error>Validation error message</error>
      <name>Column heading name</name>
      <prompt>Empty control prompt</prompt>
    </time>
  </fields>
</dynamictable>

dynamictable

This required element serves as the container for the DynamicTable configuration data that identifies it as intended for use with a DynamicTable HTC.

Parent Element

None (document root).

Required Child Elements

global, fields

Optional Child Elements

None.

Data

None.

Attributes

None.

Return to XML Structure

global

This required element provides configuration information that affects the general behavior of the DynamicTable HTC.

Parent Element

dynamictable

Required Child Elements

None.

Optional Child Elements

None.

Data

None.

Attributes

Attribute | Description
removebutton | Specifies whether the Remove button will be displayed. Optional. Legal values: "yes" and "no". Default value: "yes". If the value is "no", the Remove button will not be displayed.
keycol | Specifies the ID of the field that will be used as the record key for sorting, unique key checks, and so forth. Required. Each field type for which sorting is allowed (numeric and text types only) has the required attribute id; this attribute must be set to one of those id values.
newbutton | Specifies whether the New button will be displayed. Optional. Legal values: "yes" and "no". Default value: "yes". If the value is "no", the New button will not be displayed.
overx | Controls the display of the last row in the table. Optional. Legal values: "yes" and "no". Default value: "no". If the value is "yes", the last row in the table is manipulated after each sort operation based on the value in the field specified by the keycol attribute. If the value of this field in the last row is "–1", the field is displayed as "Over X", where "X" is the value in the same field, one row above. If the value of this field in the last row is not "-1", a new row is inserted with "Over X" text in that field and all other fields being empty. In the case where there are no rows, a row is inserted with "Over 0" displayed in the key column. For more information about the OverX feature of the DynamicTable HTC, see OverX Feature.
required | Specifies whether the table can be empty, and controls the display of the "required" icon. Optional. Legal values: "yes" and "no". Default value: "no". If the value is "yes", the table cannot be empty.
sortbykey | Specifies whether the table is re-sorted according to the values in the field specified by the keycol attribute when the Done button is pressed. Optional. Legal values: "yes" and "no". Default value: "no". If the value is "yes", the re-sorting is performed.
uniquekey | Specifies whether the uniqueness of values in the key column should be enforced. Optional. Legal values: "yes" and "no". Default value: "no". If the value is "yes", uniqueness validation is performed.

Return to XML Structure

fields

This required element contains the elements that specify the fields to be displayed in the DynamicTable HTC.

Parent Element

dynamictable

Required Child Elements

None.

Optional Child Elements

boolean, date, numeric, select, text, time

Data

None.

Attributes

None.

Remarks

The fields element must contain at least one child element, though in general it will contain several such elements, corresponding to a DynamicTable HTC with several columns.

Child elements within the fields element are displayed as columns in the DynamicTable HTC. The field specified as the key is always displayed as the first column; all other fields are displayed in the order in which they appear within the fields element.

The child elements of the fields element are essentially the same as the elements that can be defined as child elements of the editfield element in the configuration data for the EditField HTC. The primary difference is that sometimes there are some additional attributes that can be defined for the child elements when they occur within the context of the DynamicTable HTC. For information about shared attributes, see Shared EditField Attributes.

Return to XML Structure

boolean

This optional element provides configuration and validation information about a particular column in a DynamicTable HTC containing Boolean values.

Parent Element

fields

Required Child Elements

name

Optional Child Elements

browsetooltip, label

Data

None.

Attributes

Attribute | Description
id, browse, browsereadonly, default, disabled, hide, onbrowse, onchange, onerror, readonly | The id attribute is required. All others are optional. For more information about these attributes, see Shared EditField Attributes.
width | Specifies an initial width for the column corresponding to this element, expressed as a percentage of the total width. Optional. Legal values: Integers between 0 and 100. Default value: Total width divided by the number of displayed columns.

Return to XML Structure

date

This optional element provides configuration and validation information about a particular column in a DynamicTable HTC containing date values.

Parent Element

fields

Required Child Elements

name

Optional Child Elements

browsetooltip, error, format, prompt

Data

None.

Attributes

Attribute | Description
id, browse, browsereadonly, default, disabled, hide, max, min, onbrowse, onchange, onerror, onrequire, onvalid, readonly, required | The id attribute is required. All others are optional. For more information about these attributes, see Shared EditField Attributes.
firstday | Specifies the day of the week that is considered to be the first day of the week. Optional. Legal values: Integers between 0 (Sunday) and 6 (Saturday), inclusive. Default value: 0 (Sunday)
width | Specifies an initial width for the column corresponding to this element, expressed as a percentage of the total width. Optional. Legal values: Integers between 0 and 100. Default value: Total width divided by the number of displayed columns.

Return to XML Structure

numeric

This optional element provides configuration and validation information about a particular column in a DynamicTable HTC containing numeric values.

Parent Element

fields

Required Child Elements

name

Optional Child Elements

browsetooltip, error, format, prompt

Data

None.

Attributes

Attribute | Description
id, browse, browsereadonly, default, disabled, hide, max, min, onbrowse, onchange, onerror, onrequire, onvalid, readonly, required, subtype | The id attribute is required. All others are optional. For more information about these attributes, see Shared EditField Attributes.
width | Specifies an initial width for the column corresponding to this element, expressed as a percentage of the total width. Optional. Legal values: Integers between 0 and 100. Default value: Total width divided by the number of displayed columns.

Return to XML Structure

select

This optional element provides configuration and validation information about a particular column in a DynamicTable HTC containing a fixed set of choices.

Parent Element

fields

Required Child Elements

name, select

Optional Child Elements

browsetooltip, prompt

Data

None.

Attributes

Attribute | Description
id, browse, browsereadonly, default, disabled, hide, onbrowse, onchange, onerror, onvalid, readonly | The id attribute is required. All others are optional. For more information about these attributes, see Shared EditField Attributes.
width | Specifies an initial width for the column corresponding to this element, expressed as a percentage of the total width. Optional. Legal values: Integers between 0 and 100. Default value: Total width divided by the number of displayed columns.

Return to XML Structure

text

This optional element provides configuration and validation information about a particular column in a DynamicTable HTC containing text values.

Parent Element

fields

Required Child Elements

name

Optional Child Elements

browsetooltip, charmask, error, prompt

Data

None.

Attributes

Attribute | Description
id, browse, browsereadonly, default, disabled, hide, maxlen, minlen, onbrowse, onchange, onerror, onrequire, onvalid, readonly, required, subtype | The id attribute is required. All others are optional. For more information about these attributes, see Shared EditField Attributes.
width | Specifies an initial width for the column corresponding to this element, expressed as a percentage of the total width. Optional. Legal values: Integers between 0 and 100. Default value: Total width divided by the number of displayed columns.

Return to XML Structure

time

This optional element provides configuration and validation information about a particular column in a DynamicTable HTC containing time values.

Parent Element

fields

Required Child Elements

name

Optional Child Elements

browsetooltip, error, prompt

Data

None.

Attributes

Attribute | Description
id, browse, browsereadonly, default, disabled, hide, max, min, onbrowse, onchange, onerror, onrequire, onvalid, readonly, required | The id attribute is required. All others are optional. For more information about these attributes, see Shared EditField Attributes.
width | Specifies an initial width for the column corresponding to this element, expressed as a percentage of the total width. Optional. Legal values: Integers between 0 and 100. Default value: Total width divided by the number of displayed columns.

Remarks

The format of fields associated with the time element is fixed. Hours and minutes are displayed in 24-hour format, separated by the colon character (":"). Seconds are not supported.

Return to XML Structure

browsetooltip, charmask, error, format, label, name, prompt, select, option

These nine elements are used to qualify or extend the behavior of one or more of the EditField elements of various data types, embedded within the DynamicTable HTC. For more information, see Shared EditField Child Elements.

Return to XML Structure


EditField Configuration

The XML data-island identified by the MetaXML container attribute contains the configuration information used by one or more EditField HTML components (HTCs).

For more information about how an XML document can be included on a page (creating an XML data-island), see XML Data-Islands.

The structure of this data-island is shown below, with links to more detailed explanations of each element. Element attributes are shown in italic and without the values that are normally associated with them. Required elements and attributes are shown in bold; optional elements and attributes are not in bold.

Note

  • The XML elements and attributes in the MetaXML data-island for the EditField HTC must be expressed in lowercase letters.

XML Structure

<editfield>
  <boolean browse browsereadonly default disabled hide
           id onbrowse onchange onerror readonly
    <browsetooltip>Tooltip for browse button</browsetooltip>
    <label>Checkbox label</label>
  </boolean>
  <date browse browsereadonly default disabled firstday
        hide id max min onbrowse onchange onerror
        onrequire onvalid readonly required
    <browsetooltip>Tooltip for browse button</browsetooltip>
    <error>Validation error message</error>
    <format>Date format to use</format>
    <prompt>Empty control prompt</prompt>
  </date>
  <numeric browse browsereadonly default disabled hide id
           max min onbrowse onchange onerror onrequire
           onvalid readonly required subtype
    <browsetooltip>Tooltip for browse button</browsetooltip>
    <error>Validation error message</error>
    <format>Number format to use</format>
    <prompt>Empty control prompt</prompt>
  </numeric>
  <select browse browsereadonly default disabled hide id
          onbrowse onchange onerror onvalid readonly
    <browsetooltip>Tooltip for browse button</browsetooltip>
    <prompt>Empty control prompt</prompt>
    <select id>
      <option value>Item display name</option>
    </select>
    ...
    <select id>
      <option value>Item display name</option>
    </select>
  </select>
  <text browse browsereadonly default disabled hide id
        maxlen minlen onbrowse onchange onerror
        onrequire onvalid readonly required subtype
    <browsetooltip>Tooltip for browse button</browsetooltip>
    <charmask>Validation character mask</charmask>
    <error>Validation error message</error>
    <prompt>Empty control prompt</name>
  </text>
  <time browse browsereadonly default disabled hide
        id max min onbrowse onchange onerror
        onrequire onvalid readonly required
    <browsetooltip>Tooltip for browse button</browsetooltip>
    <error>Validation error message</error>
    <prompt>Empty control prompt</prompt>
  </time>
</editfield>

editfield

This required element provides a container for the configuration data associated with one or more EditField HTCs. This allows multiple EditField HTCs to share a single XML editfield data-island, accessing different configuration information using distinct id attribute values.

Parent Element

None (document root).

Required Child Elements

None.

Optional Child Elements

boolean, date, numeric, select, text, time

(at least one is required; order not important)

Data

None.

Attributes

None.

Return to XML Structure

boolean

This optional element provides configuration and validation information about an EditField HTC of the Boolean type.

Parent Element

editfield

Required Child Elements

None.

Optional Child Elements

browsetooltip, label

Data

None.

Attributes

Attribute | Description
id, browse, browsereadonly, default, disabled, hide, onbrowse, onchange, onerror, readonly | The id attribute is required. All others are optional. For more information about these attributes, see Shared EditField Attributes.

Return to XML Structure

date

This optional element provides configuration and validation information about an EditField HTC of the Date type.

Parent Element

editfield

Required Child Elements

None.

Optional Child Elements

browsetooltip, error, format, prompt

Data

None.

Attributes

Attribute | Description
id, browse, browsereadonly, default, disabled, hide, max, min, onbrowse, onchange, onerror, onrequire, onvalid, readonly, required | The id attribute is required. All others are optional. For more information about these attributes, see Shared EditField Attributes.
firstday | Specifies the day of the week that is considered to be the first day of the week. Optional. Legal values: Integers between 0 (Sunday) and 6 (Saturday), inclusive. Default value: 0 (Sunday)

Return to XML Structure

numeric

This optional element provides configuration and validation information about an EditField HTC of the Numeric type.

Parent Element

editfield

Required Child Elements

None.

Optional Child Elements

browsetooltip, error, format, prompt

Data

None.

Attributes

Attribute | Description
id, browse, browsereadonly, default, disabled, hide, max, min, onbrowse, onchange, onerror, onrequire, onvalid, readonly, required, subtype | The id attribute is required. All others are optional. For more information about these attributes, see Shared EditField Attributes.

Return to XML Structure

select

This optional element provides configuration and validation information about an EditField HTC of the Select type.

Parent Element

editfield

Required Child Elements

select

Optional Child Elements

browsetooltip, prompt

Data

None.

Attributes

Attribute | Description
id, browse, browsereadonly, default, disabled, hide, onbrowse, onchange, onerror, onvalid, readonly | The id attribute is required. All others are optional. For more information about these attributes, see Shared EditField Attributes.

Return to XML Structure

text

This optional element provides configuration and validation information about an EditField HTC of the Text type.

Parent Element

editfield

Required Child Elements

None.

Optional Child Elements

browsetooltip, charmask, error, prompt

Data

None.

Attributes

Attribute | Description
id, browse, browsereadonly, default, disabled, hide, maxlen, minlen, onbrowse, onchange, onerror, onrequire, onvalid, readonly, required, subtype | The id attribute is required. All others are optional. For more information about these attributes, see Shared EditField Attributes.

Return to XML Structure

time

This optional element provides configuration and validation information about an EditField HTC of the Time type.

Parent Element

editfield

Required Child Elements

None.

Optional Child Elements

browsetooltip, error, prompt

Data

None.

Attributes

Attribute | Description
id, browse, browsereadonly, default, disabled, hide, max, min, onbrowse, onchange, onerror, onrequire, onvalid, readonly, required | The id attribute is required. All others are optional. For more information about these attributes, see Shared EditField Attributes.

Remarks

The format of fields associated with the time element is fixed. Hours and minutes are displayed in a 24-hour format, separated by the colon character (":"). Seconds are not supported.

Return to XML Structure

browsetooltip, charmask, error, format, label, prompt, select, option

These eight elements are used to qualify or extend the behavior of one or more of the EditField elements of various data types. For more information, see Shared EditField Child Elements.

Return to XML Structure


Shared EditField Child Elements

A number of elements specify EditField HTCs of different data types: boolean, date, numeric, select, text, and type. These elements may be present in the configuration information for EditField HTCs themselves. They may also be present in EditField HTCs embedded within the DynamicTable, EditSheet, and ListEditor HTCs. These shared elements include a number of child elements that alter or extend their behavior. The following table lists these child elements, and lists the EditField data types to which they apply.

EditField Child Elements | Relevant EditField Types
browsetooltip | boolean, date, numeric, select, text, type
charmask | text
error | date, numeric, text, type
format | date, numeric
label | boolean
name | boolean, date, numeric, select, text, type Required in the DynamicTable HTC; optional in the EditSheet and ListEditor HTCs; not applicable to the EditField HTC.
option | select Actually a child element of the select child element: <select> <select> <option>
prompt | date, numeric, select, text, type
select | select The option element is a child element of this element.
tooltip | boolean, date, numeric, select, text, type Optional in the EditSheet and ListEditor HTCs; not applicable in the DynamicTable and EditField HTCs.

browsetooltip

This optional element specifies a ToolTip for the browse button associated with an EditField HTC, whether embedded in another HTC or not.

Parent Elements

boolean, date, numeric, select, text, time

(can be a child of any of the element types shown)

Required Child Elements

None.

Optional Child Elements

None.

Data

The tooltip text.

Attributes

None.

Remarks

The browsetooltip element is ignored if a browse button is not specified.

Return to Shared Editfield Child Elements

charmask

This optional element provides a mask of characters, specified in VBScript regular expression syntax, which is used for input validation of text.

Parent Element

text

Required Child Elements

None.

Optional Child Elements

None.

Data

The charmask text, specified in VBScript regular expression syntax.

Attributes

None.

Remarks

The regular expression string provided as the data to the charmask element should be expressed such that valid input matches the regular expression, but that no sub-string of valid input matches the regular expression. One way to accomplish is by surrounding the specified regular expression with the regular expression symbols for the beginning of the expression (^) and the end of the expression ($).

The charmask element being present, but without any data, is treated the same as if it is not present.

If the charmask element is not present, the following default character mask is used for all three subtypes of the text element:

^[^<>&]*$

For more information about regular expressions, see http://msdn.microsoft.com

Return to Shared Editfield Child Elements

error

This optional element specifies an error message to be displayed to the user if data validation for the field fails.

Parent Elements

date, numeric, text, time

(can be a child of any of the element types shown)

Required Child Elements

None.

Optional Child Elements

None.

Data

The error message text.

Attributes

None.

Remarks

The error element is present, but without any data, and is treated the same as if it is not present.

If the error element is not present, the following default error messages are used for the various element types that use error messages.

Elements That Display Errors | Default Error Message
Date | Validation error in date (m/d/yyyy)
Numeric (Integer subtype) | Validation error in number
Numeric (Float subtype) | Validation error in float
Numeric (Currency subtype) | Validation error in currency
Text (all subtypes) | Validation error in text (cannot contain "<", ">", or "&")
Time | Validation error in time (hh:mm – 24hr)

The default error message for dates will show a different format if one is specified using the format element.

Return to Shared Editfield Child Elements

format

This optional element specifies valid input formats for a particular date or numeric EditField HTC, whether embedded in another HTC or not.

Parent Elements

date, numeric

(can be a child of either of the element types shown)

Required Child Elements

None.

Optional Child Elements

None.

Data

The format specification text.

Attributes

None.

Remarks

Valid formats for dates are "m/d/yyyy", "d/m/yyyy", and "yyyy/m/d". The default is "m/d/yyyy". The separator can be specified as any of the following three characters: forward slash ("/"), hyphen ("-"), and period ("."). The default separator is forward slash ("/"). Any number of the characters "m", "d", and "y" may be specified without affecting displayed dates; months and days will never be displayed with leading zeros, and years will always be displayed using four digits.

Valid formats for numbers depend on the subtype of number being displayed: integer, float, or currency. The following table describes valid formats for each.

Numeric Subtype Numeric Formats
integer A string that specifies the manner in which negative values will be indicated (or not), relative to the placement of digits. The negative value indicator can be a leading or trailing hyphen ("-"), or it can be parentheses around the number.

Even though the format is specified as a decimal number, values that are not whole numbers cannot be entered into the HTC when the subtype is "integer".

Examples:

1.1 -1.1 1.1- (1.1)
float A string that specifies the manner in which negative values will be indicated (or not), relative to the placement of digits. The negative value indicator can be a leading or trailing hyphen ("-"), or it can be parentheses around the number.

Examples:

1.1 -1.1 1.1- (1.1)
currency A string that specifies the manner in which negative values will be indicated (or not), relative to the placement of digits. The negative value indicator can be a leading or trailing hyphen ("-"), or it can be parentheses around the number.

No currency symbol should be specified as part of this format.

Examples:

1.1 -1.1 1.1- (1.1)

Return to Shared Editfield Child Elements

label

This optional element provides text to be displayed after the checkbox in a Boolean EditField HTC, whether embedded in another HTC or not.

Parent Element

boolean

Required Child Elements

None.

Optional Child Elements

None.

Data

The check box label text.

Attributes

None.

Remarks

When the label element is absent, the check box will be labeled with the word "Yes" by default.

Return to Shared Editfield Child Elements

name

This element, which is required in some circumstances (see table in Notes), specifies the name associated with an EditField HTC in some situations where it is embedded in another HTC.

Parent Elements

boolean, date, numeric, select, text, time

(can be a child of either of the element types shown)

Required Child Elements

None.

Optional Child Elements

None.

Data

The EditField HTC name.

Attributes

None.

Remarks

The following table shows the situations in which the name element is used, including whether it is required or optional.

HTC with embedded EditFields | Use of the <name> element
DynamicTable | The value of the name element is used as the name of the column associated with the containing element. The name element is required in this situation.
EditSheet | When no template element is specified, the value of the name element is used as the name displayed to the left of the embedded EditField HTC. The name element is optional in this situation. If no name is specified, the field is displayed without a label.
ListEditor | The value of the name element is used as the name displayed to the left of the embedded EditField HTC in the edit area of the ListEditor HTC. The name element is optional in this situation. If no name is specified, the field is displayed without a label.

If the hide attribute of the containing element is set to "yes", the name element is superfluous and need not be present.

Return to Shared Editfield Child Elements

option

This required element specifies the display name and the underlying value for a multiple choice EditField HTC, whether embedded in another HTC or not.

Parent Element

select
(which is itself a child of the higher level select element)

Required Child Elements

None.

Optional Child Elements

None.

Data

The text to be displayed in the selection drop down list.

Attributes

Attribute | Description
value | Specifies the value associated with a particular choice. Required. Legal values: Any. Default value: None. It is up to the author of the XML configuration information to ensure that no two value attribute values for the option elements within the same select element are the same. The Commerce Server Business Desk Framework performs no uniqueness checking in this regard.

Remarks

At least one option element is required, and in general, at least two option elements will be specified.

If an option element is specified with a value attribute set to an empty string, then that option is considered the chosen option when the field is empty.

The select field will display its prompt whenever the current data value does not correspond to the value attribute value of any of the option elements.

Return to Shared Editfield Child Elements

prompt

This optional element provides text to be displayed within an EditField HTC, whether embedded in another HTC or not, when there is no value present. The purpose of such text is to prompt the user for input. Once the user begins entering data, the prompt is replaced by that data.

Parent Elements

date, numeric, select, text, time

(can be a child of either of the element types shown)

Required Child Elements

None.

Optional Child Elements

None.

Data

The prompt text.

Attributes

None.

Remarks

When the prompt element is absent, a default prompt is displayed. To avoid having a prompt displayed, an empty prompt element must be present.

The following table shows the default prompts for the different types of EditField HTCs.

Type of EditField HTC | Default Prompt
boolean | None.
date | <enter date (m/d/yyyy)>.
numeric | <enter number>
select | <select one>
text | <enter text>
time | <enter time (hh:mm)>

The default prompt for dates will show a different format if one is specified using the format element.

Return to Shared Editfield Child Elements

select

This required element contains a set of choices that are available for a multiple choice EditField HTC, whether embedded in another HTC or not. These choices are expressed as a set of option elements.

Parent Element

select
(the higher-level select element )

Required Child Elements

option
(at least one)

Optional Child Elements

None.

Data

None.

Attributes

Attribute | Description
id | Specifies an identifier for this select element. Required, unless there are no sibling select elements. Legal values: Must be unique with respect to the id attributes of any sibling select elements. Default value: None. The value of this attribute can be used as the value of the sID parameter to the reload method of the EditField HTC to dynamically change the set of choices offered to those specified by the child option elements of this select element. (Use the field method of the DynamicTable HTC to retrieve the EditField HTC for which the reload method will be called.)

Remarks

At least one select element is required, but more than one select element may be supplied for situations where the set of choices changes based on some other control setting or circumstance.

Return to Shared Editfield Child Elements

tooltip

This optional element specifies a ToolTip for the left-hand column label, if any, associated with an EditField HTC that is embedded within an EditSheet or ListEditor HTC.

Parent Elements

boolean, date, numeric, select, text, time
(can be a child of either of the element types shown)

Required Child Elements

None.

Optional Child Elements

None.

Data

The ToolTip text.

Attributes

None.

Return to Shared Editfield Child Elements


Shared EditField Attributes

The following table shows the attributes of the various types of EditField elements that are shared.

Attribute
Applicable EditField Types
Description
browse Boolean, Date, Numeric, Select, Text, Time Specifies that a browse button will be available for use with this field.

Optional.

Legal values: "yes" and "no". A value of "yes" specifies that browsing is provided for this field.

Default value: "no".

For more information about the various attributes that work together to control browsing, see EditField.
browsereadonly Boolean, Date, Numeric, Select, Text, Time Specifies whether browsing will be the only way to specify a value for this field.

Optional.

Legal values: "yes" and "no". A value of "yes" specifies that browsing is the only way to provide a value for this field.

Default value: "no".

For more information about the various attributes that work together to control browsing, see EditField.
default Boolean, Date, Numeric, Select, Text, Time Specifies a default value for this field when the data passed to it is an empty string.

Optional.

Legal values: Depend on the type of the field, and are validated in the same way as values passed in as data.

Default value: None.
disabled Boolean, Date, Numeric, Select, Text, Time Specifies whether this field is disabled.

Optional.

Legal values: "yes" and "no". A value of "yes" specifies that this field is disabled.

Default value: "no".
hide Boolean, Date, Numeric, Select, Text, Time Specifies whether display of the field should be suppressed.

Optional.

Legal values: "yes" and "no". A value of "yes" suppresses the display of the field.

Default value: "no".
id Boolean, Date, Numeric, Select, Text, Time Provides an identifier used to associate this field with the corresponding data in the DataXML container attribute.

Required.

Legal values: Must be unique relative to the other id attribute values within the current HTC.

Default value: None.
max Date, Numeric, Time Provides a maximum value that is used when validating field input.

Optional.

Legal values: Must match the specified data format, if any.

Default value: None.
maxlen Text Provides the maximum length of input allowed in a text field, specified in characters.

Optional.

Legal values: Positive integers.

Default value: None.
min Date, Numeric, Time Provides a minimum value that is used when validating field input.

Optional.

Legal values: Must match the specified data format, if any.

Default value: None.
minlen Text Provides the minimum length of input allowed in a text field, specified in characters.

Optional.

Legal values: Positive integers.

Specifying a positive integer as the value of the minlen attribute also forces the field to be required.
onbrowse Boolean, Date, Numeric, Select, Text, Time Specifies the function name of the browse handler.

Optional.

Legal values: Must specify a valid function name.

Default value: None.

If this attribute is set, the browse attribute need not be set.

For more information about the various attributes that work together to control browsing, see EditField.
onchange Boolean, Date, Numeric, Select, Text, Time Specifies the function name of the change handler.

Optional.

Legal values: Must specify a valid function name.

Default value: None.
onerror Boolean, Date, Numeric, Select, Text, Time Specifies the function name of the error handler.

Optional.

Legal values: Must specify a valid function name.

Default value: None.
onrequire Date, Numeric, Text, Time Specifies the function name of the require handler.

Optional.

Legal values: Must specify a valid function name.

Default value: None.
onvalid Date, Numeric, Select, Text, Time Specifies the function name of the valid handler.

Optional.

Legal values: Must specify a valid function name.

Default value: None.
readonly Boolean, Date, Numeric, Select, Text, Time Specifies whether this field is read-only.

Optional.

Legal values: "yes" and "no". A value of "yes" prevents the field value from being changed.

Default value: "no".
required Date, Numeric, Text, Time Specifies whether data must be supplied for this field.

Optional.

Legal values: "yes" and "no". A value of "yes" specifies that data must be supplied.

Default value: "no".
subtype Numeric, Text Specifies further refinement of the data type specified by the element containing this attribute.

Optional.

Legal values:

numeric: "integer", "float", "currency"

text: "short", "long", "password"

Default value:

numeric: "integer"

text: "short"


EditSheet Configuration

The XML data-island identified by the MetaXML container attribute contains the configuration information used by the EditSheet HTML component (HTC).

For more information about how an XML document can be included on a page (creating an XML data-island), see XML Data-Islands.

The structure of this data-island is shown below, with links to more detailed explanations of each element. Element attributes are shown in italic and without the values that are normally associated with them. Required elements and attributes are shown in bold; optional elements and attributes are not in bold.

Note

  • The XML elements and attributes in the MetaXML data-island for the EditSheet HTC must be expressed in lowercase letters.

XML Structure

<editsheets>
  <editsheet>
    <global expanded title>
      <name>Editsheet name goes here<name>
      <key>Access key for editsheet goes here</key>
    </global>
    <template fields register>
      <![CDATA[
        HTML template goes here
      ]]>
    </template>
    <fields>
      <boolean browse browsereadonly default disabled hide
               id onbrowse onchange onerror readonly
        <browsetooltip>Tooltip for browse button</browsetooltip>
        <name>Name of field in left-hand column</name>
        <label>Checkbox label</label>
        <tooltip>Tooltip for left-hand column label</tooltip>
      </boolean>
      <date browse browsereadonly default disabled firstday
            hide id max min onbrowse onchange onerror
            onrequire onvalid readonly required
        <browsetooltip>Tooltip for browse button</browsetooltip>
        <format>Date format to use</format>
        <error>Name of field in left-hand column</error>
        <name>Column heading name</name>
        <prompt>Empty control prompt</prompt>
        <tooltip>Tooltip for left-hand column label</tooltip>
      </date>
      <numeric browse browsereadonly default disabled hide id
               max min onbrowse onchange onerror onrequire
               onvalid readonly required subtype
        <browsetooltip>Tooltip for browse button</browsetooltip>
        <format>Number format to use</format>
        <error>Validation error message</error>
        <name>Name of field in left-hand column</name>
        <prompt>Empty control prompt</prompt>
        <tooltip>Tooltip for left-hand column label</tooltip>
      </numeric>
      <select browse browsereadonly default disabled hide id
              onbrowse onchange onerror onvalid readonly
        <browsetooltip>Tooltip for browse button</browsetooltip>
        <name>Name of field in left-hand column</name>
        <prompt>Empty control prompt</prompt>
        <tooltip>Tooltip for left-hand column label</tooltip>
        <select id>
          <option value>Item display name</option>
        </select>
        ...
        <select id>
          <option value>Item display name</option>
        </select>
      </select>
      <text browse browsereadonly default disabled hide id
            maxlen minlen onbrowse onchange onerror onrequire
            onvalid readonly required subtype
        <browsetooltip>Tooltip for browse button</browsetooltip>
        <charmask>Validation character mask</charmask>
        <error>Validation error message</error>
        <name>Name of field in left-hand column</name>
        <prompt>Empty control prompt</prompt>
        <tooltip>Tooltip for left-hand column label</tooltip>
      </text>
      <time browse browsereadonly default disabled hide
            id max min onbrowse onchange onerror
            onrequire onvalid readonly required
        <browsetooltip>Tooltip for browse button</browsetooltip>
        <error>Validation error message</error>
        <name>Name of field in left-hand column</name>
        <prompt>Empty control prompt</prompt>
        <tooltip>Tooltip for left-hand column label</tooltip>
      </time>
    </fields>
  </editsheet>
  <editsheet>
    another editsheet specification goes here
  </editsheet>
</editsheets>

editsheets

This optional element is used to contain multiple editsheet elements, if present. Otherwise a single editsheet element is used.

Parent Element

None (document root).

Required Child Elements

editsheet

(at least one is required, but normally two or more are present)

Optional Child Elements

None.

Data

None.

Attributes

None.

Return to XML Structure

editsheet

This required element contains the configuration information for a single EditSheet HTC.

Parent Elements

None (document root), editsheets
(can be one or the other)

Required Child Elements

global, fields

Optional Child Elements

template

Data

None.

Attributes

None.

Remarks

It can be used as the sole child of the XML data-island when a single EditSheet HTC is being used, or can occur within the editsheets element when configured as one of several EditSheet HTCs.

For more information about how an XML document can be included on a page (creating an XML data-island) see XML Data-Islands.

Return to XML Structure

global

This required element specifies global information about the display of an EditSheet HTC.

Parent Element

editsheet

Required Child Elements

name, key

(Required in some circumstances)

Optional Child Elements

name, key

(Optional in some circumstances)

Data

None.

Attributes

Attribute | Description
expanded | Specifies whether the EditSheet HTC is initially displayed as open or closed. Optional. Legal values: "yes" and "no". A value of "yes" causes the EditSheet HTC to initially display as open. Default value: "no". The value of this attribute is irrelevant if the title attribute is set to "no".
title | Controls whether the EditSheet HTC is shown with a title bar containing the expand/collapse control and its name. Optional. Legal values: "yes" and "no". A value of "no" suppresses the display of the title bar. Default value: "yes". If the title attribute is set to "no", then the expanded attribute is automatically set to "yes". Also, if the title attribute is set to "no", then the name and key (sub) elements need not be specified.

Return to XML Structure

name

This element, which is required in some circumstances, provides the name of the EditSheet HTC.

Parent Element

global

Required Child Elements

None.

Optional Child Elements

None.

Data

The name of the editsheet.

Attributes

None.

Remarks

This name is sometimes called the group name.

This name is typically displayed in the title bar. This behavior can be suppressed by setting the title attribute to "no"; in this case this element is not required. If the title attribute of the containing global element is not set to "no", this element is required.

If the specific EditSheet name contains any HTML formatting directives, proper escaping must be used. For example, the string &lt; must be used for the "<" character, the string &gt; must be used for the ">" character, and the string &amp; must be used for the "&" character.

Return to XML Structure

key

This element, which is required in some circumstances, specifies a character that serves as the accessibility key associated with the EditSheet HTC.

Parent Element

global

Required Child Elements

None.

Optional Child Elements

None.

Data

The accessibility key, as indicated in the editsheet name with underlining.

Attributes

None.

Remarks

If the title attribute of the containing global element is not set to "no", this element is required.

The accessibility key for the EditSheet HTC must specify the same character identified with underlining in the EditSheet name, if any.

For example, if the EditSheet name is specified such that the user sees the string "Department", the character "d" must appear between the <key> and </key> tags.

Return to XML Structure

template

This optional element contains an HTML template for the EditSheet HTC that can contain sub-instances of Commerce Server Business Desk HTCs within it, often EditSheet and EditField HTCs.

Parent Element

editsheet

Required Child Elements

None.

Optional Child Elements

None.

Data

An HTML template expressed as character data (CDATA).

Attributes

Attribute | Description
fields | Specifies a space-delimited list of the IDs of any contained EditField HTCs that should be loaded using the same data and meta-data as the parent EditSheet HTC. Optional. Legal values: Valid IDs of contained EditField HTCs, separated by spaces. Default value: None. When the EditSheet HTC creates the template, it will attach the correct behavior for those EditField HTCs and also enable their OnChange, OnValid, and OnRequire events to be passed to the outer EditSheet HTC. These EditField HTCs should not have the CLASS attribute value "EditField" set on their DIV element.
register | Specifies a space-delimited list of the IDs of any contained HTCs that should have their OnChange, OnValid, and OnRequire events passed to the outer EditSheet HTC. Optional. Legal values: Valid IDs of contained HTCs, separated by spaces. Default value: None. Standard HTML input elements can also be registered so that their OnChange events will be passed to the outer EditSheet HTC. However, it is important to remember that HTML radio and check box type input elements do not fire the OnChange event.

Remarks

The register attribute is used to allow OnChange and OnRequire events generated by these sub-controls to be passed to the outer EditSheet HTC.

The fields attribute is used to create EditField HTCs for elements within the template without requiring that the EditField HTCs load their own meta-data.

Passing the OnRequire event to the outer EditSheet HTC allows the icon indicating required data to be displayed for templated sub-controls.

Passing the OnValid event to the outer EditSheet HTC allows the icon that indicates data is not valid to be displayed for templated sub-controls.

Passing the OnChange event to the outer EditSheet HTC allows proper tracking of whether changes have been made.

The following example illustrates how to create a template that contains an EditSheet HTC, an EditField HTC, and a check box as sub-controls. Note how the IDs of the EditSheet and EditField HTCs are specified in the fields and register attributes of the template element:

  <template fields="esSubControl2" register="esSubControl1">
    <![CDATA[
      <DIV ID='esSubControl1'
           CLASS='editSheet'
           MetaXML='esMeta1'
           DataXML='esData'>
        <H3 ALIGN="center">Loading Property Group...</H3>
      </DIV>
      <B>File Name 5:</B>
      <DIV ID='esSubControl2'
           STYLE='WIDTH:300px'
           MetaXML='esMeta1'
           DataXML='esData'>
        <H3 ALIGN="center">Loading Property...</H3>
      </DIV>
      <INPUT type="checkbox" id=checkbox1 name=checkbox1>
      <LABEL FOR=checkbox1>additional HTML controls</LABEL>
    ]]>
  </template>

Return to XML Structure

fields

This required element contains the elements that specify the fields to be displayed in the EditSheet HTC.

Parent Element

editsheet

Required Child Elements

None.

Optional Child Elements

boolean, date, numeric, select, text, time

Data

None.

Attributes

None.

Remarks

When the template element is not present, elements defined within the fields element are displayed as rows in the EditSheet HTC, in the order in which they appear within the fields element. For example, the first element defines the top row and the last element defines the bottom row.

The child elements of the fields element are essentially the same as the elements that can be defined as child elements of the editfield element in the configuration data for the EditField HTC. The primary difference is that child elements of the fields element in the EditSheet HTC can include additional child elements, namely the name and tooltip elements. For information about shared attributes, see Shared EditField Attributes.

Return to XML Structure

boolean

This optional element provides configuration and validation information about a particular field in an EditSheet HTC containing a Boolean value.

Parent Element

fields

Required Child Elements

None.

Optional Child Elements

browsetooltip, label, name, tooltip

Data

None.

Attributes

Attribute | Description
id, browse, browsereadonly, default, disabled, hide, onbrowse, onchange, onerror, readonly | The id attribute is required. All others are optional. For more information about these attributes, see Shared EditField Attributes.

Return to XML Structure

date

This optional element provides configuration and validation information about a particular field in an EditSheet HTC containing a date value.

Parent Element

fields

Required Child Elements

None.

Optional Child Elements

browsetooltip, error, format, name, prompt, tooltip

Data

None.

Attributes

Attribute | Description
id, browse, browsereadonly, default, disabled, hide, max, min, onbrowse, onchange, onerror, onrequire, onvalid, readonly, required | The id attribute is required. All others are optional. For more information about these attributes, see Shared EditField Attributes.
firstday | Specifies the day of the week that is considered to be the first day of the week. Optional. Legal values: Integers between 0 (Sunday) and 6 (Saturday), inclusive. Default value: 0 (Sunday)

Return to XML Structure

numeric

This optional element provides configuration and validation information about a particular field in an EditSheet HTC containing a numeric value.

Parent Element

fields

Required Child Elements

None.

Optional Child Elements

browsetooltip, error, format, name, prompt, tooltip

Data

None.

Attributes

Attribute | Description
id, browse, browsereadonly, default, disabled, hide, max, min, onbrowse, onchange, onerror, onrequire, onvalid, readonly, required, subtype | The id attribute is required. All others are optional. For more information about these attributes, see Shared EditField Attributes.

Return to XML Structure

select

This optional element provides configuration and validation information about a particular field in an EditSheet HTC containing a fixed set of choices.

Parent Element

fields

Required Child Elements

select (at least one, but generally two or more)

Optional Child Elements

browsetooltip, name, prompt, tooltip

Data

None.

Attributes

Attribute | Description
id, browse, browsereadonly, default, disabled, hide, onbrowse, onchange, onerror, onvalid, readonly | The id attribute is required. All others are optional. For more information about these attributes, see Shared EditField Attributes.

Return to XML Structure

text

This optional element provides configuration and validation information about a particular field in an EditSheet HTC containing a text value.

Parent Element

fields

Required Child Elements

name

Optional Child Elements

browsetooltip, charmask, error, prompt, tooltip

Data

None.

Attributes

Attribute | Description
id, browse, browsereadonly, default, disabled, hide, maxlen, minlen, onbrowse, onchange, onerror, onrequire, onvalid, readonly, required, subtype | The id attribute is required. All others are optional. For more information about these attributes, see Shared EditField Attributes.

Return to XML Structure

time

This optional element provides configuration and validation information about a particular field in an EditSheet HTC containing a time value.

Parent Element

fields

Required Child Elements

None.

Optional Child Elements

browsetooltip, error, name, prompt, tooltip

Data

None.

Attributes

Attribute | Description
id, browse, browsereadonly, default, disabled, hide, max, min, onbrowse, onchange, onerror, onrequire, onvalid, readonly, required | The id attribute is required. All others are optional. For more information about these attributes, see Shared EditField Attributes.

Remarks

The format of fields associated with the time element is fixed. Hours and minutes are displayed in a 24-hour format, separated by the colon character (":"). Seconds are not supported.

Return to XML Structure

browsetooltip, charmask, error, format, label, name, option, prompt, select, tooltip

These ten elements are used to qualify or extend the behavior of one or more of the EditField elements of various data types, embedded within the EditSheet HTC. For more information, see Shared EditField Child Elements.

Return to XML Structure


ExpressionBuilder Configuration

The XML data-island identified by the XMLCfgID container attribute contains the configuration information used by the ExpressionBuilder HTML component (HTC).

For more information about the ways in which an XML document can be included on a page (creating an XML data-island), see XML Data-Islands.

The ExpressionBuilder HTC includes an embedded QueryBuilder HTC. Because of this, a number of the configuration elements passed to the ExpressionBuilder HTC are actually used by the embedded QueryBuilder HTC. Each of the elements discussed in this topic will be identified as being used to configure the ExpressionBuilder HTC, the embedded QueryBuilder HTC, or both.

The structure of this data-island is shown below, with links to more detailed explanations of each element. Element attributes are shown in italic and without the values that are normally associated with them. Required elements and attributes are shown in bold; optional elements and attributes are not in bold.

Note

  • The XML elements and attributes in the MetaXML data-island for the ExpressionBuilder HTC must be expressed in uppercase letters.

XML Structure

<EBCONFIG>
  <EXPR-ASP>relative URL of exprarch folder</EXPR-ASP>
  <PROFILE-LIST>
    <PROFILE>profile name</PROFILE>
    <PROFILE SRC />
  </PROFILE-LIST>
  <SITE-TERMS URL NOLOAD />
  <EEE-INTRINSICS />
  <DEBUG />
  <RENAME>no</RENAME>
  <HIDEBUTTONS />
  <TYPESOPS>path to xml file</TYPEOPS>
  <MESSAGE>alternate message</MESSAGE>
  <FILTER-CATEGORIES>
    <CATEGORY>category name</CATEGORY>
  </FILTER-CATEGORIES>
  <SAVE-CATEGORY>save category name</SAVE-CATEGORY>
  <EDIT-NESTED>always, warn, or never</EDIT-NESTED>
  <DATE-FORMAT>date format</DATE-FORMAT>
  <DATE-FIRSTDAY>first day of week</DATE-FIRSTDAY>
  <NUMBER-FORMAT>number format</NUMBER-FORMAT>
  <CURRENCY-FORMAT>currency format</CURRENCY-FORMAT>
  <HELPTOPIC>help topic URL</HELPTOPIC>
  <ADVANCED />
  <FILTER-PROPERTIES>XSL expression</FILTER-PROPERTIES>
</EBCONFIG>

EBCONFIG

This required element contains the configuration information for an instance of the ExpressionBuilder HTC.

Parent Elements

None (document root)

Required Child Elements

EXPR-ASP, PROFILE-LIST

Optional Child Elements

ADVANCED, CURRENCY-FORMAT, DATE-FIRSTDAY, DATE-FORMAT, DEBUG, EDIT-NESTED, EEE-INTRINSICS, FILTER-CATEGORIES, FILTER-PROPERTIES, HELPTOPIC, HIDEBUTTONS, MESSAGE, NUMBER-FORMAT, RENAME, SAVE-CATEGORY, SITE-TERMS, TYPESOPS

Data

None.

Attributes

None.

Remarks

The EBCONFIG element is used by both the ExpressionBuilder HTC and the embedded QueryBuilder HTC.

Return to XML Structure

EXPR-ASP

This required element specifies the relative URL of the Exprarch folder, which is required for the proper functioning of the ExpressionBuilder HTC.

Parent Elements

EBCONFIG

Required Child Elements

None.

Optional Child Elements

None.

Data

The relative URL of the Exprarch folder.

Attributes

None.

Remarks

The EBCONFIG element is used by both the ExpressionBuilder HTC and the embedded QueryBuilder HTC.

Return to XML Structure

PROFILE-LIST

This required element contains the specifications of the various profiles used by this instance of the ExpressionBuilder HTC.

Parent Elements

EBCONFIG

Required Child Elements

PROFILE (at least one is required)

Optional Child Elements

None.

Data

None.

Attributes

None.

Remarks

The PROFILE-LIST element is only used by the embedded QueryBuilder HTC.

Return to XML Structure

PROFILE

This required element specifies a profile in one of two ways. For Profile Definitions defined within Commerce Server, the name of the profile is specified as data associated with the element. For profiles not defined within Commerce Server, the URL of a valid XML document containing one or more profiles is specified as the value of the SRC attribute.

Parent Element

PROFILE-LIST

Required Child Elements

None.

Optional Child Elements

None.

Data

When the SRC attribute is not present, the name of the profile is specified as data within the PROFILE element. Otherwise, no data is present.

Attributes

Attribute | Description
SRC | Provides the URL of a valid XML document that contains one or more profiles not defined within Commerce Server. Optional. Legal values: A valid URL. Default value: None. When this attribute is specified, the PROFILE element should not contain any data.

REMARKS

When the name of a Profile Definition defined within Commerce Server is specified as data for this element, the name must be of the form "CatalogName.ProfileName". For example, "UserProfiles.UserObject".

When a profile not defined within Commerce Server is specified using the SRC attribute, it must conform to a defined XML structure for profile specification. For more information about this structure, see Specifying Profiles and Site Terms in the QueryBuilder HTC.

The PROFILE element is only used by the embedded QueryBuilder HTC.

Return to XML Structure

SITE-TERMS

This optional element specifies alternate information about whether the ExpressionBuilder HTC should load site-terms, and, if so, from where.

Parent Element

EBCONFIG

Required Child Elements

None.

Optional Child Elements

None.

Data

None.

Attributes

Attribute | Description
NOLOAD | Suppresses the loading of site-terms for this instance of the ExpressionBuilder HTC (when set to "1"). Optional. Legal values: "1". Default value: None. If site-term loading is suppressed and expression bodies containing site-terms are passed to the ExpressionBuilder HTC, errors will result. This attribute should not be specified in combination with the URL attribute.
URL | Provides the URL of a valid XML document that contains alternate site-terms for use in this instance of the ExpressionBuilder HTC. Optional. Legal values: A valid URL. Default value: None. This attribute should not be specified in combination with the NOLOAD attribute.

REMARKS

When the SITE-TERMS element is present, either the NOLOAD attribute or the URL attribute (but not both) must be specified.

When the SITE-TERMS element is not present, site terms are loaded from the same folder specified by the required EXPR-ASP element.

When an alternate set of site terms is specified using the URL attribute, it must conform to the defined XML structure for site term specification. For more information about this structure, see Specifying Profiles and Site Terms in the QueryBuilder HTC.

The SITE-TERMS element is used only by the embedded QueryBuilder HTC.

Return to XML Structure

EEE-INTRINSICS

This optional element, when present, causes the ExpressionBuilder HTC to expose the intrinsic properties of the Expression Evaluator as a profile in its drop-down menus.

Parent Elements

EBCONFIG

Required Child Elements

None.

Optional Child Elements

None.

Data

None.

Attributes

None.

Remarks

The EEE-INTRINSICS element is only used by the embedded QueryBuilder HTC.

Return to XML Structure

DEBUG

This optional element, when present, causes the ExpressionBuilder HTC to display debugging information.

Parent Elements

EBCONFIG

Required Child Elements

None.

Optional Child Elements

None.

Data

None.

Attributes

None.

Remarks

The DEBUG element is used by both the ExpressionBuilder HTC and the embedded QueryBuilder HTC.

Return to XML Structure

RENAME

This optional element controls whether the ExpressionBuilder HTC will allow the renaming of expressions during editing.

Parent Elements

EBCONFIG

Required Child Elements

None.

Optional Child Elements

None.

Data

Typically, the string "no".

Attributes

None.

Remarks

If the string "no" appears as data associated with this element, renaming of expressions is not allowed. Given any other data string, or the absence of the RENAME element, renaming is allowed.

If the ExpressionBuilder HTC is activated in either the create or the createfrom mode, the RENAME element is ignored and renaming is always allowed.

The RENAME element is only used by the ExpressionBuilder HTC.

Return to XML Structure

HIDEBUTTONS

This optional element, when present, causes the ExpressionBuilder HTC to hide the Save, Cancel, and Help buttons.

Parent Elements

EBCONFIG

Required Child Elements

None.

Optional Child Elements

None.

Data

None.

Attributes

None.

Remarks

  • The HIDEBUTTONS element is only used by the ExpressionBuilder HTC.

Return to XML Structure

TYPESOPS

This optional element, when present, specifies a types and operators XML file for the ExpressionBuilder HTC to use.

Parent Elements

EBCONFIG

Required Child Elements

None.

Optional Child Elements

None.

Data

The relative path to the XML types and operators file.

Attributes

None.

Remarks

If this element is not specified, the default types and operators file is /Widgets/ExprbldrHTC/TypesOpsA.xml.

The TYPESOPS element is only used by the embedded QueryBuilder HTC.

Return to XML Structure

MESSAGE

This optional element, when present, specifies an alternate message to be displayed above the expression-selector area.

Parent Elements

EBCONFIG

Required Child Elements

None.

Optional Child Elements

None.

Data

The alternate message.

Attributes

None.

Remarks

When the MESSAGE element is not present, the default message is "Target according to the following conditions".

The MESSAGE element is only used by the embedded QueryBuilder HTC.

Return to XML Structure

FILTER-CATEGORIES

This optional element, when present, contains a list of expression categories. When the ExpressionBuilder HTC builds a list of expressions that can be used to create new expressions, and the FILTER-CATEGORIES element has been specified, only expressions belonging to a specified category are included in the expression list. If the FILTER-CATEGORIES element is not present, all expressions are included in the expression list.

Parent Elements

EBCONFIG

Required Child Elements

None.

Optional Child Elements

category (typically at least one is present)

Data

None.

Attributes

None.

Remarks

If there are no CATEGORY elements contained in the FILTER-CATEGORIES element, it is treated as though the latter element is not present.

The FILTER-CATEGORIES element is only used by the ExpressionBuilder HTC.

Return to XML Structure

CATEGORY

This optional element is used to specify a category of expressions to be included in the expression list presented by the ExpressionBuilder HTC. Multiple CATEGORY elements can be used to specify that multiple expression categories be presented.

Parent Elements

FILTER-CATEGORY

Required Child Elements

None.

Optional Child Elements

None.

Data

The expression category name.

Attributes

None.

Remarks

In general, at least one CATEGORY element will be present when the FILTER-CATEGORIES element is present. When all categories are to be included, the FILTER-CATEGORIES element may or may not be present.

The CATEGORY element is only used by the ExpressionBuilder HTC.

Return to XML Structure

SAVE-CATEGORY

This optional element, when present, specifies the category in which this expression will be saved.

Parent Elements

EBCONFIG

Required Child Elements

None.

Optional Child Elements

None.

Data

The name of expression category with which the current expression will be associated when it is saved.

Attributes

None.

Remarks

When the SAVE-CATEGORY element is specified, the value specified as data for this element takes precedence over any previous category associated with the expression.

If the SAVE-CATEGORY element is not specified, the expression will not be associated with any category, regardless of any previous association.

The SAVE-CATEGORY element is only used by the ExpressionBuilder HTC.

Return to XML Structure

EDIT-NESTED

This optional element, when present, specifies whether editing of nested expressions is allowed or prevented, or allowed only if the user explicitly allows it in response to a warning dialog box.

Parent Elements

EBCONFIG

Required Child Elements

None.

Optional Child Elements

None.

Data

One of the three values "always", "warn", or "never". See Remarks for more details.

Attributes

None.

Remarks

Specifying "always" results in the nested expression being opened in edit mode. In general, this is not recommended.

Specifying "warn" results in a warning dialog box that offers the choice between opening the nested expression in edit mode or view mode.

Specifying "never" results in the nested expression being opened in view mode.

The default behavior, in the event that the EDIT-NESTED element is not present or contains an illegal data value, is to not allow the editing of nested expressions.

The EDIT-NESTED is only relevant when an expression is being created or edited.

The EDIT-NESTED element is only used by the embedded QueryBuilder HTC.

Return to XML Structure

DATE-FORMAT

This optional element, when present, specifies the display format for dates.

Parent Elements

EBCONFIG

Required Child Elements

None.

Optional Child Elements

None.

Data

The display format for dates.

Attributes

None.

Remarks

Valid formats for dates are "m/d/yyyy", "d/m/yyyy", and "yyyy/m/d". The default is "m/d/yyyy". The separator can be specified as any of the following three characters: forward slash ("/"), hyphen ("-"), and period ("."). The default separator is forward slash ("/"). Any number of the characters "m", "d", and "y" may be specified without affecting displayed dates; months and days will always be displayed without a leading zero, and years will always be displayed using 4 digits.

The DATE-FORMAT element is only used by the embedded QueryBuilder HTC.

Return to XML Structure

DATE-FIRSTDAY

This optional element, when present, specifies the day of the week that will be considered the first day of the week.

Parent Elements

EBCONFIG

Required Child Elements

None.

Optional Child Elements

None.

Data

A number in the range 0 (Sunday) to 6 (Saturday).

Attributes

None.

Remarks

Days of the week are represented by numbers between 0 and 6, as follows: 0 = Sunday; 1 = Monday; 2 = Tuesday, 3 = Wednesday; 4 = Thursday; 5 = Friday, and 6 = Saturday.

If this element is not present, the default first day of the week is Sunday.

The DATE-FIRSTDAY element is only used by the embedded QueryBuilder HTC.

Return to XML Structure

NUMBER-FORMAT

This optional element, when present, specifies the display format for numbers.

Parent Elements

EBCONFIG

Required Child Elements

None.

Optional Child Elements

None.

Data

The display format for numbers.

Attributes

None.

Remarks

Valid formats for numbers are specified using a string that indicates the manner in which negative values will be indicated (or not), relative to the placement of digits. The negative value indicator can be a leading or trailing hyphen ("-"), space-separated from the number or not, or it can be parentheses around the number.

If this element is not present, the default format is "–1.1".

Examples:

1.1 -1.1 1.1- (1.1)

The NUMBER-FORMAT element is only used by the embedded QueryBuilder HTC.

Return to XML Structure

CURRENCY-FORMAT

This optional element, when present, specifies the display format for currency.

Parent Elements

EBCONFIG

Required Child Elements

None.

Optional Child Elements

None.

Data

The display format for currency.

Attributes

None.

Remarks

Valid formats for currency are specified using a string that indicates the manner in which negative values will be indicated (or not), relative to the placement of digits. The negative value indicator can be a leading or trailing hyphen ("-"), space-separated from the number or not, or it can be parentheses around the number.

If this element is not present, the default format is "–1.1".

No currency symbol should be specified as part of this format.

Examples:

1.1 -1.1 1.1- (1.1)

The CURRENCY-FORMAT element is only used by the embedded QueryBuilder HTC.

Return to XML Structure

HELPTOPIC

This optional element, when present, specifies a help topic for this instance of the QueryBuilder HTC.

Parent Elements

EBCONFIG

Required Child Elements

None.

Optional Child Elements

None.

Data

The absolute URL of the corresponding help topic.

Attributes

None.

Remarks

If this element is present, the QueryBuilder HTC will display a help button, which when clicked will display the specified help topic.

Use the server-side utility routine sRelURL2AbsURL to generate the absolute URL required by this element. For example:

<HELPTOPIC><%=sRelURL2AbsURL("../docs/htm/yourhelpfile.htm")%></HELPTOPIC>

The HELPTOPIC element is only used by the embedded QueryBuilder HTC.

Return to XML Structure

ADVANCED

This optional element, when present, specifies that advanced editing will be allowed. Advanced editing allows the use of the OR operator in expressions.

Parent Elements

EBCONFIG

Required Child Elements

None.

Optional Child Elements

None.

Data

None.

Attributes

None.

Remarks

If this element is not present, advanced editing is not allowed.

The ADVANCED element is only used by the embedded QueryBuilder HTC.

Return to XML Structure

FILTER-PROPERTIES

This optional element, when present, specifies an Extensible Stylesheet Language (XSL) pattern fragment used for filtering properties from the profile. If this element is present, the provided XSL pattern will be applied to the properties in each profile that is loaded. Any properties that do not conform to the XSL pattern will not be shown when creating or editing expressions.

Parent Elements

EBCONFIG

Required Child Elements

None.

Optional Child Elements

None.

Data

The XSL pattern fragment.

Attributes

None.

Remarks

The default XSL pattern fragment is: not(@isActive) || @isActive != '0'

The data values supplied for this element are actually XSL pattern fragments because they are surrounded by the strings "Property[" and "]" to achieve the actual XSL pattern. For example, the actual default XSL pattern, shown with the added strings in bold, is as follows:

Property[not(@isActive) || @isActive != '0']

Element attributes return "0" when they are not defined. Therefore, it is recommended the XSL pattern fragments specified as data for this element check for the presence of an attribute as well as for the attribute value being set to zero. The default XSL pattern is an example of both of these conditions being checked.

The FILTER-PROPERTIES element is only used by the embedded QueryBuilder HTC.

Return to XML Structure


ListEditor Configuration

The XML data-island identified by the MetaXML container attribute contains the configuration information used by the ListEditor HTML component (HTC).

For more information about the ways in which an XML document can be included on a page (creating an XML data-island), see XML Data-Islands.

The structure of this data-island is shown below, with links to more detailed explanations of each element. Element attributes are shown in italic and without the values that are normally associated with them. Required elements and attributes are shown in bold; optional elements and attributes are not bolded.

Note

  • The XML elements and attributes in the MetaXML data-island for the ListEditor HTC must be expressed in lowercase letters.

XML Structure

<listeditor>
  <columns>
    <column format hide id width>Column name</column>
  </columns>
  <fields>
    <boolean browse browsereadonly default disabled hide
             id onbrowse onchange onerror readonly
      <browsetooltip>Tooltip for browse button</browsetooltip>
      <name>Name of field in left-hand column</name>
      <label>Checkbox label</label>
      <tooltip>Tooltip for the left-hand column label</tooltip>
    </boolean>
    <date browse browsereadonly default disabled firstday
          hide id max min onbrowse onchange onerror
          onrequire onvalid readonly required
      <browsetooltip>Tooltip for browse button</browsetooltip>
      <format>Date format to use</format>
      <error>Name of field in left-hand column</error>
      <name>Column heading name</name>
      <prompt>Empty control prompt</prompt>
      <tooltip>Tooltip for the left-hand column label</tooltip>
    </date>
    <numeric browse browsereadonly default disabled hide id
             max min onbrowse onchange onerror onrequire
             onvalid readonly required subtype
      <browsetooltip>Tooltip for browse button</browsetooltip>
      <format>Number format to use</format>
      <error>Validation error message</error>
      <name>Name of field in left-hand column</name>
      <prompt>Empty control prompt</prompt>
      <tooltip>Tooltip for the left-hand column label</tooltip>
    </numeric>
    <select browse browsereadonly default disabled hide id
            onbrowse onchange onerror onvalid readonly
      <browsetooltip>Tooltip for browse button</browsetooltip>
      <name>Name of field in left-hand column</name>
      <prompt>Empty control prompt</prompt>
      <tooltip>Tooltip for the left-hand column label</tooltip>
      <select id>
        <option value>Item display name</option>
      </select>
      ...
      <select id>
        <option value>Item display name</option>
      </select>
    </select>
    <text browse browsereadonly default disabled hide id
          maxlen minlen onbrowse onchange onerror onrequire
          onvalid readonly required subtype
      <browsetooltip>Tooltip for browse button</browsetooltip>
      <charmask>Validation character mask</charmask>
      <error>Validation error message</error>
      <name>Name of field in left-hand column</name>
      <prompt>Empty control prompt</prompt>
      <tooltip>Tooltip for the left-hand column label</tooltip>
    </text>
    <time browse browsereadonly default disabled hide
          id max min onbrowse onchange onerror
          onrequire onvalid readonly required
      <browsetooltip>Tooltip for browse button</browsetooltip>
      <error>Validation error message</error>
      <name>Name of field in left-hand column</name>
      <prompt>Empty control prompt</prompt>
      <tooltip>Tooltip for the left-hand column label</tooltip>
    </time>
  </fields>
</listeditor>

listeditor

This required element contains the configuration information for a ListEditor HTC.

Parent Element

None (document root).

Required Child Elements

columns, fields

Optional Child Elements

None.

Data

None.

Attributes

None.

Return to XML Structure

columns

This required element contains the descriptions of the various columns that the ListEditor HTC displays in the list area.

Parent Element

listeditor

Required Child Elements

column

(at least one is required, but normally two or more are present)

Optional Child Elements

None.

Data

None.

Attributes

None.

Return to XML Structure

column

This required element provides configuration information about a particular column in the list area of a ListEditor HTC.

Parent Element

columns

Required Child Elements

None.

Optional Child Elements

None.

Data

The name of the column as the user sees it.

Attributes

Attribute Description
format Specifies how the data in this column should be formatted.

Optional.

Legal values: "select", "password", and "float". See below for additional details.

Default value: None.

When the format attribute is set to "select", the embedded ListSheet HTC will look for a select element in the meta-data corresponding to the id attribute and look up the display value to display for the value in the column.

When the format attribute is set to "password", the value will be masked just like in a password type HTML element.

When the format attribute is set to "float", the value will be normalized. For example, "2.00" displays as "2".
hide Specifies whether this column should be displayed.

Optional.

Legal values: "yes" and "no". If the value is "yes", the column is not displayed.

Default value: "no".
id Provides an identifier used to associate this column with the corresponding data in the DataXML container attribute.

Required.

The value of this attribute may or may not correspond to the value of the id attribute for one of the field elements.
width Specifies an initial width for the column corresponding to this element.

Optional.

Legal values: Integers between 0 and 100, representing column width as a percentage of control width. The specified widths of all columns are normalized if they do not add up to 100.

Default value: If a width is not specified, the width percentage is calculated as the total width divided by the number of displayed columns.

Remarks

At least one column element is required.

Return to XML Structure

fields

This required element contains the elements that specify the various fields to be displayed in the edit area of the ListEditor HTC.

Parent Element

listeditor

Required Child Elements

None.

Optional Child Elements

boolean, date, numeric, select, text, time

Data

None.

Attributes

None.

Remarks

It must contain at least one such element, though in general it will contain several such elements, corresponding to a ListEditor HTC with several fields in the edit area.

Elements defined within the fields element are displayed as rows in the edit area of the ListEditor, in the order in which they appear within the fields element. For example, the first element defines the top row and the last element defines the bottom row.

The child elements of the fields element are essentially the same as the elements that can be defined as child elements of the editfield element in the configuration data for the EditField HTC. The primary difference is that child elements of the ListEditor HTC can include additional child elements, namely the name and tooltip elements. For information about the attributes that are shared, see Shared EditField Attributes.

Return to XML Structure

boolean

This optional element provides configuration and validation information about a particular field in a ListEditor HTC containing a Boolean value.

Parent Element

fields

Required Child Elements

None.

Optional Child Elements

browsetooltip, label, name, tooltip

Data

None.

Attributes

Attribute | Description
id, browse, browsereadonly, default, disabled, hide, onbrowse, onchange, onerror, readonly | The id attribute is required. All others are optional. For more information about these attributes, see Shared EditField Attributes.

Return to XML Structure

date

This optional element provides configuration and validation information about a particular field in a ListEditor HTC containing a date value.

Parent Element

fields

Required Child Elements

None.

Optional Child Elements

browsetooltip, error, format, name, prompt, tooltip

Data

None.

Attributes

Attribute | Description
id, browse, browsereadonly, default, disabled, hide, max, min, onbrowse, onchange, onerror, onrequire, onvalid, readonly, required | The id attribute is required. All others are optional. For more information about these attributes, see Shared EditField Attributes.

Return to XML Structure

numeric

This optional element provides configuration and validation information about a particular field in a ListEditor HTC containing a numeric value.

Parent Element

fields

Required Child Elements

None.

Optional Child Elements

browsetooltip, error, format, name, prompt, tooltip

Data

None.

Attributes

Attribute | Description
id, browse, browsereadonly, default, disabled, hide, max, min, onbrowse, onchange, onerror, onrequire, onvalid, readonly, required, subtype | The id attribute is required. All others are optional. For more information about these attributes, see Shared EditField Attributes.

Return to XML Structure

select

This optional element provides configuration and validation information about a particular field in a ListEditor HTC containing a fixed set of choices.

Parent Element

fields

Required Child Elements

select (at least one, but generally two or more)

Optional Child Elements

browsetooltip, name, prompt, tooltip

Data

None.

Attributes

Attribute | Description
id, browse, browsereadonly, default, disabled, hide, onbrowse, onchange, onerror, onvalid, readonly | The id attribute is required. All others are optional. For more information about these attributes, see Shared EditField Attributes.

Return to XML Structure

text

This optional element provides configuration and validation information about a particular field in a ListEditor HTC containing a text value.

Parent Element

fields

Required Child Elements

None.

Optional Child Elements

browsetooltip, charmask, error, name, prompt, tooltip

Data

None.

Attributes

Attribute | Description
id, browse, browsereadonly, default, disabled, hide, maxlen, minlen, onbrowse, onchange, onerror, onrequire, onvalid, readonly, required, subtype | The id attribute is required. All others are optional. For more information about these attributes, see Shared EditField Attributes.

Return to XML Structure

time

This optional element provides configuration and validation information about a particular field in a ListEditor HTC containing a time value.

Parent Element

fields

Required Child Elements

None.

Optional Child Elements

browsetooltip, error, name, prompt, tooltip

Data

None.

Attributes

Attribute | Description
id, browse, browsereadonly, default, disabled, hide, max, min, onbrowse, onchange, onerror, onrequire, onvalid, readonly, required | The id attribute is required. All others are optional. For more information about these attributes, see Shared EditField Attributes.

Remarks

The format of fields associated with the time element is fixed. Hours and minutes are displayed in a 24-hour format, separated by the colon character (":"). Seconds are not supported.

Return to XML Structure

browsetooltip, charmask, error, format, label, name, option, prompt, select, tooltip

These ten elements are used to qualify or extend the behavior of one or more of the EditField elements of various data types, embedded within the ListEditor HTC. For more information, see Shared EditField Child Elements.

Return to XML Structure


ListSheet Configuration

The XML data-island identified by the MetaXML container attribute contains the configuration information used by the ListSheet HTML component (HTC).

For more information about how an XML document can be included on a page (creating an XML data-island), see XML Data-Islands.

The structure of this data-island is shown below, with links to more detailed explanations of each element. Element attributes are shown in italic and without the values that are normally associated with them. Required elements and attributes are shown in bold; optional elements and attributes are not in bold.

Note

  • The XML elements and attributes in the MetaXML data-island for the ListSheet HTC must be expressed in lowercase letters.

XML Structure

<listsheet>
  <global curpage headers pagecontrols pagesize
          recordcount scroll selectall selection
          selectionbuttons sort/>
  <columns>
    <column format hide id id2
            id3 sortdir width>Column heading name</column>
    <subobject datawidth labelwidth type>
      <column format hide id width>Column heading name</column>
    </subobject>
  </columns>
  <operations>
    <page formid />
    <sort formid />
    <sublist formid />
    <custom_op formid />
  </operations>
</listsheet>

listsheet

This required element contains the configuration information for a ListSheet HTML component (HTC).

Parent Element

None (document root).

Required Child Elements

columns, global

Optional Child Elements

operations

Data

None.

Attributes

None.

Return to XML Structure

global

This required element specifies global characteristics of a ListSheet HTC, allowing ListSheet HTCs to exhibit different behavior in different situations.

Parent Element

listsheet

Required Child Elements

None.

Optional Child Elements

None.

Data

None.

Attributes

Attribute | Description
curpage | Specifies the current page number. Optional. Legal values: Integers. Default value: 1.
headers | Specifies whether column headings are displayed. Optional. Legal values: "yes" and "no". If the value is "no", the display of column headings is suppressed. Default value: "yes".
pagecontrols | Specifies whether or not page controls are displayed. Optional. Legal values: "yes" and "no". If the value is "no", the display of page controls is suppressed. Default value: "yes".
pagesize | Specifies the number of records displayed per page. Optional. Legal values: Integers. Default value: 20. This value is used to calculate the number of pages available for display.
recordcount | Specifies the total number of records in all pages. Optional. Legal values: Integers. Default value: None. This value is used to calculate the number of pages available for display. If it is set to -1 and page controls are displayed, then no last page display or validation is performed.
scroll | Controls whether or not scroll bars are available to display the entire list. Optional. Legal values: "yes" and "no". If the value is "no", the display of scroll bars is suppressed, resulting in a ListSheet HTC that is the height of the entire list (scrolling in the browser might be required in this case). Default value: "yes".
selectall | Specifies whether the ListSheet HTC will show all items as selected. Optional. Legal values: "yes" and "no". If the value is "yes", all items are selected. Default value: "no".
selection | Specifies whether multiple selection is allowed in this instance of the ListSheet HTC. Optional. Legal values: "single" and "multi". Default value: "single". The Select All and Unselect All buttons are only displayed when the value is "multi".
selectionbuttons | Specifies whether the Select All and Unselect All buttons are displayed. Optional. Legal values: "yes" and "no". If the value is "no", display of the Select All and Unselect All buttons is suppressed. Default value: "yes".
sort | Specifies whether clicking on a column heading sorts the records according to the values in that column. Optional. Legal values: "yes" and "no". If the value is "no", column sorting is disabled and the firing of the OnPage event is suppressed. Default value: "yes".

Return to XML Structure

columns

This required element contains the descriptions of the various columns displayed by the ListSheet HTC.

Parent Element

listsheet

Required Child Elements

column (at least one)

Optional Child Elements

subobject

Data

None.

Attributes

None.

Return to XML Structure

column

This required element provides configuration information about a particular column in a ListSheet HTC.

Parent Element

columns

Required Child Elements

None.

Optional Child Elements

None.

Data

The name of the column as the user sees it.

Attributes

Attribute Description
format Specifies that special formatting should be used for this column.

Optional.

Legal values: "select", "password", "float". See below for additional details.

Default value: None.

The value "select" will look up the display value from a select list within the meta-data.

The value "password" will mask the display in the same manner as an HTML password input element.

The value "float" will display the data as a normalized decimal number.
hide Specifies whether the column is displayed.

Optional.

Legal values: "yes" and "no". If the value is "yes", display of this column is suppressed.

Default value: "no".
id Provides the identifier used to associate this column with its corresponding first-level data.

Required.

Legal values: A string that uniquely identifies the corresponding first-level data in the XML data island identified by the DataXML container attribute.

Default value: None.

The ListSheet HTC expects to find this identifier as an XML element in the first-level of the data to be displayed.
id2 Provides the identifier used to associate this column with its corresponding second-level data.

Optional.

Legal values: A string that uniquely identifies the corresponding second-level data in the XML data island identified by the DataXML container attribute.

Default value: None.

The ListSheet HTC expects to find this identifier as an XML element in the second-level of the data to be displayed.

This attribute must be present for each column to be displayed as the second-level of a two- or three-tiered list.
id3 Provides the identifier used to associate this column with its corresponding third-level data.

Optional.

Legal values: A string that uniquely identifies the corresponding third-level data in the XML data island identified by the DataXML container attribute.

Default value: None.

The ListSheet HTC expects to find this identifier as an XML element in the third-level of the data to be displayed.

This attribute must be present for each column to be displayed as the third-level of a two- or three-tiered list.
sortdir When present, specifies the initial sort column and the direction of the sort.

Optional.

Legal values: "asc" and "desc" (ascending or descending, respectively).

Default value: None.

If more than one column has this attribute set, only the first one has any effect.
width Specifies an initial width for the column.

Optional.

Legal values: An integer between 0 and 100, representing column width as a percentage of control width. The specified widths of all columns are normalized if they do not add up to 100.

Default value: None.

If a width is not specified, the width percentage is calculated as the total width divided by the number of displayed columns.

Remarks

At least one column element is required, though typically several column elements will be specified.

Return to XML Structure

subobject

This optional element specifies details about the data displayed in the detail rows of heterogeneous grouped lists. This data is always specified as the second-level data in the DataXML container attribute, and can be displayed in either the list-style or the properties-style, as specified by the type attribute.

Parent Element

columns

Required Child Elements

column

Optional Child Elements

None.

Data

None.

Attributes

Attribute | Description
datawidth | Specifies an initial width for the data column when the type attribute is set to "properties". Optional. Legal values: An integer between 0 and 100, representing data column width as a percentage of control width. Default value: 50. When the type attribute is set to "list", this attribute is irrelevant and is ignored if present.
labelwidth | Specifies an initial width for the label column when the type attribute is set to "properties". Optional. Legal values: An integer between 0 and 100, representing label column width as a percentage of control width. Default value: 30. When the type attribute is set to "list", this attribute is irrelevant and is ignored if present.
type | Specifies which type of heterogeneous grouped list will be displayed. Required. Legal values: "list" and "properties". Default value: None.

Remarks

Typically, more than one column element will be specified.

The presence of the subobject element indicates that the ListSheet HTC will display as a heterogeneous grouped list. In this case, the id2 and id3 attributes of the top-level column elements are not used.

When the subobject element is absent, the ListSheet HTC will display as either a flat list, a two-level homogeneous grouped item list, or a three-level homogeneous grouped item list, depending on how many of the attributes id, id2, and id3 are specified.

Return to XML Structure

column

This required element provides configuration information about a particular row or column in a ListSheet displaying a heterogeneous grouped list. Whether it is a column or row depends on whether the type attribute of the subobject element is set to "list" or "properties", respectively.

Parent Element

subobject

Required Child Elements

None.

Optional Child Elements

None.

Data

The name of the column or the label on the row as the user sees it.

Attributes

Attribute Description
format Specifies that special formatting should be used for this column or row.

Optional.

Legal values: "select", "password", "float". See below for additional details.

Default value: None.

The value "select" will look up the display value from a select list within the meta-data.

The value "password" will mask the display in the same manner as an HTML password input element.

The value "float" will display the data as a normalized decimal number.
hide Specifies whether the column or row is displayed.

Optional.

Legal values: "yes" and "no". If the value is "yes", display of this column or row is suppressed.

Default value: "no".
id Provides the identifier used to associate this column or row with its corresponding second-level data.

Required.

Legal values: A string that uniquely identifies the corresponding second-level data in the XML data island identified by the DataXML container attribute.

Default value: None.

The ListSheet HTC expects to find this identifier as an XML element in the second-level of the data to be displayed.
width Specifies an initial width for the data column when the type attribute of the subobject element is set to "list".

Optional.

Legal values: An integer between 0 and 100, representing data column width as a percentage of control width. The specified widths of all columns are normalized if they do not add up to 100.

Default value: Calculated by dividing the number of subobject columns by 80, resulting in uniform column width in the right-hand 80% of the overall width of the ListSheet HTC.

When the type attribute of the subobject control is set to "properties", this attribute is irrelevant and is ignored if present.

Remarks

If the subobject element is present, at least one column element is required, though in general, multiple column elements will be specified.

Return to XML Structure

operations

This optional element contains other elements that, when present, cause certain standard XMLHTTP operations to be performed when specific events are fired. This set of operations can also be extended with custom operations.

Parent Element

listsheet

Required Child Elements

None.

Optional Child Elements

page, sort, sublist, custom_op

Data

None.

Attributes

None.

Remarks

All child elements, including custom child elements, represent different operations that will be performed when different events occur.

If the operations element is present but contains no child elements, it will be ignored.

The operations corresponding to the child elements are known as XMLHTTP operations. For more information about XMLHTTP operations, see XMLHTTP Operations and Fetch Pages.

Return to XML Structure

page

This optional element corresponds to a standard XMLHTTP operation available with the ListSheet HTC. When this element is present, the entire list reloads with new data after the OnNewPage event fires. The new data is returned from a page on the server and must not contain anything except the data in the standard XML data format.

Parent Element

operations

Required Child Elements

None.

Optional Child Elements

None.

Data

None.

Attributes

Attribute | Description
formid | Specifies the identifier of the form that will be posted when the OnNewPage event fires. Required. Legal values: Valid id attribute of a form element. Default value: None.

Remarks

For more information about XMLHTTP operations, see XMLHTTP Operations and Fetch Pages.

The identifier of the corresponding form is set as the formid attribute. The action attribute of the form must be set to the post page: the page that returns the new page of data.

The following table shows the arguments that are sent when the form is posted.

Argument | Description
op | The value of this attribute is set to "page". This argument, combined with the post page specified as an attribute of the form, allows specific server-side code to be executed in response to the OnNewPage event. The op argument allows the same post page to process more than one operation, branching to perform different operations based on the value of this argument.
prevpage | The value of this attribute is set to number of the page currently being displayed, soon to be the previous page displayed.
page | The value of this attribute is set to the number of the new page to be displayed.
column | The value of this attribute is set to the ID of the sort column for the new page of data. This ID is the name of the relevant child element of the record element.
direction | The value of this attribute is set to either "asc" or "desc", depending on whether the new page of data should be sorted in the ascending direction or the descending direction, respectively.

For more information about how the posting of forms is used to perform operations on the server, including saving changes to data, see Saving Changes to Data.

Return to XML Structure

sort

This optional element corresponds to a standard XMLHTTP operation available with the ListSheet HTC. When this element is present, the entire list reloads with new data after the OnHeaderClick event fires. The new data is returned from a page on the server and must not contain anything except the data in the standard XML data format.

Parent Element

operations

Required Child Elements

None.

Optional Child Elements

None.

Data

None.

Attributes

Attribute | Description
formid | Specifies the identifier of the form that will be posted when the OnHeaderClick event fires. Required. Legal values: Valid id attribute of a form element. Default value: None.

Remarks

For more information about XMLHTTP operations, see XMLHTTP Operations and Fetch Pages.

The identifier of the corresponding form is set as the formid attribute. The action attribute of the form should be set to the post page: the page that returns the first page of data, re-sorted as specified.

The following table shows the arguments that are sent when the form is posted.

Argument | Description
op | The value of this attribute is set to "sort". This argument, combined with the post page specified as an attribute of the form, allows specific server-side code to be executed in response to the OnHeaderClick event. The op argument allows the same post page to process more than one operation, branching to perform different operations based on the value of this argument.
page | The value of this attribute is always set to 1. This operation does not permit re-sorting the list without returning to the beginning of the list, where the "top" of the sort will be displayed.
column | The value of this attribute is set to the ID of the sort column for the new page of data. This ID is the name of the relevant child element of the record element.
direction | The value of this attribute is set to either "asc" or "desc", depending on whether the new page of data should be sorted in the ascending direction or the descending direction, respectively.

For more information about how the posting of forms is used to perform operations on the server, including saving changes to data, see Saving Changes to Data.

Return to XML Structure

sublist

This optional element corresponds to a standard XMLHTTP operation available with the ListSheet HTC. When this element is present, the list under the currently selected item loads with data when this operation is invoked using the reload method, which should be called in the OnGroupOpen event handling routine. This means that the retrieval of detail data can be deferred until it needs to be displayed.

Parent Element

operations

Required Child Elements

None.

Optional Child Elements

None.

Data

None.

Attributes

Attribute | Description
formid | Specifies the identifier of the form that will be posted when the OnGroupOpen event fires. Required. Legal values: Valid id attribute of a form element. Default value: None.

Remarks

For more information about XMLHTTP operations, see XMLHTTP Operations and Fetch Pages.

The identifier of the corresponding form is set as the formid attribute. The action attribute of the form should be set to the post page, the page that returns the detail data.

The following table shows the arguments that are sent when the form is posted.

Argument | Description
op | The value of this argument is set to "sublist". This argument, combined with the post page specified as an attribute of the form, allows specific server-side code to be executed in response to the OnGroupOpen event. The op argument allows the same post page to process more than one operation, branching to perform different operations based on the value of this argument.
xmllist | The value of this argument is set to the XML of the list item that was clicked, so that the post page knows what sub-items to return.

In some situations it might be appropriate to include other parameters in the posted form as part of fetching the correct XML response. For example, suppose a response page is designed to be shared by several different pages, returning different results based on which page calls it. In this case, the form might have a hidden element containing the page name so the response page will know which page called it.

For more information about how the posting of forms is used to perform operations on the server, including saving changes to data, see Saving Changes to Data.

Return to XML Structure

custom_op

Custom operation elements, which are optional, correspond to custom XMLHTTP operations defined for a ListSheet HTC. When a custom operation element is present, the entire list reloads when the reload method is called with its sOp parameter set to the custom name for this element.

Parent Element

operations

Required Child Elements

None.

Optional Child Elements

None.

Data

None.

Attributes

Attribute | Description
formid | Specifies the identifier of the form that will be posted when the reload method is called with its sOp parameter set to the custom name for this element. Required. Legal values: Valid id attribute of a form element. Default value: None.

Remarks

For example, if the element double_sort is included as a custom operation, and the reload method is called with its sOp parameter set to "double_sort", the form with the specified identifier will be posted. For example:

bRetVal = elListSheet.reload("double_sort")

The reload method returns False if no XML is returned or if any error elements are present, and True otherwise.

For more information about XMLHTTP operations, see XMLHTTP Operations and Fetch Pages.

The identifier of the corresponding form is set as the formid attribute. The action attribute of the form should be set to the post page, the page that returns the new data.

The following table shows the arguments that are sent when the form is posted.

Argument | Description
op | The value of this attribute is set to "custom_op". This argument, combined with the post page specified as an attribute of the form, allows specific server-side code to be executed in response to a particular invocation of the reload method. The op argument allows the same post page to process more than one operation, branching to perform different operations based on the value of this argument.

In some situations it might be appropriate to include other parameters in the posted form as part of fetching the correct XML response. For example, suppose a response page is designed to be shared by several different pages, returning different results based on which page calls it. In this case, the form might have a hidden element containing the page name so the response page will know which page called it.

For more information about how the posting of forms is used to perform operations on the server, including saving changes to data, see Saving Changes to Data.

Return to XML Structure


QueryBuilder Configuration

The XML data-island identified by the XMLCfgID container attribute contains the configuration information used by the QueryBuilder HTML component (HTC).

For more information about how an XML document can be included on a page (creating an XML data-island), see XML Data-Islands.

The structure of this data-island is shown below, with links to more detailed explanations of each element. Element attributes are shown in italic and without the values that are normally associated with them. Required elements and attributes are shown in bold; optional elements and attributes are not bolded.

Note

  • The XML elements and attributes in the MetaXML data-island for the QueryBuilder HTC must be expressed in uppercase letters.

XML Structure

<EBCONFIG>
  <EXPR-ASP>relative URL of exprarch directory</EXPR-ASP>
  <PROFILE-LIST>
    <PROFILE>profile name</PROFILE>
    <PROFILE SRC />
  </PROFILE-LIST>
  <SITE-TERMS URL NOLOAD />
  <EEE-INTRINSICS />
  <DEBUG />
  <TYPESOPS>path to xml file</TYPESOPS>
  <MESSAGE>alternate message</MESSAGE>
  <EDIT-NESTED>always, warn, or never</EDIT-NESTED>
  <DATE-FORMAT>date format</DATE-FORMAT>
  <DATE-FIRSTDAY>first day of week</DATE-FIRSTDAY>
  <NUMBER-FORMAT>number format</NUMBER-FORMAT>
  <CURRENCY-FORMAT>currency format</CURRENCY-FORMAT>
  <HELPTOPIC>help topic URL</HELP-TOPIC>
  <ADVANCED />
  <FILTER-PROPERTIES>XSL expression</FILTER-PROPERTIES>
</EBCONFIG>

EBCONFIG

This required element contains the configuration information for an instance of the QueryBuilder HTC.

Parent Elements

None (document root)

Required Child Elements

EXPR-ASP, PROFILE-LIST

Optional Child Elements

ADVANCED, CURRENCY-FORMAT, DATE-FIRSTDAY, DATE-FORMAT, DEBUG, EDIT-NESTED, EEE-INTRINSICS, FILTER-PROPERTIES, HELPTOPIC, MESSAGE, NUMBER-FORMAT, SITE-TERMS, TYPESOPS

Data

None.

Attributes

None.

Return to XML Structure

EXPR-ASP

This required element specifies the relative URL of the Exprarch folder, which is required for the proper functioning of the QueryBuilder HTC.

Parent Elements

EBCONFIG

Required Child Elements

None.

Optional Child Elements

None.

Data

None.

Attributes

None.

Return to XML Structure

PROFILE-LIST

This required element contains the specifications of the various profiles used by this instance of the QueryBuilder HTC.

Parent Elements

EBCONFIG

Required Child Elements

PROFILE (at least one is required)

Optional Child Elements

None.

Data

None.

Attributes

None.

Return to XML Structure

PROFILE

This required element specifies a profile in one of two distinct ways. For profile definitions defined within Commerce Server, the name of the profile is specified as data associated with the element. For profiles not defined within Commerce Server, the URL of a valid XML document containing one or more profiles is specified as the value of the SRC attribute.

Parent Element

PROFILE-LIST

Required Child Elements

None.

Optional Child Elements

None.

Data

When the SRC attribute is not present, the name of the profile is specified as data within the PROFILE element. Otherwise, no data is present.

Attributes

Attribute | Description
SRC | Provides the URL of a valid XML document that contains one or more profiles not defined within Commerce Server. Optional. Legal values: A valid URL. Default value: None. When this attribute is specified, the PROFILE element should not contain any data.

Remarks

When the name of a Profile Definition defined within Commerce Server is specified as data for this element, the name must be of the form "CatalogName.ProfileName". For example, "UserProfiles.UserObject".

When a profile not defined within Commerce Server is specified using the SRC attribute, it must conform to a defined XML structure for profile specification. For more information about this structure, see Specifying Profiles and Site Terms in the QueryBuilder HTC.

Return to XML Structure

SITE-TERMS

This optional element specifies alternate information about whether the QueryBuilder HTC should load site-terms, and if so, from where.

Parent Element

EBCONFIG

Required Child Elements

None.

Optional Child Elements

None.

Data

None.

Attributes

Attribute | Description
NOLOAD | Suppresses the loading of site-terms for this instance of the QueryBuilder HTC (when set to "1"). Optional. Legal values: "1". Default value: None. If site-term loading is suppressed and queries containing site-terms are passed to the QueryBuilder HTC, errors will result. This attribute should not be specified in combination with the URL attribute.
URL | Provides the URL of a valid XML document that contains alternate site-terms for use in this instance of the QueryBuilder HTC. Optional. Legal values: A valid URL. Default value: None. This attribute should not be specified in combination with the NOLOAD attribute.

REMARKS

When the SITE-TERMS element is present, either the NOLOAD attribute or the URL attribute (but not both) must be specified.

When the SITE-TERMS element is not present, site terms are loaded from the same folder specified by the required EXPR-ASP element.

When an alternate set of site terms is specified using the URL attribute, it must conform to the defined XML structure for site term specification. For more information about this structure, see Specifying Profiles and Site Terms in the QueryBuilder HTC.

Return to XML Structure

EEE-INTRINSICS

This optional element, when present, causes the QueryBuilder HTC to expose the intrinsic properties of the Expression Evaluator as a profile in its drop-down menus.

Parent Elements

EBCONFIG

Required Child Elements

None.

Optional Child Elements

None.

Data

None.

Attributes

None.

Return to XML Structure

DEBUG

This optional element, when present, causes the QueryBuilder HTC to display debugging information.

Parent Elements

EBCONFIG

Required Child Elements

None.

Optional Child Elements

None.

Data

None.

Attributes

None.

Return to XML Structure

TYPESOPS

This optional element, when present, specifies a types and operators XML file for the QueryBuilder HTC to use.

Parent Elements

EBCONFIG

Required Child Elements

None.

Optional Child Elements

None.

Data

The relative path to the XML types and operators file.

Attributes

None.

Remarks

If this element is not specified, the default types and operators file is /Widgets/ExprbldrHTC/TypesOpsA.xml.

Return to XML Structure

MESSAGE

This optional element, when present, specifies an alternate message to be displayed above the expression-selector area.

Parent Elements

EBCONFIG

Required Child Elements

None.

Optional Child Elements

None.

Data

The alternate message.

Attributes

None.

Remarks

When the MESSAGE element is not present, the default message is "Target based to the following conditions:".

Return to XML Structure

EDIT-NESTED

This optional element, when present, specifies whether editing of nested expressions is allowed or prevented, or only allowed if the user explicitly allows it in response to a warning dialog box.

Parent Elements

EBCONFIG

Required Child Elements

None.

Optional Child Elements

None.

Data

One of the three values "always", "warn", or "never". See Remarks for more details.

Attributes

None.

Remarks

Specifying "always" results in the nested expression being opened in edit mode. In general, this is not recommended.

Specifying "warn" results in a warning dialog box that offers the choice between opening the nested expression in edit mode or view mode.

Specifying "never" results in the nested expression being opened in view mode.

The default behavior, in the event that the EDIT-NESTED element is not present or contains an illegal data value, is to not allow the editing of nested expressions.

The EDIT-NESTED is only relevant when an expression is being created or edited.

Return to XML Structure

DATE-FORMAT

This optional element, when present, specifies the display format for dates.

Parent Elements

EBCONFIG

Required Child Elements

None.

Optional Child Elements

None.

Data

The display format for dates.

Attributes

None.

Remarks

Valid formats for dates are "m/d/yyyy", "d/m/yyyy", and "yyyy/m/d". The default is "m/d/yyyy". The separator can be specified as any of the following three characters: forward slash ("/"), hyphen ("-"), and period ("."). The default separator is forward slash ("/"). Any number of the characters "m", "d", and "y" may be specified without affecting displayed dates; months and days will always be displayed without a leading zero, and years will always be displayed using 4 digits.

Return to XML Structure

DATE-FIRSTDAY

This optional element, when present, specifies the day of the week that will be considered the first day of the week.

Parent Elements

EBCONFIG

Required Child Elements

None.

Optional Child Elements

None.

Data

A number in the range 0 (Sunday) to 6 (Saturday).

Attributes

None.

Remarks

Days of the week are represented by numbers between 0 and 6, as follows: 0 = Sunday; 1 = Monday; 2 = Tuesday, 3 = Wednesday; 4 = Thursday; 5 = Friday, and 6 = Saturday.

If this element is not present, the default first day of the week is Sunday.

Return to XML Structure

NUMBER-FORMAT

This optional element, when present, specifies the display format for numbers.

Parent Elements

EBCONFIG

Required Child Elements

None.

Optional Child Elements

None.

Data

The display format for numbers.

Attributes

None.

Remarks

Valid formats for numbers are specified using a string that indicates the manner in which negative values will be indicated (or not), relative to the placement of digits. The negative value indicator can be a leading or trailing hyphen ("-"), space-separated from the number or not, or it can be parentheses around the number.

If this element is not present, the default format is "–1.1".

Examples:

1.1 -1.1 1.1- (1.1)

Return to XML Structure

CURRENCY-FORMAT

This optional element, when present, specifies the display format for currency.

Parent Elements

EBCONFIG

Required Child Elements

None.

Optional Child Elements

None.

Data

The display format for currency.

Attributes

None.

Remarks

Valid formats for currency are specified using a string that indicates the manner in which negative values will be indicated (or not), relative to the placement of digits. The negative value indicator can be a leading or trailing hyphen ("-"), space-separated from the number or not, or it can be parentheses around the number.

If this element is not present, the default format is "–1.1".

No currency symbol should be specified as part of this format.

Examples:

1.1 -1.1 1.1- (1.1)

Return to XML Structure

HELPTOPIC

This optional element, when present, specifies a help topic for this instance of the QueryBuilder HTC.

Parent Elements

EBCONFIG

Required Child Elements

None.

Optional Child Elements

None.

Data

The absolute URL of the corresponding help topic.

Attributes

None.

Remarks

If this element is present, the QueryBuilder HTC will display a help button, which when clicked will display the specified help topic.

Use the server-side utility routine sRelURL2AbsURL to generate the absolute URL required by this element. For example:

<HELPTOPIC><%=sRelURL2AbsURL("../docs/htm/yourhelpfile.htm")%></HELPTOPIC>

Return to XML Structure

ADVANCED

This optional element, when present, specifies that advanced editing will be allowed. Advanced editing allows the use of the OR operator in expressions.

Parent Elements

EBCONFIG

Required Child Elements

None.

Optional Child Elements

None.

Data

None.

Attributes

None.

Remarks

If this element is not present, advanced editing is not allowed.

Return to XML Structure

FILTER-PROPERTIES

This optional element, when present, specifies an XSL pattern fragment used for filtering properties from the profile. If this element is present, the provided XSL pattern will be applied to the properties in each profile that is loaded. Any properties that do not conform to the XSL pattern will not be shown when creating or editing expressions.

Parent Elements

EBCONFIG

Required Child Elements

None.

Optional Child Elements

None.

Data

The XSL pattern fragment.

Attributes

None.

Remarks

The default XSL pattern fragment is: not(@isActive) || @isActive != '0'

The data values supplied for this element are actually XSL pattern fragments because they are surrounded by the strings "Property[" and "]" to achieve the actual XSL pattern. For example, the actual default XSL pattern, shown with the added strings in bold, is as follows:

Property[not(@isActive) || @isActive != '0']

Element attributes return "0" when they are not defined. Therefore, it is recommended the XSL pattern fragments specified as data for this element check for the presence of an attribute as well as for the attribute value being set to zero. The default XSL pattern is an example of both of these conditions being checked.

Return to XML Structure


Specifying Profiles and Site Terms in the QueryBuilder HTC

Both the PROFILE and SITE-TERMS elements, which are part of the MetaXML for the ExpressionBuilder and QueryBuilder HTCs, can be configured to use alternative profiles and site terms, respectively. These alternative profiles and site terms are specified by providing the URL of an XML file, as the value of the SRC attribute of the PROFILE element and the URL attribute of the SITE-TERMS element, respectively.

The XML structure used to specify alternative profiles and site terms for the QueryBuilder HTC consists of a subset of the more general XML schema used for profiles within Commerce Server. The QueryBuilder HTC is not concerned with all of the elements and attributes of the more general schema, and will ignore those elements and attributes that are not of interest to it.

The XML structures used to specify profiles and site terms are similar enough that they are described here together. In terms of elements, they are the same except for the type of child element that must be present for the Property element.

In the case of profiles, the Property element typically contains one DataRef element, representing the data-member to which the property maps.

In the case of site terms, the Property element contains at least one, and typically several, Attribute elements, each representing one of the choices available for that site term.

In both profile and site term specification, the Group element can be used to organize properties and site terms into a hierarchy. This can be beneficial when there are a large number of properties or site-terms present.

The descriptions of each element and attribute specify whether they are relevant for only profiles, or only site terms.

XML Structure

<Profile name displayName description>
  <Property name displayName description propType
            referenceString isActive isMultiValue isSearchable>
    <DataRef idref />
    . . .
    <DataRef />
    <Attribute name displayName description />
    . . .
    <Attribute />
  </Property>
  . . .
  <Property> . . .</Property>
  <Group name displayName description>
    <Property/>
    <Group/>
  </Group>
  . . .
  <Group> . . .</Group>
</Profile>

Profile

This required element represents a profile definition or the definition of a set of site terms.

Parent Elements

None (document root)

Required Child Elements

None.

Optional Child Elements

Property, Group
(At least one is required.)

Data

None.

Attributes

Attribute | Description
name | Provides a programmatic name for this profile or set of site terms, used when accessing it from code. Required. Legal values: Any string up to 30 characters in length. Default value: None.
displayname | Provides a friendly name for the profile or set of site terms, used when it is displayed in a user interface. Required. Legal values: Any string up to 30 characters in length. Default value: Most tools default this value to be the same as name attribute. The value of this attribute may be locale-specific.
description | Stores additional information about the purpose of a set of site terms. If this attribute is present in a profile specification, it is ignored by the QueryBuilder HTC. Optional. Legal values: Any string up to 200 characters in length. Default value: None (an empty string). The value of this attribute may be locale-specific.
defaultTableName, isNew, isModified, isDeleted | These attributes, which may appear in the more general profile schema, are not relevant to site term specification for the QueryBuilder HTC.

Return to XML Structure

Property

This required element represents a single property in a profile definition, or a single site term within a set of site terms.

Parent Elements

Profile, Group

Required Child Elements

None.

Optional Child Elements

DataRef (profiles), Attribute (site terms)
(at least one of the relevant type is required.)

Data

None.

Attributes

Attribute | Description
name | Provides a programmatic name for this property or site term, used when accessing it from code. Required. Legal values: Any string up to 30 characters in length. Default value: None.
displayname | Provides a friendly name for the property or site term, used when it is displayed in a user interface. Required. Legal values: Any string up to 30 characters in length. Default value: Most tools default this value to be the same as name attribute. The value of this attribute may be locale-specific.
description | Stores additional information about the purpose of a site term. If this attribute is present in a profile specification, it is ignored by the QueryBuilder HTC. Optional. Legal values: Any string up to 200 characters in length. Default value: None (an empty string). The value of this attribute may be locale-specific.
propType | Stores the data type of a property. If this attribute is present in a set of site terms, it is ignored by the QueryBuilder HTC. Required. Legal values: STRING, SITETERM, PASSWORD, NUMBER, BOOL, DATE, TIME, DATETIME, PROFILE. Default value: None. The values SITETERM and PASSWORD are strings, but with specific semantics applied. The values DATE, TIME, and DATETIME are all stored as a single date-time data type, but with different semantics applied.
referenceString | Stores supplementary information about the data type of a property. If this attribute is present in a set of site terms, it is ignored by the QueryBuilder HTC. Optional. Legal values: The name of a profile. Default value: None. If the propType attribute specifies a profile, this attribute must specify the name of a profile.
isActive | Indicates whether the value of this property is loaded by the Profile Service. If this attribute is present in a set of site terms, it is ignored by the QueryBuilder HTC. Optional. Legal values: "true" and "false". If the value is "true", the value of this property is loaded by the Profile Service. If the value is "false", the value of this property is not loaded by the Profile Service. Default value: "true".
isMultiValue | Indicates whether this property is multi-valued, that is, consists of a list of values. If this attribute is present in a set of site terms, it is ignored by the QueryBuilder HTC. Optional. Legal values: "true" and "false". If the value is "true", this property is multi-valued. If the value is "false", this property is multi-valued. Default value: "false".
isSearchable | Indicates whether fast searching can be performed on this property. If this attribute is present in a set of site terms, it is ignored by the QueryBuilder HTC. Optional. Legal values: "true" and "false". If the value is "true", fast searching can be performed on this property. If the value is "false", searching on this property can still be performed, but may be slower. Default value: "false".
keyDef, defaultValue, isCached, isDefaultNull, isExported, isHidden, isPrivate, isReadOnly, isRequired, isUpdatable, isNew, isModified, isDeleted | These attributes, which may appear in the more general profile schema, are not relevant to the QueryBuilder HTC. This is true with respect to both profile and site term specification.

Return to XML Structure

Attribute

With respect to the QueryBuilder HTC, this element is only relevant in the specification of sets of site terms. It represents one of the choices available for the site term. In general, there will be several Attribute elements specified, representing a corresponding set of choices.

In the more general profile schema, it may appear as a child element of Profile, Group, Property, and SourceInfo elements.

Parent Elements

Property (in site term specifications)

Required Child Elements

None.

Optional Child Elements

None.

Data

None.

Attributes

Attribute | Description
name | Provides a programmatic name for this site term choice, used when accessing it from code. Required. Legal values: Any string up to 30 characters in length. Default value: None.
displayname | Provides a friendly name for this site term choice, used when it is displayed in a user interface. Required. Legal values: Any string up to 30 characters in length. Default value: Most tools default this value to be the same as name attribute. The value of this attribute may be locale-specific.
description | Stores additional information about the purpose of a site term choice. Optional. Legal values: Any string up to 200 characters in length. Default value: None (an empty string). The value of this attribute may be locale-specific.
value, isNew, isModified, isDeleted | These attributes, which may appear in the more general profile schema, are not relevant to site term specification for the QueryBuilder HTC.

Return to XML Structure

DataRef

With respect to the QueryBuilder HTC, this element is only relevant in the specification of profiles. In the more general profile schema, it may appear as a child element of Profile, Group, Property, and SourceInfo elements.

This element contains the mapping information about its parent property. Each DataRef element contains a reference to a data member in a data object exposed by a data source. When a profile property is mapped to multiple data members (as when the property is an aggregated property), it will contain multiple DataRef child elements.

Parent Elements

Property (in profile specifications)

Required Child Elements

None.

Optional Child Elements

None.

Data

None.

Attributes

Attribute | Description
idref | Specifies the data-member to which the parent Property element maps. Required. Legal values: Strings of the form sourceName.objectName.memberName. Default value: None.
isRDNAttribute, isModified | These attributes, which may appear in the more general profile schema, are not relevant to site term specification for the QueryBuilder HTC.

Return to XML Structure

Group

This element represents a logical grouping of properties or site terms, and potentially subgroups, in a profile definition or set of site terms.

Parent Elements

Profile, Group

Required Child Elements

None.

Optional Child Elements

Group, Property
(at least one is required.)

Data

None.

Attributes

Attribute | Description
name | Provides a programmatic name for this group, used when accessing it from code. Required. Legal values: Any string up to 30 characters in length. Default value: None.
displayname | Provides a friendly name for this group, used when it is displayed in a user interface. Required. Legal values: Any string up to 30 characters in length. Default value: Most tools default this value to be the same as name attribute. The value of this attribute may be locale-specific.
description | Stores additional information about the purpose of a group. Optional. Legal values: Any string up to 200 characters in length. Default value: None (an empty string). The value of this attribute may be locale-specific.
isNew, isModified, isDeleted | These attributes, which may appear in the more general profile schema, are not relevant to the QueryBuilder HTC. This is true with respect to both profile and site term specification.

Return to XML Structure


TreeView Configuration

The TreeView control requires that the tree to be displayed be passed to it in the form of an XML data-island. The container attribute DataXML is set to the ID of this data-island.

For more information about the ways in which an XML document can be included on a page (creating an XML data-island), see XML Data-Islands.

It is important to note that the TreeView HTC is the only Commerce Server Business Desk HTC that does not have any configuration data. In other words, there is no MetaXML container attribute that must be specified for the TreeView HTC. Only data is provided, using the DataXML container attribute. The nested nature of the elements provides the nesting shown in the displayed tree.

The structure of this data-island is shown below, with links to more detailed explanations of each element. Element attributes are shown in italic and without the values that are normally associated with them. Required elements and attributes are shown in bold; optional elements and attributes are not bolded.

Note

  • The XML elements and attributes, not including the arbitrarily named elements, in the MetaXML data-island for the TreeView HTC must be expressed in lowercase letters.

XML Structure

<document selection>
  <level_1_element caption closed
                   enabled hidden
                   queryid selected
                   skip>data that might be displayed
    <level_2_element caption closed
                     enabled hidden
                     queryid selected
                     skip>data that might be displayed
      <level_3_element caption closed
                       enabled hidden
                       queryid selected
                       skip>data that might be displayed

Note that levels can go to an arbitrary depth...

      </level_3_element>
    </level_2_element>
  </level_1_element>
  <another_level_1_element caption closed
                           enabled hidden
                           queryid selected
                           skip>data that might be displayed
    <another_level_2_element caption closed
                             enabled hidden
                             queryid selected
                             skip>data that might be displayed
      <expand />
    </another_level_2_element>
  </another_level_1_element>
  <operations>
    <expand formid />
    <custom_op formid />
  </operations>
</document>

document

This required element contains the configuration information for a TreeView HTML Component (HTC).

Parent Elements

None (document root)

Required Child Elements

None.

Optional Child Elements

operations, arbitrary_tree_nodes

Data

None.

Attributes

Attribute | Description
selection | Specifies whether multiple selection will be allowed. Optional. Legal values: "single" and "multi", allowing single and multiple selection, respectively. Default value: "single".

Remarks

To be meaningful, the document element must contain one or more elements besides the operations element. The names of these other elements is arbitrary, and in certain circumstances these names are used as the display string for the corresponding tree node shown to the user.

Return to XML Structure

level_N_element

Other than the document element, the two types of expand elements, and the operations element, the names of all elements in the data-island for the TreeView HTC are arbitrary. There are circumstances where the element name itself is displayed in the control; in such cases extra care must be taken with regard to the element names. Otherwise, they can be truly arbitrary with no effect on the functioning of the TreeView HTC. The arbitrary elements may contain data and may contain the caption attribute, but need not.

Parent Element

document, arbitrary_tree_element

Required Child Elements

None.

Optional Child Elements

arbitrary_tree_element

Data

Optionally, a string that will be displayed to the user as the name of the tree node, if no caption attribute value is provided for this element.

Attributes

Attribute | Description
caption Provides the highest precedence choice for text to be displayed to the user.

Optional.

If present, it overrides both data supplied with the element and the element name itself.
closed When set to "yes", the tree item corresponding to this element will initially be displayed as closed.

Optional.

If not present, or set to any other value, and assuming that the element has child elements, the corresponding item is initially displayed as open.
enabled When set to "no", the tree item corresponding to this element will be disabled.

Optional.

Disabled items are dimmed, and their events are suppressed.

Further, even if they have child items, they cannot to be opened and closed.

If this attribute is not present, or set to any other value, the item is enabled, resulting in normal display and operation.
hidden When set to "yes", the tree item corresponding to this element will be hidden.

Optional.

Any child items are hidden as well.

If this attribute is not present, or set to any other value, the item is visible.
queryid | This attribute is reserved for use by the TreeView HTC itself and should not be set prior to invoking the TreeView HTC.
selected When set to "yes", the tree item corresponding to this element will be initially displayed as selected.

Optional.

Legal values are "yes" and "no".

After initial loading, this attribute continues to be maintained. In other words, it is set to either "yes" or "no" as the corresponding tree item is selected and deselected, respectively.
skip When set to "yes", the corresponding element will be skipped when building the tree structure.

Optional.

If this attribute is not present, or set to any other value, the element is not skipped and results in an item in the tree being displayed (subject to other effects of other attributes).

Unlike the hidden attribute, setting the skip attribute for an element to "yes" does not prevent its child elements from being displayed.

Remarks

The text that is displayed to the user for a particular item in the tree can come from one of three places, with a specific order of precedence, as follows:

  1. If the element has a caption attribute, the value of that attribute is displayed.

  2. Otherwise, if the element contains data, that data is displayed.

  3. Otherwise, the element name itself is displayed.

For example, consider the following XML tree structure, which shows the actual text to be displayed in bold font. Note the presence of the expand element, which allows deferred loading of portions of the tree.

<Item1A>
  <LevelTwo caption=Item2A>Data that will not be displayed
    <LevelThree>Item3A</LevelThree>
    <LevelThree>Item3B</LevelThree>
  </LevelTwo>
</Item1A>
<Item1B>
  <LevelTwo caption=Item2B>More text that will not be displayed
    <LevelThree>Item3C</LevelThree>
    <LevelThree>Item3D</LevelThree>
  </LevelTwo>
  <LevelTwo>Item2C
    <expand />
  </LevelTwo>
</Item1B>
<Item1C>
  <LevelTwo caption=Item2D />
</Item1B>

Given the XML tree structure above, the TreeView HTC displays the following tree when fully expanded, and assuming that the one expand element resulted in a single item named "Item3E (retrieved using expand operation)" being returned.

[-] Item1A

[-] Item2A

Item3A

Item3B

[-] Item1B

[-] Item2B

Item3C

Item3D

[-] Item2C

Item3E (retrieved using expand operation)

[-] Item1C

Item2D

Return to XML Structure

expand

This optional element marks a place in the tree structure where the loading of subordinate tree elements is deferred until the element in question is actually expanded by the user.

Parent Elements

arbitrary_element

Required Child Elements

None.

Optional Child Elements

None.

Data

None.

Attributes

None.

Remarks

There are two distinct types of expand elements that can occur in the DataXML data-island. This is the first type, which can occur within the arbitrarily named tree elements, and which serves as a placeholder for where the loading of a section of the tree has been deferred, and thus where expansion can occur.

Together, the two types of expand elements are used to perform a special type of XMLHTTP Operation available with the TreeView HTC. This operation allows the loading of the subordinate tree items to be deferred until the containing tree item is opened. In circumstances involving large numbers of items, such deferral can drastically improve the performance of the initial loading and display of the tree.

This element, when present as the sole child element of another element, causes that element to be displayed as a containing item. In other words, with a plus sign indicating the (potential) presence of one or more subordinate items that are not currently being shown. The containing item must be initially closed because the subordinate items have not yet been retrieved. Indeed, the presence of the expand element implies that the closed attribute of its containing element is set to "yes".

When a tree item is opened by a user, the OnItemOpen event fires. If the data for the item being opened is already loaded, no event handler need be assigned to this event. On the other hand, if this event fires and the TreeView HTC finds an expand element rather than the requisite data, an event handling routine needs to be in place. This routine is responsible for adding arguments to the form so that the response page knows which node is being expanded. If no event handling routine has been assigned to the OnItemOpen event and an expand element is encountered, no arguments will be added to the form, and the operation is not likely to return the proper data.

Arguments are added to the form in the standard fashion: hidden input elements are embedded in the form, and the event handling routine simply assigns the appropriate values to those input elements. For example, suppose there is a form element with its id attribute set to "tvform" and it contains a hidden input element with its id attribute set to "category". The event handling routine can assign the value "chocolate" to that input element with the following line of code:

tvform.category.value = 'chocolate'

Once the event handling routine, if any, has executed, and if the TreeView HTC has found an expand element where it needs to show a newly expanded section of the tree, the TreeView HTC will call the reload method with the sOp parameter set to "expand".

For more information about XMLHTTP Operations, see XMLHTTP Operations and Fetch Pages.

The identifier of the corresponding form is set as the formid attribute of the other expand element, the one that is subordinate to the operations element. Unless you were to change the value of this attribute dynamically, all expansion must be handled by the same form. On the response page at the server, the passed arguments must be used to determine the item being expanded, so that the correct data can be returned.

For more information about how the posting of forms is used to perform operations on the server, including saving changes to data, see Saving Changes to Data.

Return to XML Structure

operations

This optional element contains other elements that, when present, cause certain custom XMLHTTP Operations to be performed when the reload method is invoked with certain parameter values.

Parent Elements

document

Required Child Elements

None.

Optional Child Elements

expand, arbitrary_operations_elements

Data

None.

Attributes

None.

Remarks

If the operations element is present but contains no child elements, it is ignored.

Return to XML Structure

expand

This optional element identifies the form element that will be used to post the expansion request to the server.

Parent Element

operations

Required Child Elements

None.

Optional Child Elements

None.

Data

None.

Attributes

Attribute | Description
formid | Specifies the identifier of the form that will be posted when the OnItemOpen event fires and its handler calls the reload method with the sOp parameter set to "expand". Required. Legal values: Valid id attribute of a form element. Default value: None.

Remarks

There are two distinct types of expand elements that can occur in the DataXML data-island. This is the second type, which can occur within the operations element, and which serves to identify the form element that will be used to post the expansion request to the server.

Together, the two types of expand elements are used to perform a special type of XMLHTTP Operation available with the TreeView HTC. This operation allows the loading of the subordinate tree items to be deferred until the containing tree item is opened. In circumstances involving large numbers of items, such deferral can drastically improve the performance of the initial loading and display of the tree.

If any of the other type of expand elements exist in the DataXML data-island, then this expand element must be present, providing the ID of the form used to handle deferred item loading. The action attribute of this form must be set to the post page, the page that returns the new, expand section of the tree.

Like other HTTP/XML Operations, the new data returned from the post page on the server must not contain anything except the data in the standard XML data format.

The returned set of subordinate items actually replaces the expand element in the tree. This means that a particular expand operation will normally only occur once for each instantiation of the TreeView HTC.

For more information about XMLHTTP Operations, see XMLHTTP Operations and Fetch Pages.

This type of expand element is optional, but must be present if any of the other type of expand elements are present.

For more information about how the posting of forms is used to perform operations on the server, including saving changes to data, see Saving Changes to Data.

Return to XML Structure

custom_op

Custom operation elements correspond to custom XMLHTTP Operations defined for a TreeView HTC. When a custom operation element is present, the entire tree reloads when the reload method is called with its sOp parameter set to the custom name for the element.

For example, if the element alpha_sort is included as a custom operation, and the reload method is called with its sOp parameter set to "alpha_sort", the form with the specified identifier will be posted. For example,

elTreeView.reload("alpha_sort")

Parent Element

operations

Required Child Elements

None.

Optional Child Elements

None.

Data

None.

Attributes

Attribute | Description
formid | Specifies the identifier of the form that will be posted when the reload method is called with its sOp parameter set to the custom name for this element. Required. Legal values: Valid id attribute of a form element. Default value: None.

Remarks

For more information about XMLHTTP Operations, see XMLHTTP Operations and Fetch Pages.

The identifier of the corresponding form is set as an attribute. The action attribute of the form should be set to the post page, the page that returns the new tree data.

The following table shows the arguments that are automatically sent when the form is posted.

Argument | Description
op | The value of this attribute is set to "custom_op". This argument, combined with the post page specified as an attribute of the form, allows specific server-side code to be executed in response to a particular invocation of the reload method. The op argument allows the same post page to process more than one operation, branching to perform different operations based on the value of this argument.

Additional arguments can be added to the form in the standard fashion: hidden input elements are embedded in the form, and the appropriate argument values are assigned to those input elements prior to the form being posted.

Custom operation elements are optional.

For more information about how the posting of forms is used to perform operations on the server, including saving changes to data, see Saving Changes to Data.

Return to XML Structure


Expression XML Structures

The expression Extensible Markup Language (XML) schema defines the form of expressions that can be used in Commerce Server 2000. The part of the expression that can be evaluated is stored as an XML string in the ExprBody field of an ActiveX Data Object (ADO) Recordset object. The Recordset objects are contained in a group of tables in the Commerce database known as the Expression Store.

This section contains:

  • Expression Recordset Schema. Describes the XML expression recordset schema.

  • Expression Body Structure. Describes the XML structure, elements, and attributes of the expression body of the expression recordset. This is the evaluable part of the recordset.

  • Data Types and Operators. Describes the valid data types and operators.

  • Intrinsics. Describes the intrinsics, which are time and date properties evaluated on the server.

  • Expression Example. Provides an example of a valid XML expression.

See Also

Expression Objects

Expression Recordset

ExpressionEval Object

ExpressionStore Object


Expression Recordset Schema

This section provides the Extensible Markup Language (XML) expression recordset schema. The evaluable part of an expression is contained in the ExprBody field of the recordset. For more information, see Expression Recordset. This schema is output when exporting expressions from the Expression Store and is required for importing expressions into the Expression Store from a file.

<xml xmlns:s='uuid:BDC6E3F0-6DA3-11d1-A2A3-00AA00C14882'
   xmlns:dt='uuid:C2F41010-65B3-11d1-A29F-00AA00C14882'
   xmlns:rs='urn:schemas-microsoft-com:rowset' xmlns:z='#RowsetSchema'>
<s:Schema id='RowsetSchema'>
   <s:ElementType name='row' content='eltOnly' rs:CommandTimeout='300'
      rs:ReshapeName='DSRowset1'>
      <s:AttributeType name='ExprID' rs:number='1'>
         <s:datatype dt:type='int' dt:maxLength='4' rs:precision='10'
            rs:fixedlength='true' rs:maybenull='false'/>
      </s:AttributeType>
      <s:AttributeType name='ExprName' rs:number='2'
         rs:writeunknown='true'>
         <s:datatype dt:type='string' dt:maxLength='30'
            rs:maybenull='false'/>
      </s:AttributeType>
      <s:AttributeType name='Category' rs:number='3' rs:nullable='true'
         rs:writeunknown='true'>
         <s:datatype dt:type='string' dt:maxLength='30'/>
      </s:AttributeType>
      <s:AttributeType name='ExprDesc' rs:number='4' rs:nullable='true'
         rs:writeunknown='true'>
         <s:datatype dt:type='string' dt:maxLength='200'/>
      </s:AttributeType>
      <s:AttributeType name='ExprBody' rs:number='5'
         rs:writeunknown='true'>
         <s:datatype dt:type='string' dt:maxLength='3400'
            rs:maybenull='false'/>
      </s:AttributeType>
      <s:AttributeType name='DateCreated' rs:number='6'
         rs:writeunknown='true'>
         <s:datatype dt:type='dateTime' rs:dbtype='timestamp'
            dt:maxLength='16' rs:scale='3' rs:precision='23'
            rs:fixedlength='true' rs:maybenull='false'/>
      </s:AttributeType>
      <s:AttributeType name='DateModified' rs:number='7'
         rs:writeunknown='true'>
         <s:datatype dt:type='dateTime' rs:dbtype='timestamp'
            dt:maxLength='16' rs:scale='3' rs:precision='23'
            rs:fixedlength='true' rs:maybenull='false'/>
      </s:AttributeType>
      <s:ElementType name='rsExprDeps' content='eltOnly'
         rs:CommandTimeout='300' rs:ReshapeName='DSRowset2'
         rs:relation='010000000100000000000000'>
         <s:AttributeType name='ExprID' rs:number='1'
            rs:writeunknown='true'>
            <s:datatype dt:type='int' dt:maxLength='4' rs:precision='10'
               rs:fixedlength='true' rs:maybenull='false'/>
         </s:AttributeType>
         <s:AttributeType name='ExprDep' rs:number='2'
            rs:writeunknown='true'>
            <s:datatype dt:type='int' dt:maxLength='4' rs:precision='10'
               rs:fixedlength='true' rs:maybenull='false'/>
         </s:AttributeType>
         <s:extends type='rs:rowbase'/>
      </s:ElementType>
      <s:ElementType name='rsProfDeps' content='eltOnly'
         rs:CommandTimeout='300' rs:ReshapeName='DSRowset3'
         rs:relation='010000000100000000000000'>
         <s:AttributeType name='ExprID' rs:number='1'
            rs:writeunknown='true'>
            <s:datatype dt:type='int' dt:maxLength='4' rs:precision='10'
               rs:fixedlength='true' rs:maybenull='false'/>
         </s:AttributeType>
         <s:AttributeType name='ProfDep' rs:number='2'
            rs:writeunknown='true'>
            <s:datatype dt:type='string' dt:maxLength='128'
               rs:maybenull='false'/>
         </s:AttributeType>
         <s:extends type='rs:rowbase'/>
      </s:ElementType>
      <s:extends type='rs:rowbase'/>
   </s:ElementType>
</s:Schema>

For more information, see Expression Recordset.


Expression Body Structure

This section describes the Extensible Markup Language (XML) structure, elements, and attributes of the expression body of the expression recordset. The expression body is the evaluable part of the recordset and is generally referred to as the expression. All elements and attributes are specified in uppercase. The only exception to this rule is the <PROPERTY> element.

In the following example, capitalized names refer to the elements of the XML structure. The first occurrence of each element is linked to documentation on that element. Names in italic are attributes associated with each element. Bold italic signifies attributes that are required. Lowercase values represent data that is contained between the opening and closing element tags.

<TERM TYPE>
   <CLAUSE OPER>
      <PROPERTY ID TYPE SUBTYPE />
      <IMMED-VAL TYPE SUBTYPE MULTIVAL>
         <VALUE>value1</VALUE>
         <VALUE>value2</VALUE>
      </IMMED-VAL>
   </CLAUSE>
   <CLAUSE OPER>
      <EXPR-REF ID />
   </CLAUSE>
   <TERM TYPE>
      <CLAUSE OPER>
         <PROPERTY ID TYPE SUBTYPE />
         <IMMED-VAL TYPE SUBTYPE MULTIVAL>immediate value</IMMED-VAL>
      </CLAUSE>
      <CLAUSE OPER>
      </CLAUSE>
   </TERM>
</TERM>

CLAUSE

CLAUSE elements are the building blocks of expressions and evaluate to either True or False. CLAUSE elements contain an operator attribute and one or two arguments listed as child elements. CLAUSE elements can be grouped together by TERM elements to create more complex expressions. A CLAUSE element along with its child elements represents one of the following operations:

  • [profile property] [operator] [immediate value]

  • [profile property] [operator] [profile property]

  • [profile property] [operator]

  • [intrinsic] [operator] [immediate value]

  • [intrinsic] [operator]

  • [expression] [operator]

Parent Elements: TERM

Child Elements: EXPR-REF, IMMED-VAL, PROPERTY

Attributes:

Name | Description
OPER | Required. Specifies the operator to be used to evaluate the child arguments.

See Also

TERM

EXPR-REF

IMMED-VAL

PROPERTY

EXPR-REF

Expressions can be built from other expressions, allowing larger, more complex expressions. Expressions are referred to by their unique IDs (an integer value), not their names. The only valid operators for the EXPR-REF element are "is-true" and "is-false".

Parent Elements: CLAUSE

Child Elements: None

Attributes:

Name | Description
ID | Required. An integer that is the ID of the expression to evaluate.

See Also

CLAUSE

IMMED-VAL

The IMMED-VAL element represents a hard-coded value used to check the preceding profile PROPERTY element against. For example, the number "25" and the string "Joe" are both immediate values. Immediate values can be either single-valued or multi-valued, and have a specific data type.

Parent Elements: CLAUSE

Child Elements: VALUE (when MULTIVAL = "True")

Data: Valid types - bool, currency, date, number, siteterm, string, time

Attributes:

Name | Description
TYPE | Required. Valid types are: bool, currency, date, datetime, number, siteterm, string, and time.
SUBTYPE | Specifies the sub-type of the property, if appropriate. For example, when TYPE = "siteterm", the value of the SUBTYPE attribute is the appropriate path for accessing the site-term in the Site Terms store. The default is "".
MULTIVAL | A bool that defaults to False. In this case, a single value is specified between the opening and closing tags. True indicates that the immediate value is multi-valued. In this case, the list of values is specified as a sequence of VALUE tags between the opening and closing tags.

See Also

CLAUSE

VALUE

PROPERTY

The PROPERTY element represents a profile property or intrinsic that is the actual data being evaluated. Profile properties can be either single-valued or multi-valued, and have a specific data type. When a profile property is specified as the only argument (child element) of a CLAUSE element, the only valid operators are "is-defined" and "not-defined". An exception to the all uppercase syntax rule, this element is specified as <Property> if an expression containing it should appear in the Campaign Expressions module in Business Desk.

Note

  • When building an expression, all profile properties in the expression must be from the same data source (for example, all from SQL Server databases, or all from Active Directory).

Parent Elements: TERM

Child Elements: CODE, EXPR-REF, IMMED-VAL, PROPERTY

Attributes:

Name | Description
ID | Required. Specifies the profile property or intrinsic.
TYPE | Required. Valid types are: bool, currency, date, datetime, number, siteterm, string, and time. A generic type is also supported for the "is-defined" and "not-defined" operators.
SUBTYPE | Specifies the sub-type of the property, if appropriate. For example, when TYPE = "siteterm", the value of the SUBTYPE attribute may be "Site Terms.Products.Cars.Colors". The default is "".

See Also

TERM

EXPR-REF

IMMED-VAL

Intrinsics

TERM

The TERM element evaluates a group of CLAUSE elements according to some logic function. Currently, the expression architecture supports the following Boolean logic operations: AND, OR, and NOT. TERM elements can be further grouped together, along with additional CLAUSE elements, to form more complex expressions.

Parent Elements: TERM

Child Elements: CLAUSE, TERM

Attributes:

Name | Description
TYPE | Required. This attribute specifies how the containing TERM elements and CLAUSE elements are logically combined. Valid values are: AND, OR, NOT

See Also

CLAUSE

VALUE

The VALUE element is used to specify the individual values of a multi-valued IMMED-VAL element.

Parent Elements: IMMED-VAL

Child Elements: None

Data: Valid types - bool, currency, date, datetime, number, siteterm, string, and time

Attributes: None

See Also

IMMED-VAL

Copyright © 1996–2000 Microsoft Corporation.
All rights reserved.


Data Types and Operators

This section describes the valid data types and operators used in the expression body of the expression recordset. An operator is applied to the child element(s) of the CLAUSE element. The following structure:

      <CLAUSE OPER>
         <PROPERTY />
         <IMMED-VAL></IMMED-VAL>
      </CLAUSE>

represents an operation of the form:

      Operator
         Argument1
         Argument2

which is easier to interpret as:

      Argument1 Operator Argument2

For example:

      <CLAUSE OPER="equal" >
         <PROPERTY ID="user.hair.color" TYPE="string" />
         <IMMED-VAL TYPE="string">"brown"</IMMED-VAL>
      </CLAUSE>

results in the evaluation of the expression:

      "user.hair.color" = "brown" ?

Data types are specified in the PROPERTY and IMMED-VAL elements, which are child elements of the CLAUSE element. The expression architecture supports the following data types: bool, currency, date, datetime, number, siteterm, string, and time. A generic data type (not recognized as from the previous list) may be used, but with a limited set of operators. For CLAUSE elements with two arguments, the data types must match.

The valid operators for each data type are specified in the following tables. The MV column specifies which arguments, if any, can be multi-valued. All operators must be specified in lowercase.

Bool

Operator | MV | Description
equal | None | Returns true if arg1 = arg2
not-equal | None | Returns true if arg1 != arg2

Currency, Number

Operator | MV | Description
equal | None | Returns true if arg1 = arg2
not-equal | None | Returns true if arg1 != arg2
greater-than | None | Returns true if arg1 > arg2
less-than | None | Returns true if arg1 < arg2
at-least | None | Returns true if arg1 >= arg2
at-most | None | Returns true if arg1 <= arg2
in | Arg2 | Returns true if arg1 appears anywhere in the list in arg2
not-in | Arg2 | Returns true if arg1 appears nowhere in the list in arg2
contains | Arg1 | Returns true if arg2 appears anywhere in the list in arg1
not-contains | Arg1 | Returns true if arg2 appears nowhere in the list in arg1
intersects | Both | Returns true if the intersection of the lists arg1 and arg2 is not the empty set
not-intersects | Both | Returns true if the intersection of the lists arg1 and arg2 is the empty set

Date, Time, Datetime

Operator | MV | Description
equal | None | Returns true if arg1 = arg2
not-equal | None | Returns true if arg1 != arg2
before | None | Returns true if arg1 is before arg2
after | None | Returns true if arg1 is after arg2
on-or-before | None | Returns true if arg1 is the same as or before arg2
on-or-after | None | Returns true if arg1 is the same as or after arg2
in | Arg2 | Returns true if arg1 appears anywhere in the list in arg2
not-in | Arg2 | Returns true if arg1 appears nowhere in the list in arg2
contains | Arg1 | Returns true if arg2 appears anywhere in the list in arg1
not-contains | Arg1 | Returns true if arg2 appears nowhere in the list in arg1
intersects | Both | Returns true if the intersection of the lists arg1 and arg2 is not the empty set
not-intersects | Both | Returns true if the intersection of the lists arg1 and arg2 is the empty set

Expression

An expression is not a data type of the PROPERTY and IMMED-VAL elements. An expression is an integer value that is evaluated as part of the EXPR-REF element. It is included in the following table for completeness in describing the available operators.

Operator | MV | Description
is-true | None | Returns true if specified expression is true
is-false | None | Returns true if specified expression is false

Generic

If a profile PROPERTY element is specified as the only argument (child element) of a CLAUSE element, any generic data type can be used with the operators listed in the following table.

Operator | MV | Description
is-defined | None | Returns true if the property is defined. Returns false if this argument is missing.
not-defined | None | Returns true if the property is not defined or if this argument is missing.

Siteterm

Operator | MV | Description
equal | None | Returns true if arg1 = arg2
not-equal | None | Returns true if arg1 != arg2
in | Arg2 | Returns true if arg1 appears anywhere in the list in arg2
not-in | Arg2 | Returns true if arg1 appears nowhere in the list in arg2
contains | Arg1 | Returns true if arg2 appears anywhere in the list in arg1
not-contains | Arg1 | Returns true if arg2 appears nowhere in the list in arg1
intersects | Both | Returns true if the intersection of the lists arg1 and arg2 is not the empty set
not-intersects | Both | Returns true if the intersection of the lists arg1 and arg2 is the empty set

String

Operator | MV | Description
equal | None | Returns true if arg1 = arg2.
not-equal | None | Returns true if arg1 != arg2.
contains | None | Returns true if arg2 appears anywhere in arg1. (For example, "Donnie" contains "nn".)
not-contains | None | Returns true if arg2 does not appear anywhere in arg1. (For example, "flintstone" does not contain "stones".)
begins-with | None | Returns true if the first part of arg2 matches arg1.
not-begins-with | None | Returns true if the first part of arg2 does not match arg1.
in | Arg2 | Returns true if arg1 appears anywhere in the list in arg2.
not-in | Arg2 | Returns true if arg1 appears nowhere in the list in arg2.
contains | Arg1 | Returns true if arg2 appears anywhere in the list in arg1.
not-contains | Arg1 | Returns true if arg2 appears nowhere in the list in arg1.
intersects | Both | Returns true if the intersection of the lists arg1 and arg2 is not the empty set.
not-intersects | Both | Returns true if the intersection of the lists arg1 and arg2 is the empty set.


Intrinsics

Intrinsics are time and date properties that are evaluated on the server. They are specified in the ID attribute of the Property element. The following table lists the available intrinsics, what they resolve to, and the data types they are evaluated against.

Name | Resolves to | Type/SubType
eee.currDate | date | date
eee.currTime | time | time
eee.currDayOfWeek | 0 - Sunday 1 - Monday 2 - Tuesday 3 - Wednesday and so on | siteterm/CalendarSiteTerms.Days (number)
eee.currMonth | 1 - January 2 - February 3 - March and so on | siteterm/CalendarSiteTerms.Months (number)
eee.currYear | number | number
eee.yesterday | date | date
eee.lastWeek | date | date
eee.lastMonth | Same as eee.currMonth | siteterm/CalendarSiteTerms.Months (number)

Internally, dates and times are handled in variant time format. For more information about the variant time format, see MSDN.

Intrinsic Examples

The following example tests whether the current day of the week is Wednesday:

      <CLAUSE OPER="equal">
         <PROPERTY ID="eee.currDayOfWeek" TYPE="siteterm" />
         <IMMED-VAL TYPE="siteterm" SUBTYPE="CalendarSiteTerms.Days">
            3</IMMED-VAL>
      </CLAUSE>

The following example tests whether 10/1/2000 is a date in the previous week (last 7 days):

      <CLAUSE OPER="on-or-before">
         <PROPERTY ID="eee.lastWeek" TYPE="date" />
         <IMMED-VAL TYPE="date">10/1/2000</IMMED-VAL>
      </CLAUSE>


Expression Example

The following example, based on a hypothetical User profile, evaluates to True for all users with the following attributes:

  • Baseball and jai alai are their favorite sports,

  • They are at least 65 years old, and

  • They either have a home area code of 425, or

  • The expression with an ID of 34 is True
<TERM TYPE="and">
   <CLAUSE OPER="in">
      <PROPERTY ID="User.FavoriteSports" TYPE="string" />
      <IMMED-VAL TYPE="string" MULTIVAL="True">
         <VALUE>baseball</VALUE>
         <VALUE>jai alai</VALUE>
      </IMMED-VAL>
   </CLAUSE>

   <TERM TYPE="and">
      <CLAUSE OPER="at-least">
         <PROPERTY ID="User.Age" TYPE="number" />
         <IMMED-VAL TYPE="number">65</IMMED-VAL>
      </CLAUSE>

      <TERM TYPE="or">
         <CLAUSE OPER="begins-with">
            <PROPERTY ID="User.ContactInfo.HomePhone" TYPE="string" />
            <IMMED-VAL TYPE="string">425</IMMED-VAL>
         </CLAUSE>
         <CLAUSE OPER="is-true">
            <EXPR-REF ID="34" />
         </CLAUSE>
      </TERM>
   </TERM>
</TERM>


Profile XML Structures

This document contains the XML representations of the profile schemas and runtime instances for the profiles (Address, Organization, and UserObject) defined in Microsoft Commerce Server 2000. The ProfileService and ProfileObject objects expose methods that return these representations.

This section contains:

  • Schemas. Shows the XML representation of the profile schemas.

  • Runtime Representations. Shows the XML runtime representation for the profiles.

See Also

Profile Objects

Profile Schema

ProfileObject Object

ProfileService Object


Schemas

This section shows the attribute-centric Extensible Markup Language (XML) schema definitions for the profiles defined in Commerce Server 2000. These definitions are identical to what is returned by the GetProfileDefXML method (with the bNamesOnly parameter set to False) of the ProfileService object, and to what is returned by the GetProfileXML method (with the eRetrieveEnum parameter set to psRetrieveSchemaOnly) of the ProfileObject object.

This section contains:

  • Address Schema. Shows the attribute-centric schema for the Address profile, which stores both user and organization addresses.

  • Organization Schema. Shows the attribute-centric schema for the Organization profile, which stores information about organizations (trading partners, home companies, subsidiaries, and so forth).

  • UserObject Schema. Shows the attribute-centric schema for the UserObject profile, which stores information about both registered and anonymous users.


Address Schema

This topic shows the attribute-centric schema for the Address profile, which stores both user and organization addresses. This schema is identical to what is returned by the GetProfileDefXML method (with the bNamesOnly parameter set to False) of the ProfileService object, and to what is returned by the GetProfileXML method (with the eRetrieveEnum parameter set to psRetrieveSchemaOnly and the bAttributeCentric parameter set to True) of the ProfileObject object.

<?xml version="1.0"?>
<ProfileDocument>
<Schema xmlns="urn:schemas-microsoft-com:xml-data"
   xmlns:dt="urn:schemas-microsoft-com:datatypes">
<ElementType name="Address">
   <attributeType name="address_id" dt:type="string" required="yes"/>
   <attributeType name="id" dt:type="string"/>
   <attributeType name="last_name" dt:type="string"/>
   <attributeType name="first_name" dt:type="string"/>
   <attributeType name="address_name" dt:type="string"/>
   <attributeType name="address_type" dt:type="int"/>
   <attributeType name="description" dt:type="string"/>
   <attributeType name="address_line1" dt:type="string" required="yes"/>
   <attributeType name="address_line2" dt:type="string"/>
   <attributeType name="city" dt:type="string"/>
   <attributeType name="region_code" dt:type="string" required="yes"/>
   <attributeType name="region_name" dt:type="string"/>
   <attributeType name="postal_code" dt:type="string" required="yes"/>
   <attributeType name="country_code" dt:type="string" required="yes"/>
   <attributeType name="country_name" dt:type="string"/>
   <attributeType name="tel_number" dt:type="string"/>
   <attributeType name="tel_extension" dt:type="string"/>
   <attributeType name="locale" dt:type="int"/>
   <attributeType name="user_id_changed_by" dt:type="string"/>
   <attributeType name="date_last_changed" dt:type="datetime"/>
   <attributeType name="date_created" dt:type="datetime"/>
<ElementType name="GeneralInfo" content="eltOnly">
   <attribute type="address_id"/>
   <attribute type="id"/>
   <attribute type="last_name"/>
   <attribute type="first_name"/>
   <attribute type="address_name"/>
   <attribute type="address_type"/>
   <attribute type="description"/>
   <attribute type="address_line1"/>
   <attribute type="address_line2"/>
   <attribute type="city"/>
   <attribute type="region_code"/>
   <attribute type="region_name"/>
   <attribute type="postal_code"/>
   <attribute type="country_code"/>
   <attribute type="country_name"/>
   <attribute type="tel_number"/>
   <attribute type="tel_extension"/>
   <attribute type="locale"/>
   <attribute type="user_id_changed_by"/>
</ElementType>
<ElementType name="ProfileSystem" content="eltOnly">
   <attribute type="date_last_changed"/>
   <attribute type="date_created"/>
</ElementType>
   <element type="GeneralInfo"/>
   <element type="ProfileSystem"/>
</ElementType>
</Schema>
</ProfileDocument>


Organization Schema

This topic shows the attribute-centric schema for the Organization profile, which stores information about organizations (trading partners, home companies, subsidiaries, and so on). This schema is identical to what is returned by the GetProfileDefXML method (with the bNamesOnly parameter set to False) of the ProfileService object, and to what is returned by the GetProfileXML method (with the eRetrieveEnum parameter set to psRetrieveSchemaOnly and the bAttributeCentric parameter set to True) of the ProfileObject object.

<?xml version="1.0"?>
<ProfileDocument>
<Schema xmlns="urn:schemas-microsoft-com:xml-data"
   xmlns:dt="urn:schemas-microsoft-com:datatypes">
<ElementType name="Organization">
   <attributeType name="org_id" dt:type="string" required="yes"/>
   <attributeType name="name" dt:type="string" required="yes"/>
   <attributeType name="trading_partner_number" dt:type="string"/>
   <attributeType name="user_id_admin_contact" dt:type="string"/>
   <attributeType name="user_id_receiver" dt:type="string"/>
   <attributeType name="org_catalog_set" dt:type="string"/>
   <attributeType name="user_id_changed_by" dt:type="string"/>
   <attributeType name="date_last_changed" dt:type="datetime"/>
   <attributeType name="date_created" dt:type="datetime"/>
   <attributeType name="user_id_purchasing_manager" dt:type="string"/>
<ElementType name="GeneralInfo" content="eltOnly">
   <attribute type="org_id"/>
   <attribute type="name"/>
   <attribute type="trading_partner_number"/>
   <attribute type="user_id_admin_contact"/>
   <attribute type="user_id_receiver"/>
   <attribute type="org_catalog_set"/>
   <attribute type="user_id_changed_by"/>
</ElementType>
<ElementType name="ProfileSystem" content="eltOnly">
   <attribute type="date_last_changed"/>
   <attribute type="date_created"/>
</ElementType>
<ElementType name="Purchasing" content="eltOnly">
   <attribute type="user_id_purchasing_manager"/>
</ElementType>
   <element type="GeneralInfo"/>
   <element type="ProfileSystem"/>
   <element type="Purchasing"/>
</ElementType>
</Schema>
</ProfileDocument>


UserObject Schema

This topic shows the attribute-centric schema for the UserObject profile, which stores information about both registered and anonymous users. This schema is identical to what is returned by the GetProfileDefXML method (with the bNamesOnly parameter set to False) of the ProfileService object, and to what is returned by the GetProfileXML method (with the eRetrieveEnum parameter set to psRetrieveSchemaOnly and the bAttributeCentric parameter set to True) of the ProfileObject object.

<?xml version="1.0"?>
<ProfileDocument>
<Schema xmlns="urn:schemas-microsoft-com:xml-data"
   xmlns:dt="urn:schemas-microsoft-com:datatypes">
<ElementType name="UserObject">
   <attributeType name="org_id" dt:type="string"/>
   <attributeType name="account_status" dt:type="int" required="yes"/>
   <attributeType name="user_catalog_set" dt:type="string"/>
   <attributeType name="date_registered" dt:type="datetime"/>
   <attributeType name="campaign_history" dt:type="string"/>
   <attributeType name="partner_desk_role" dt:type="int"/>
   <attributeType name="user_id" dt:type="string" required="yes"/>
   <attributeType name="logon_name" dt:type="string" required="yes"/>
   <attributeType name="user_security_password" dt:type="string" required="yes"/>
   <attributeType name="email_address" dt:type="string"/>
   <attributeType name="user_type" dt:type="int"/>
   <attributeType name="user_title" dt:type="string"/>
   <attributeType name="last_name" dt:type="string"/>
   <attributeType name="first_name" dt:type="string"/>
   <attributeType name="tel_number" dt:type="string"/>
   <attributeType name="tel_extension" dt:type="string"/>
   <attributeType name="fax_number" dt:type="string"/>
   <attributeType name="fax_extension" dt:type="string"/>
   <attributeType name="user_id_changed_by" dt:type="string"/>
   <attributeType name="date_last_changed" dt:type="datetime"/>
   <attributeType name="date_created" dt:type="datetime"/>
<ElementType name="AccountInfo" content="eltOnly">
   <attribute type="org_id"/>
   <attribute type="account_status"/>
   <attribute type="user_catalog_set"/>
   <attribute type="date_registered"/>
</ElementType>
<ElementType name="Advertising" content="eltOnly">
   <attribute type="campaign_history"/>
</ElementType>
<ElementType name="BusinessDesk" content="eltOnly">
   <attribute type="partner_desk_role"/>
</ElementType>
<ElementType name="GeneralInfo" content="eltOnly">
   <attribute type="user_id"/>
   <attribute type="logon_name"/>
   <attribute type="user_security_password"/>
   <attribute type="email_address"/>
   <attribute type="user_type"/>
   <attribute type="user_title"/>
   <attribute type="last_name"/>
   <attribute type="first_name"/>
   <attribute type="tel_number"/>
   <attribute type="tel_extension"/>
   <attribute type="fax_number"/>
   <attribute type="fax_extension"/>
   <attribute type="user_id_changed_by"/>
</ElementType>
<ElementType name="ProfileSystem" content="eltOnly">
   <attribute type="date_last_changed"/>
   <attribute type="date_created"/>
</ElementType>
   <element type="AccountInfo"/>
   <element type="Advertising"/>
   <element type="BusinessDesk"/>
   <element type="GeneralInfo"/>
   <element type="ProfileSystem"/>
</ElementType>
</Schema>
</ProfileDocument>


Runtime Representations

This section shows the attribute-centric Extensible Markup Language (XML) run time representations for the profiles defined in Commerce Server 2000. These representations are identical to the XML structures returned by the GetProfileXML method (with the eRetrieveEnum parameter set to psRetrieveDataOnly) of the ProfileObject object.

This section contains:

  • Address Runtime Representation. Shows the attribute-centric runtime representation for the Address profile, which stores both user and organization addresses.

  • Organization Runtime Representation. Shows the attribute-centric runtime representation for the Organization profile, which stores information about organizations (trading partners, home companies, subsidiaries, and so forth).

  • UserObject Runtime Representation. Shows the attribute-centric runtime representation for the UserObject profile, which stores information about both registered and anonymous users.


Address Runtime Representation

This topic shows the XML attribute-centric runtime representation for the Address profile, which stores both user and organization addresses. This definition is identical to the XML structures returned by the GetProfileXML method (with the eRetrieveEnum parameter set to psRetrieveDataOnly and the bAttributeCentric parameter set to True) of the ProfileObject object.

<?xml version="1.0"?>
<ProfileDocument>
<Address>
   <GeneralInfo address_id id last_name first_name address_name
      address_type description address_line1 address_line2 city
      region_code region_name postal_code country_code country_name
      tel_number tel_extension locale />
   </GeneralInfo>
   <ProfileSystem date_last_changed date_created>
   </ProfileSystem>
</Address>
</ProfileDocument>


Organization Runtime Representation

This topic shows the XML attribute-centric runtime representation for the Organization profile, which stores information about organizations (trading partners, home companies, subsidiaries, and so on). This definition is identical to the XML structures returned by the GetProfileXML method (with the eRetrieveEnum parameter set to psRetrieveDataOnly and the bAttributeCentric parameter set to True) of the ProfileObject object.

<?xml version="1.0"?>
<ProfileDocument>
<Organization>
   <GeneralInfo org_id name trading_partner_number user_id_admin_contact
      user_id_receiver org_catalog_set user_id_changed_by>
   </GeneralInfo>
   <ProfileSystem date_last_changed date_created>
   </ProfileSystem>
   <Purchasing user_id_purchasing_manager>
   </Purchasing>
</Organization>
</ProfileDocument>


UserObject Runtime Representation

This topic shows the XML attribute-centric runtime representation for the UserObject profile, which stores information about both registered and anonymous users. This definition is identical to the XML structures returned by the GetProfileXML method (with the eRetrieveEnum parameter set to psRetrieveDataOnly and the bAttributeCentric parameter set to True) of the ProfileObject object.

<?xml version="1.0"?>
<ProfileDocument>
<UserObject>
   <AccountInfo org_id account_status user_catalog_set date_registered>
   </AccountInfo>
   <BusinessDesk partner_desk_role>
   </BusinessDesk>
   <GeneralInfo user_id logon_name user_security_password email_address
      user_type user_title last_name first_name tel_number tel_extension
      fax_number fax_extension user_id_changed_by>
   </GeneralInfo>
   <ProfileSystem date_last_changed date_created>
   </ProfileSystem>
</UserObject>
</ProfileDocument>


Schema Reference

Microsoft Commerce Server 2000 uses databases in many different capacities. It is important for programmers to have knowledge of the schema employed by some of these databases.

This section contains:

  • Analysis/Reporting Schema. Describes the schema used to create reports in Commerce Server.

  • Data Warehouse Schema. Describes the classes and relations that make up the logical schema and the meta-model used to create them.

  • Predictor Schema. Describes the tables used to define a Prediction model configuration.

  • Profiles Schema. Describes the pre-defined profile schemas: Address, Organization, and UserObject.


Analysis/Reporting Schema

This topic describes the schema used to create reports in Commerce Server 2000.

The section contains:

  • Architecture. Describes the overall architecture of the Business Analytics System.

  • Parameterization. Describes the parameters used to create the parameterized queries in static reports.

  • Report Tables. Describes the tables used to create reports and their relations.

See Also

Analysis/Reporting XML Structures

AsyncRpt Object

Creating Custom Reports

ReportRender Object

Running Reports


Architecture

Analysis and reporting in Commerce Server 2000 is built on an open architecture designed to allow total content control by business managers. The business manager is free to add, delete, and modify report content. Multiple Data Warehouse and Online Analytical Processing (OLAP) data sources may be used by changing connection strings in Commerce Server Manager. The system administrator performs this task.

Reports are implemented as static or dynamic, and are based on either SQL or multidimensional expresssion (MDX) queries of SQL or OLAP databases, respectively. Static reports are HTML-based; dynamic reports are based on Microsoft Office 2000 Web Components (OWC).

Static report definitions consist of a query and parameter definitions. When a static report is run, the parameters are presented to the operator and then passed to a rendering component. The rendering component generates an HTML document from the query results. Completed static reports are stored as HTML files on the computer that houses Commerce Server Business Desk. These reports can be opened through Business Desk and are displayed in Microsoft Internet Explorer.

Dynamic report definitions are stored as queries, and the pivot table view is stored in Extensible Markup Language (XML) in the Data Warehouse. Query results are displayed in the OWC Pivot Table component.

Definitions for the pre-defined reports are contained in the file CSReports.sql found in the Commerce Server installation directory. The CSReports.sql file populates the Report tables in the Commerce Server Data Warehouse. A "Report preparation DTS" task is available to process OLAP cubes and execute stored procedures to prepare imported data for reporting.


Parameterization

This section describes the parameters and constants used to create the parameterized query entries in the ReportParam table.

This section contains:

  • Parameter Types. Describes the available parameter types and their valid operands and values.

  • Constants. Lists the constants available for use in creating reports.


Parameter Types

The following table lists the available parameter types and their valid operands and values. The SingleValue parameter type can appear anywhere in a query. The SelectOrder parameter type is used in the Select clause of the query. The remaining parameter types appear in the Where clause of the query.

Paramtype Operand1 Value1 Operand2 Value2
ParamType_DateRange DateRangeOpnd_All

DateRangeOpnd_From

DateRangeOpnd_OnOrBefore

DateRangeOpnd_Today

DateRangeOpnd_ThisWeek

DateRangeOpnd_ThisMonth

DateRangeOpnd_ThisQuarter

DateRangeOpnd_ThisYear

DateRangeOpnd_Yesterday

DateRangeOpnd_LastWeek

DateRangeOpnd_LastMonth

DateRangeOpnd_LastQuarter

DateRangeOpnd_LastYear

 Required for DateRangeOpnd_From or DateRangeOpnd_OnOrB4.

For DateRangeOpnd_From, the beginning date of a range to return.

For DateRangeOpnd_OnOrB4, the last date to include.

Not applicable for the other operand types.

Date format = MM/DD/YYYY

 Not applicable. Required for DateRangeOpnd_From.

The end date of a range to return.

Not applicable for the other operand types.
ParamType_Expression ExpOpnd_None

ExpOpnd_Equals

ExpOpnd_NotEquals

ExpOpnd_IsNull

ExpOpnd_IsNotNull

ExpOpnd_LessThan*

ExpOpnd_LessThanOrEquals*

ExpOpnd_GreaterThan*

ExpOpnd_GreaterThanOrEquals*

ExpOpnd_Like#

ExpOpnd_NotLike#

-------------------------

* - only used for numeric types.

# - only used for String types

 Not applicable for ExpOpnd_None.

Required for the other ParamTypes.

Valid types are:

  • Currency

  • Float

  • Integer

  • String
 Same operand types as Operand1.

Not applicable for ExpOpnd_None.

Optional for the other operand types.

Required if Operand2 is specified.
ParamType_SelectOrder SelectOrderOpnd_All*

SelectOrderOpnd_Distinct*

SelectOrderOpnd_Top

SelectOrderOpnd_Bottom#

-------------------------

* - SQL only

# - MDX only

 Required for SelectOrderOpnd_Top or SelectOrderOpnd_Bottom.

An Integer specifying the number of rows to return.

Not applicable for SelectOrderOpnd_All.

 Not applicable. Not applicable.
ParamType_SingleValue Not applicable Required String value.

The value for this operand is a text field that can accommodate any type of entry. Two examples are: booleanVal = "True" and Time = "12:59:59".

 Not applicable. Not applicable.
ParamType_SiteName
(SQL query only) 		SiteNameOpnd_All

SiteNameOpnd_Equals

SiteNameOpnd_NotEquals

SiteNameOpnd_Like

SiteNameOpnd_NotLike

 Not applicable for SiteNameOpnd_All.

Required String value for the others.

 Not applicable. Not applicable.


Constants

The following tables list the constants defined in the CSReports.sql file for use in creating parameterized reports.

  • DataType

  • ParamType

  • ParamType_DateRange Operand

  • ParamType_Expression Operand

  • ParamType_SelectOrder Operand

  • ParamType_SiteName Operand

DataType

The following table lists the valid data types.

Data type | Value
DataType_date | 1
DataType_integer | 2
DataType_float | 3
DataType_currency | 4
DataType_text | 5

ParamType

The following table lists the valid parameter types. The Constraint column lists where the parameter type is used in the query.

Parameter type | Value | Constraint
ParamType_SingleValue | 0 | Anywhere
ParamType_Expression | 1 | WHERE clause
ParamType_SelectOrder | 2 | SELECT clause
ParamType_DateRange | 3 | WHERE clause
ParamType_SiteName | 4 | WHERE clause

ParamType_DateRange Operand

The following table lists the valid date range operands.

Operand | Value
DateRangeOpnd_All | 0
DateRangeOpnd_From | 1
DateRangeOpnd_OnOrBefore | 2
DateRangeOpnd_Today | 3
DateRangeOpnd_ThisWeek | 4
DateRangeOpnd_ThisMonth | 5
DateRangeOpnd_ThisQuarter | 6
DateRangeOpnd_ThisYear | 7
DateRangeOpnd_Yesterday | 8
DateRangeOpnd_LastWeek | 9
DateRangeOpnd_LastMonth | 10
DateRangeOpnd_LastQuarter | 11
DateRangeOpnd_LastYear | 12

ParamType_Expression Operand

The following table lists the valid expression operands.

Operand | Value | Constraint
ExpOpnd_None | 0 | None
ExpOpnd_Equals | 1 | None
ExpOpnd_NotEquals | 2 | None
ExpOpnd_IsNull | 3 | None
ExpOpnd_IsNotNull | 4 | None
ExpOpnd_LessThan | 5 | Numeric data types only
ExpOpnd_LessThanOrEquals | 6 | Numeric data types only
ExpOpnd_GreaterThan | 7 | Numeric data types only
ExpOpnd_GreaterThanOrEquals | 8 | Numeric data types only
ExpOpnd_Like | 9 | Char data type only
ExpOpnd_NotLike | 10 | Char data type only

ParamType_SelectOrder Operand

The following table lists the valid select order operands.

Operand | Value | Constraint
SelectOrderOpnd_All | 0 | SQL only
SelectOrderOpnd_Distinct | 1 | SQL only
SelectOrderOpnd_Top | 2 | SQL and MDX
SelectOrderOpnd_Bottom | 3 | MDX only

ParamType_SiteName Operand

The following table lists the valid site name operands. This operand is applicable only for SQL queries.

Operand | Value
SiteNameOpnd_All | 0
SiteNameOpnd_Equals | 1
SiteNameOpnd_NotEquals | 2
SiteNameOpnd_Like | 3
SiteNameOpnd_NotLike | 4


Report Tables

The following figure identifies the report tables and their relations. Each table is described in the subsequent sections. Lastly, a table is presented showing which report tables are used for each report type.

Reporting Schema

Report
Instance
DbObject
Report
Instance
Param
Report
DbObject
Report
Status
Report
Param
Report
Dimension
Report

This section contains:

  • Report Table. Describes the attributes used in the main report definition table.

  • ReportDbObject Table. Describes database objects created for use in a static report.

  • ReportDimension Table. Describes the attributes used to add a dimension to a report.

  • ReportInstanceDbObject Table. Describes instances of database objects created for use in a static report.

  • ReportInstanceParam Table. Describes the attributes used to store the parameters entered through the user interface for use in query expressions.

  • ReportParam Table. Describes the attributes used to add a parameterized query expression to a static report.

  • ReportStatus Table. Describes the attributes used to supply status information about a static report.

  • Table Usage by Report Type. Describes report table usage by report type.


Report Table

The following table describes the attributes used in the main report definition table.

Attribute name | Data type | Constraint | Default | Description
ReportID | int | None | None | Identity.
AggregationType | tinyint | NULL | None | Not used.
Category | nvarchar (128) | NULL | None | Category of the report.
ChartType | int | None | 3 | See table immediately following.
CommerceBuild | nvarchar (128) | NULL | None | Commerce Server build number.
CreatedBy | nvarchar (128) | NULL | None | Name of the user who created the report.
CreatedTime | datetime | NULL | getdate() | Date and time the report was created.
Definition | ntext (16) | NULL | None | Long description.
Description | nvarchar (128) | NULL | None | Additional information.
DisplayName | nvarchar (128) | NULL | None | Name displayed in the user interface.
DmExport | bit | None | False (0) | True (1) specifies the report is exportable to Direct Mail.
LastModifiedBy | nvarchar (128) | NULL | None | Name of the user who last modified the report.
LastRunBy | nvarchar (128) | NULL | None | Name of the user who last ran the report.
LastRunDateTime | datetime | NULL | None | Date and time the report was last run.
MajorVersion | int | NULL | None | None.
MinorVersion | int | NULL | None | None.
ModifiedTime | datetime | NULL | None | Date and time the report was last modified.
Private | bit | None | False (0) | Not used.
Protected | bit | None | False (0) | True (1) indicates the report may not be overwritten or deleted. True for all system reports.
Query | nvarchar (2000) | NULL | None | The executable SQL or MDX query.
ReportType | tinyint | NULL | None | See table immediately following.
SeriesInColumns | bit | None | True (1) | Inverts the chart (swaps x and y).
ShowChart | bit | None | False (0) | True indicates to show the chart.
ShowLegend | bit | None | True (1) | True indicates to show the chart legend.
ShowPivot | bit | None | True (1) | True indicates to show the pivot control.
UPMExport | bit | None | False (0) | True (1) specifies the report is exportable to User Personalization.
XMLData | ntext (16) | NULL | None | PivotTable XML data.

Chart Types

Most Microsoft Office 2000 Web Components charts can be used. The following table lists a few of the more common chart types. ChartType Enum constants can be found in the file MSOWCVBA.CHM in the folder \Program Files\Microsoft Office\Office\1033 after a full Microsoft Office installation.

ChartType | Value
Column: Clustered | 0
Bar: Clustered | 3
Line | 6
Pie | 18

Report Types

The following table lists the valid report types.

ReportType | Value
Dynamic_SQL | 0
Dynamic_MDX | 1
Static_SQL | 2
Static_MDX | 3


ReportDbObject Table

The following table describes database objects created for use in a static report.

Attribute name | Data type | Constraint | Default | Description
ReportDbObjectID | int | None | None | Identity.
ReportID | int | NOT NULL | None | ID of the report the object is associated with.
DbObjectBaseName | nvarchar (128) | NULL | None | Name of the table or view.
DbObjectDDL | ntext (16) | NULL | None | SQL query to run to create additional database objects used in the actual report query.
DbObjectType | nvarchar (128) | NULL | None | 0 = Table 1 = TempTable 2 = View


ReportDimension Table

The following table describes the attributes used to add a dimension to a static report.

Attribute name | Data type | Constraint | Default | Description
ReportID | int | NOT NULL | None | ID of the report the dimension is associated with.
AggregationType | tinyint | None | 0 | Maps to aggregation types used by the CalcRenderer object.
DimensionType | tinyint | NOT NULL | None | 0 = Column 1 = Row 2 = Measure
DisplayName | nvarchar (128) | NULL | None | Name displayed in the user interface.
FieldName | nvarchar (128) | NOT NULL | None | Field name in report query result.
Ordinal | tinyint | NOT NULL | None | Used to specify the user interface rendering order.


ReportInstanceDbObject Table

The following table describes instances of database objects created for use in a static report. This table is created at report run time.

Attribute name | Data type | Constraint | Default | Description
ReportDbObjectID | int | NULL | None | ID of the report database object the dimension is associated with.
ReportStatusID | int | NOT NULL | None | ID of the report status.
DateCreated | datetime | NOT NULL | None | Date and time the object was instantiated.
DbObjectInstanceName | nvarchar (128) | NULL | None | Name of the table or view.
DbObjectType | nvarchar (128) | NULL | None | 0 = Table 1 = TempTable 2 = View


ReportInstanceParam Table

The following table stores an instance of the parameterized query expression. This table is created at report run time.

Attribute name | Data type | Constraint | Default | Description
ReportStatusID | int | NOT NULL | None | ID of the report status.
ParamName | nvarchar (128) | NULL | None | Tag name.
ParamType | tinyint | NULL | None | Type of parameter.
DataType | nvarchar (128) | NULL | None | Data type of Val1 and Val2. 0 = int 1 = float 2 = datetime 3 = char
Opnd1 | tinyint | NULL | 0 | First operand.
Val1 | nvarchar (128) | NULL | None | First value.
Opnd2 | tinyint | NULL | 0 | Second operand.
Val2 | nvarchar (128) | NULL | None | Second value.
FieldName | nvarchar (128) | NULL | None | Field in query used for expression.
Ordinal | tinyint | NULL | None | Used to specify the user interface rendering order.
AllowNull | bit | NOT NULL | False (0) | Reserved for future use.
Automatic | bit | NOT NULL | False (0) | Reserved for future use.


ReportParam Table

The following table describes the attributes used to create a parameterized query for a static report.

Attribute name | Data type | Constraint | Default | Description
ReportID | int | NOT NULL | None | ID of the report with which the parameter is associated.
ParamName | nvarchar (128) | NOT NULL | None | Tag name.
ParamDescription | nvarchar (128) | NOT NULL | None | Text displayed on the clickable bar.
ParamType | tinyint | NOT NULL | 0 | Type of parameter.
DataType | tinyint | NULL | None | Data type of Val1 and Val2. 0 = int 1 = float 2 = datetime 3 = char
Opnd1 | tinyint | NULL | None | First operand.
Val1 | nvarchar (128) | NULL | None | First value.
Opnd2 | tinyint | NULL | None | Second operand.
Val2 | nvarchar (128) | NULL | None | Second value.
FieldName | nvarchar (128) | NULL | None | Field in query used for expression.
Ordinal | tinyint | NULL | None | Used to specify the user interface rendering order.
AllowNull | bit | NOT NULL | False (0) | Reserved for future use
Automatic | bit | NOT NULL | False (0) | Reserved for future use.


ReportStatus Table

The following table describes the attributes used to supply status information about a report. This table is created at report run time.

Attribute name | Data type | Constraint | Default | Description
ReportStatusID | int | None | None | Identity.
ReportID | int | NULL | None | ID of the report with which the status is associated.
DisplayName | nvarchar (128) | NULL | None | Name displayed in the user interface.
ExecutionState | tinyint | NOT NULL | 0 | 0 = None 1 = Failed 2 = Pending 3 = Completed
Exported | bit | NULL | False (0) | True specifies the report was exported.
LocationName | nvarchar (255) | NULL | None | Name of the report.
LocationPath | nvarchar (255) | NULL | None | Path to the report.
RunBy | varchar (255) | NULL | None | Name of the person running the report.
RunDateTime | datetime | NULL | None | Date the report was run.


Table Usage by Report Type

The following table shows which report tables are used to create the different report types.

Report type | StaticSQL | StaticMDX | DynamicSQL | DynamicMDX
Design time table |  |  |  |
Report | X | X | X | X
ReportDbObject | X |  |  |
ReportDimension | X |  |  |
ReportParam | X | X |  |
Run time table |  |  |  |
ReportInstanceDbObject | X |  |  |
ReportInstanceParam | X | X |  |
ReportStatus | X | X |  |


Data Warehouse Schema

The Commerce Server 2000 Data Warehouse uses a logical schema to isolate applications from the underlying physical database. The basic structures of the logical schema are the class, data member, relation, and key. A meta-model containing a set of attributes (meta-data) is used to define these basic structures. Detailed knowledge of the logical schema is only needed when extending the schema to encompass a third-party data structure.

This section contains:

  • Data Warehouse Classes. Lists in alphabetical order the conceptual (logical) classes in the Data Warehouse.

  • Data Warehouse Meta-model. Describes the meta-model used to define the classes, data members, class relations, and class keys of the Data Warehouse.

  • Physical Schema. Describes the logical-to-physical mapping of the conceptual data to the underlying data store.

See Also

  • Working with the Data Warehouse


Data Warehouse Classes

This section provides an alphabetical list of the Commerce Server 2000 Data Warehouse logical classes. Information about the class data members, class relations, and class keys is included. The physical classes corresponding to these logical classes can be found in the Microsoft Management Console (MMC) under Microsoft SQL Servers\SQL Server Group\<server name>\Databases\<data warehouse database>\Tables.

The following table contains the relation types and the corresponding type codes used in the Relations table of each class description.

Relation Type | Code | Description
One-to-many | 2 | Each parent has zero or more children, each child has one parent. The identifier ("Classname"ID) of the parent is used as a foreign key by the child.
Many-to-many | 3 | Each parent has zero or more children, each child has one or more parents.
One-to-many with inheritance | 194 | Same as a one-to-many relation except all members of the parent are visible to the children. (In a regular one-to-many relation, only the key members of the parent class are visible.)

Commerce Server 2000 Data Warehouse Logical Classes

The following table contains links to the logical classes of the Data Warehouse.

Address | HttpStatus | Referrer
AdItem | ImportOptions | ReferrerDomain
Basket | IndustryCode | RegisteredUser
Campaign | IPRef | Request
CampaignEvent | LastUriByDate | RequestByDateByUriBy QueryString
CampaignEventsByDate AndUser | Level1Dir | ServerBinding
CampaignItem | Level2Dir | ServerGroup
CampaignItemTypes | Level3Dir | Site
CatalogGlobal | Level4Dir | SiteSummary
Category | Level5Dir | SiteURL
CatHierarchy | Level6Dir | SVQStringName
CommerceEvent | LinkMVQString Name | Target
Crawler | LinkSVQStringName | TargetGroup
Creative | LogUser | TargetGroupXRef
CreativeSize | MVQStringName | TaskHistory
CreativeType | OpenUserVisit | UniqueUserKey ByDate
CreativeTypeXRef | Order | URI
Customer | OrderDiscount | URIQuery
Date | OrderFormHeader | UserAgent
DMItem | OrderFormLine Items | VirtualServer
EventType | OrderGroup | Visit
FirstUriByDate | OrderGroupAddresses | VisitInfo
HitsByHour | PageGroup | Win32Status
HitsInfo | PageGroupXRef |
HostnameRef | Products


Address

This class stores user and organization addresses. By default, the Commerce Server 2000 User Profile Data Import Data Transformation Services (DTS) task imports profile data into this class.

Data Members

Data Member Name | Data Type | Default Value | Description
AddressName | WSTR | None | None
AddressType | LONG | None | 0 – Address 1 – ShipTo address 2 – BillTo address
City | WSTR | None | None
CountryCode | WSTR | None | Stores the country (ISO) code.
CountryName | WSTR | None | None
DateCreated | FILETIME | None | None
DateLastChanged | FILETIME | None | None
FirstName | WSTR | None | Stores the first name of the user.
Id | UUID | {00000000-0000-0000-0000-000000000000} | Stores the unique key for the object.
LastName | WSTR | None | Stores the last name of the user.
PostalCode | WSTR | None | Stores the postal or ZIP Code.
RegionCode | WSTR | None | None
RegionName | WSTR | None | Stores the state or region name.
SiteName | WSTR | Not available | None
TelephoneExtension | WSTR | None | None
TelephoneNumber | WSTR | None | None

Class Key

AddressKey is composed of a single data member, Id.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
AddressUserRel | Address | RegisteredUser | 2
SiteAddressRel | Site | Address | 3


AdItem

This class represents scheduled advertising content for a Web page. The class contains data members describing when the advertisement runs and codes linking the advertisement to the products it represents. The IndustryCode class provides a classification of the type of advertisement contained in the AdItem object.

Data Members

Data Member Name | Data Type | Default Value | Description
AdItemCustomerOrderNum | WSTR | None | Stores the code used by customers to order through the advertisement.
AdItemDaysOfWeekMask | SHORT | None | Indicates which days of the week the advertisement was shown.
AdItemEventsScheduled | LONG | None | Stores the number of scheduled events associated with the advertisement.
AdItemNum | LONG | 0 | Stores the unique key for the object.
AdItemTimeOfDayEnd | SHORT | None | Indicates the time of day the advertisement stopped being displayed.
AdItemTimeOfDayStart | SHORT | None | Indicates the time of day the advertisement started being displayed.
AdItemType | SHORT | None | Stores the type of advertisement.
AdItemWeight | LONG | None | Stores the relative importance of the advertisement.
CampItemNum | LONG | 0 | None
IndustryNum | LONG | 0 | None
SiteName | WSTR | None | Stores the name of the site associated with the advertisement.

Class Key

AdItemKey is composed of a single data member, AdItemNum.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
AdItemCampaignItem | CampaignItem | AdItem | 2
AdItemIndustryCode | IndustryCode | AdItem | 2


Basket

This class represents the business transaction involved in adding or removing a product from a shopping basket.

Data Members

Data Member Name | Data Type | Default Value | Description
EventName | WSTR | Not available | None
ProductNameCat | WSTR400 | Not available | None
SiteName | WSTR | Not available | None
TaskID | LONG | 0 | None
TimeStamp | FILETIME |  | None
URI | WSTR | Not available | None
UserId | WSTR | Not available | None
UserKey | UUID | {00000000-0000-0000-0000-000000000000} | None
VisitNum | IDENTITY | 0 | None

Class Key

No key is defined for this class. It is a dependent class.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
DateBasketTimeStamp | Date | Basket | 2
EventTypeBasketRel | EventType | Basket | 2
LogUserBasketRel | LogUser | Basket | 2
ProductsBasketRel | Products | Basket | 2
RegisteredUserBasketRel | RegisteredUser | Basket | 2
SiteBasket | Site | Basket | 2
TaskHistoryBasket | TaskHistory | Basket | 2
UriBasket | URI | Basket | 2


Campaign

This class defines the business process involved in running a marketing campaign for an advertiser. The Campaign class associates a customer (advertiser) with a set of CampaignItem objects (advertisements, discounts, direct mailings, or related sell items). A Campaign object is associated with an EventType object, which describes the marketing event.

A Customer object may have multiple Campaign objects associated with it; this represents multiple advertising campaigns for the customer over time. A Campaign may contain multiple sets of content items (CampaignItem objects). Each set of content items, in turn, may have multiple items (for example, AdItem objects), and may target multiple user groups. Finally, a Web page may contain multiple content items, and a content item may be included in multiple, distinct pages. All of these possibilities are represented through the one-to-many relations between classes.

Data Members

Data Member Name | Data Type | Default Value | Description
CampActive | SHORT | None | None
CampaignExported | FILETIME | None | Records when the Campaign object was exported.
CampaignModified | FILETIME | None | Records when the Campaign object was last modified.
CampaignModifiedBy | WSTR | None | Stores who last modified the Campaign object.
CampArchived | FILETIME | None | Records when the Campaign object was archived.
CampEnd | FILETIME | None | Records when the Campaign object was discontinued.
CampEventsSched | LONG | None | Stores the number of campaign events scheduled for the Campaign object.
CampLevelGoal | SHORT | None | None
CampName | WSTR | None | Stores the name of the Campaign object.
CampNum | LONG | 0 | Stores the unique key for the Campaign object.
CampStart | FILETIME | None | Records when the Campaign object became active.
CustomerComments | WSTR | None | Stores any comments made by the customer associated with the Campaign object.
CustomerNum | LONG | 0 | None
EventName | WSTR | Not available | None
SiteName | WSTR | None | Stores the name of the site associated with the Campaign object.

Class Key

CampaignKey is composed of a single data member, CampNum.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
CampaignCustomer | Customer | Campaign | 2
CampaignEventType | EventType | Campaign | 2
CampaignItemCampaign | Campaign | CampaignItem | 2


CampaignEvent

This class stores event information for marketing campaigns. An event for a marketing campaign includes hits on CampaignItem objects and business transactions involving CampaignItem objects.

Data Members

Data Member Name | Data Type | Default Value | Description
CampItemNum | LONG | 0 | None
CNT | WSTR | None | Records the number of Web events represented by the CampaignEvent object.
EventName | WSTR | Not available | None
EX | WSTR | None | None
PgNum | LONG | 0 | None
SiteName | WSTR | Not available | None
TaskID | LONG | 0 | None
TimeStamp | FILETIME |  | None
URI | WSTR | Not available | None
UserId | WSTR | Not available | None
UserKey | UUID | {00000000-0000-0000-0000-000000000000} | None
VisitNum | IDENTITY | 0 | None

Class Key

No key is defined for this class. It is a dependent class.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
CampaignItemCampaignEventRel | CampaignItem | CampaignEvent | 2
DateCampaignEventTimeStamp | Date | CampaignEvent | 2
EventTypeCampaignEventRel | EventType | CampaignEvent | 2
LogUserCampaignEventRel | LogUser | CampaignEvent | 2
PageGroupCampaignEventRel | PageGroup | CampaignEvent | 2
RegisteredUserCampaignEventRel | RegisteredUser | CampaignEvent | 2
SiteCampaignEvent | Site | CampaignEvent | 2
TaskHistoryCampaignEvent | TaskHistory | CampaignEvent | 2
UriCampaignEvent | URI | CampaignEvent | 2


CampaignItem

This class represents the content included in a marketing campaign (a Campaign object) and/or a scheduled advertisement (a Creative object). The content is represented by one or more of the following objects: AdItem, DmItem, or OrderDiscount.

A CampaignItem object may belong to a specific type of campaign item, specified by a link to a CampaignItemTypes object.

The content items may target specific groups of users; if this occurs, the CampaignItem object links to one or more TargetGroupXRef objects. The TargetGroupXRef class cross-references custom content items with targeted user groups.

Finally, the content items may be part of a Web page presenting multiple groups of custom content. A PageGroupXRef object cross-references the CampaignItem object with the page or pages containing the items.

A CampaignItem object may have multiple content items (for example, AdItem objects), and may target multiple user groups. A Web page may contain multiple content items, and a content item may be included in multiple, distinct pages. All of these possibilities are represented through the one-to-many relationships between classes.

Data Members

Data Member Name | Data Type | Default Value | Description
Active | SHORT | None | Records if the CampaignItem object is active.
ArchivedDate | FILETIME | None | Records when the CampaignItem object was archived.
CampItemNum | LONG | 0 | Stores the unique key for the CampaignItem object.
CampNum | LONG | 0 | None
Comments | WSTR | None | Records any comments regarding the objects.
CreativeNum | LONG | 0 | None
EndDate | FILETIME | None | Records when the CampaignItem object was discontinued.
ExportedDate | FILETIME | None | Records when the CampaignItem object was exported.
ExposureLimit | LONG | None | None
GUIDCampItemType | UUID | {00000000-0000-0000-0000-000000000000} | None
ModifiedBy | WSTR | None | Records who last modified the CampaignItem object.
ModifiedDate | FILETIME | None | Records when the CampaignItem object was last modified.
Name | WSTR | None | Stores the name of the CampaignItem object.
SiteName | WSTR | None | Records the name of the site associated with the CampaignItem object.
StartDate | FILETIME | None | Records when the CampaignItem object was activated.

Class Key

CampaignItemKey is composed of a single data member, CampItemNum.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
AdItemCampaignItem | CampaignItem | AdItem | 2
CampaignItemCampaign | Campaign | CampaignItem | 2
CampaignItemCampaignEventRel | CampaignItem | CampaignEvent | 2
CampaignItemCampaignItemEventsByDateAndUser | CampaignItem | CampaignItemEventsByDateAndUser | 2
CampaignItemCampaignItemTypes | CampaignItemTypes | CampaignItem | 2
CampaignItemCreative | Creative | CampaignItem | 2
CampaignItemPageGroupXrefRel | CampaignItem | PageGroupXref | 2
CampaignItemTargetGroupXrefRel | CampaignItem | TargetGroupXref | 2
DmItemCampaignItem | CampaignItem | DmItem | 2
OrderDiscountCampaignItem | CampaignItem | OrderDiscount | 2


CampaignItemEventsByDateAndUser

This class represents a summarization of campaign event data grouped by date and user.

Data Members

Data Member Name | Data Type | Default Value | Description
CampaignEventsCount | LONG | 0 | None
CampItemNum | LONG | 0 | Key member
EventName | WSTR | Not available | Key member
SiteName | WSTR | Not available | Key member
TaskID | LONG | 0 | Key member
TimeStamp | FILETIME | 1900-1-1 0:0:0.0 | Key member
userKey | UUID | {00000000-0000-0000-0000-000000000000} | Key member

Class Key

CampaignItemEventsByDateAndUserKey is composed of the following data members:

CampItemNum + EventName + SiteName + TaskID + TimeStamp +userKey

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
CampaignItemCampaignItemEventsByDateAndUser | CampaignItem | CampaignItemEventsByDateAndUser | 2
DateCampaignItemEventsByDateAndUser | Date | CampaignItemEventsByDateAndUser | 2
EventTypeCampaignItemEventsByDateAndUser | EventType | CampaignItemEventsByDateAndUser | 2
LogUserCampaignItemEventsByDateAndUser | LogUser | CampaignItemEventsByDateAndUser | 2
SiteCampaignItemEventsByDateAndUser | Site | CampaignItemEventsByDateAndUser | 2
TaskHistoryCampaignItemEventsByDateAndUser | TaskHistory | CampaignItemEventsByDateAndUser | 2


CampaignItemTypes

This class represents categories for custom Web page content. A CampaignItemTypes object links to zero or more CampaignItem objects.

Data Members

Data Member Name | Data Type | Default Value | Description
CampItemTypeName | WSTR | None | Stores the name of the item type.
CampItemTypeTable | WSTR | None | None
GUIDCampItemType | UUID | {00000000-0000-0000-0000-000000000000} | Stores the unique key for the object.
SiteName | WSTR | None | Stores the name of the site associated with the item type.

Class Key

CampaignItemTypesKey is composed of a single data member, GUIDCampItemType.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
CampaignItemCampaignItemTypes | CampaignItemTypes | CampaignItem | 2
CampaignItemTypesCreativeTypeXrefRel | CampaignItemTypes | CreativeTypeXref | 2


CatalogGlobal

This class represents a global catalog that stores other catalogs.

Data Members

Data Member Name | Data Type | Default Value | Description
CatalogName | WSTR | Not available | Stores the unique key (name) of the object.
Currency | WSTR | None | Not used by the Catalog system.
EndDate | DATETIME | None | Not used by the Catalog system.
Locale | LONG | None | Not used by the Catalog system.
ProductID | WSTR | None | The name of the column in the catalog that stores the ProductID.
SiteName | WSTR | Not available | None
StartDate | DATETIME | None | Not used by the Catalog system.
VariantID | WSTR | None | The name of the column in the catalog that stores the VariantID. If NULL, product variants are not supported.
WeightMeasure | WSTR | None | Not used by the Catalog system.

Class Key

CatalogGlobalKey is composed of a single data member, CatalogName.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
CatalogSite | Site | CatalogGlobal | 3


Category

This class represents a category of a sales catalog.

Data Members

Data Member Name | Data Type | Default Value | Description
CatalogName | WSTR | Not available | Stores the catalog name.
CategoryName | WSTR | Not available | Stores the category name.
CategoryNameCat | WSTR400 | Not available | Stores the unique key (catalog name concatenated with category name) for the object.

Class Key

CategoryKey is composed of a single data member, CategoryNameCat.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
Category | Category | Products | 3


CatHierarchy

This class represents a level of a hierarchical sales catalog.

Data Members

Data Member Name | Data Type | Default Value | Description
ChildCategoryCat | WSTR400 | Not available | Stores the catalog name concatenated with the child category name.
ParentCategoryCat | WSTR400 | Not available | Stores the catalog name concatenated with the parent category name.

Class Key

CatHierarchyKey is composed of the following data members:

ParentCategoryCat + ChildCategoryCat

Relations

No relations are defined for this class.


CommerceEvent

This class represents the mappings between commerce events and the logical classes that store the event data. Commerce events are specially structured query strings written by Commerce Server components.

Note

  • Two different class members should not point to the same storage member.

Data Members

Data Member Name | Data Type | Default Value | Description
CommerceEventClassName | WSTR | None | Stores the name of the event class.
CommerceEventMemberName | WSTR | None | Stores the name of the event member.
StorageClassName | WSTR | None | Stores the name of the storage class.
StorageMemberName | WSTR | None | Stores the name of the storage member.

Class Key

No key is defined for this class. It is a dependent class.

Relations

No relations are defined for this class.


Crawler

This class represents a Web crawler associated with a site. The Crawler object links to a Site object. A Site object may have more than one Crawler objects linked to it.

Data Members

Data Member Name | Data Type | Default Value | Description
CrawlerString | WSTR | Not available | Key member
SiteName | WSTR | Not available | Key member

Class Key

CrawlerKey is composed of the following data members:

CrawlerString + SiteName

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
SiteCrawlerRel | Site | Crawler | 2


Creative

This class defines the business process involved in scheduling Web content for a customer (for example, an advertiser). The type of content is recorded by a link to a CreativeType object. One or more CampaignItem objects describe the scheduled content; this content includes advertisements, discounts, related sell items, or direct mailings. A CreativeSize object defines the area of the Web page used to contain the content.

A Customer object may have multiple Creative objects associated with it; this represents multiple advertisements for the customer over time. A Creative advertisement may contain multiple sets of content items (CampaignItem objects). Each set of content items, in turn, may have multiple items (for example, AdItem objects), and may target multiple user groups. Finally, a Web page may contain multiple content items, and a content item may be included in multiple, distinct pages. All of these possibilities are represented through the one-to-many relationships between classes.

Data Members

Data Member Name | Data Type | Default Value | Description
CreativeNum | LONG | 0 | Stores the unique key for the Creative object.
CreativeReceived | FILETIME | None | None
CreativeSizeNum | LONG | 0 | None
CreativeTypeNum | LONG | 0 | None
CustomerNum | LONG | 0 | None
SiteName | WSTR | None | Stores the name of the site associated with the Creative object.

Class Key

CreativeKey is composed of a single data member, CreativeNum.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
CampaignItemCreative | Creative | CampaignItem | 2
CreativeCustomer | Customer | Creative | 2
CreativeSizeCreative | CreativeSize | Creative | 2
CreativeTypeCreative | CreativeType | Creative | 2


CreativeSize

This class represents the size of custom content on a Web page. A CreativeSize object links to one or more Creative objects.

Data Members

Data Member Name | Data Type | Default Value | Description
CreativeSizeNum | LONG | 0 | Stores the unique key for the object.
SiteName | WSTR | None | Stores the name of the site associated with the object.
SizeHeight | SHORT | None | Stores the height (in pixels) of the custom content size.
SizeName | WSTR | None | Stores the name of the custom content size object.
SizeTag | WSTR | None | Stores the tag associated with the custom content size.
SizeWidth | SHORT | None | Stores the width (in pixels) of the custom content size.

Class Key

CreativeSizeKey is composed of a single data member, CreativeSizeNum.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
CreativeSizeCreative | CreativeSize | Creative | 2


CreativeType

This class categorizes custom content for Web pages. A CreativeType object links to zero or more Creative objects.

Data Members

Data Member Name | Data Type | Default Value | Description
CreativeTypeName | WSTR | None | Stores the name of the object.
CreativeTypeNum | LONG | 0 | Stores the unique key for the object.
CreativeTypeTemplate | WSTR | None | None
SiteName | WSTR | None | None

Class Key

CreativeTypeKey is composed of a single data member, CreativeTypeNum.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
CreativeTypeCreative | CreativeType | Creative | 2
CreativeTypeCreativeTypeXrefRel | CreativeType | CreativeTypeXref | 2


CreativeTypeXRef

This class categorizes custom content for Web pages. One or more CreativeTypeXRef objects link to a CreativeType.

Data Members

Data Member Name | Data Type | Default Value | Description
CreativeTypeNum | LONG | 0 | Key member
GUIDCampItemType | UUID | {00000000-0000-0000-0000-000000000000} | Key member
SiteName | WSTR | Inherited | Stores the name of the site associated with the object.

Class Key

CreativeTypeXrefKey is composed of the following data members:

CreativeTypeNum + GUIDCampItemType

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
CampaignItemTypesCreativeTypeXrefRel | CampaignItemTypes | CreativeTypeXref | 2
CreativeTypeCreativeTypeXrefRel | CreativeType | CreativeTypeXref | 2


Customer

This class defines a customer who uses advertising through a Commerce Server 2000 Web site. A Customer object associates with an IndustryCode object, which defines the category of industry the customer belongs to. A link to one or more Campaign objects records the marketing campaigns for the customer. A link to one or more Creative objects records any custom advertisements for the customer.

Data Members

Data Member Name | Data Type | Default Value | Description
Address | WSTR | None | Stores the address for the Customer object.
Archived | FILETIME | None | Stores when the Customer object was archived.
Comments | WSTR | None | Stores any comments concerning the Customer object.
Contact | WSTR | None | Stores the name of the contact for the Customer object.
CustomerNum | LONG | 0 | Stores the unique key for the Customer object.
CustomerTypeNum | LONG | None | Stores a user-definable classification code.
Email | WSTR | None | Stores the e-mail address for the Customer object.
Exported | FILETIME | None | Stores when the Customer object was exported.
Fax | WSTR | None | Stores the fax number for the Customer object.
IndustryNum | LONG | 0 | None
Modified | FILETIME | None | Stores when the Customer object was last modified.
ModifiedBy | WSTR | None | Stores who last modified the Customer object.
Name | WSTR | None | Stores the name of the Customer object.
PassWord | WSTR | None | Stores the password for the Customer object.
Phone | WSTR | None | Stores the phone number for the Customer object.
SiteName | WSTR | None | Stores the name of the site associated with the Customer object.
URL | WSTR | None | Records the URL associated with the Customer object.
UserName | WSTR | None | Stores the user name for the Customer object.

Class Key

CustomerKey is composed of a single data member, CustomerNum.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
CampaignCustomer | Customer | Campaign | 2
CreativeCustomer | Customer | Creative | 2
CustomerIndustryCode | IndustryCode | Customer | 2


Date

This class represents dates and times.

Data Members

Data Member Name | Data Type | Default Value | Description
DTimestamp | FILETIME | 1900-1-1 0:0:0.0 | Stores the timestamp.

Class Key

DateKey is composed of a single data member, DTimestamp.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
DateBasketTimeStamp | Date | Basket | 2
DateCampaignEventTimeStamp | Date | CampaignEvent | 2
DateCampaignItemEventsByDateAndUser | Date | CampaignItemEventsByDateAndUser | 2
DateFirstUriByDate | Date | FirstUriByDate | 2
DateHitsByHour | Date | HitsByHour | 2
DateHitsInfo | Date | HitsInfo | 2
DateLastUriByDate | Date | LastUriByDate | 2
DateOrderGroup | Date | OrderGroup | 2
DateOrderTimeStamp | Date | Order | 2
DateRequestByDateByUriByQueryString | Date | RequestByDateByUriByQueryString | 2
DateToOrderFormHeader | Date | OrderFormHeader | 194
DateUniqueUserKeyByDate | Date | UniqueUserKeyByDate | 2
DateVisitInfoFirstTimeStamp | Date | VisitInfo | 2


DMItem

This class represents scheduled direct mailing items. The class contains data members detailing the direct mail content, including address and format information.

Data Members

Data Member Name | Data Type | Default Value | Description
CampItemNum | LONG | 0 | None
DmItemAttachment | WSTR | None | Stores the name of the attachment for the direct mail item.
DmItemDefformat | SHORT | None | Stores the default format code for the direct mail item.
DmItemDesc | WSTR | None | Stores a description of the direct mail item.
DmItemFrom | WSTR | None | Stores the e-mail address for the "from" field in the direct mail item.
DmItemNum | LONG | 0 | Stores the unique key for the object.
DmItemPersonalized | SHORT | None | Indicates if the direct mail item is personalized.
DmItemReplyTo | WSTR | None | Stores the "reply-to" e-mail address for the direct mail item.
DmItemScheduleId | WSTR | None | None
DmItemSource | WSTR | None | Stores the name of the source for the direct mail item.
DmItemSubj | WSTR | None | Stores the subject line for the direct mail item.
DmItemUserFlags | LONG | None | Stores an encoded set of flags governing user data associated with the direct mail item.
GUIDDmItemListId | UUID | None | None
GUIDDmItemOptout | UUID | None | None
GUIDDmItemTestListId | UUID | None | None
SiteName | WSTR | None | Stores the name of the site associated with the object.

Class Key

DmItemKey is composed of a single data member, DmItemNum.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
DmItemCampaignItem | CampaignItem | DmItem | 2


EventType

This class represents a categorization of marketing events. An EventType object describes a marketing event, and associates with one or more Campaign objects representing the marketing campaigns in the event.

Data Members

Data Member Name | Data Type | Default Value | Description
EventDescription | WSTR | None | Stores a description of the campaign event.
EventName | WSTR | Not available | Stores the unique key for the object.
SiteName | WSTR | None | Stores the name of the site associated with the object.

Class Key

EventTypeKey is composed of a single data member, EventName.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
CampaignEventType | EventType | Campaign | 2
EventTypeBasketRel | EventType | Basket | 2
EventTypeCampaignEventRel | EventType | CampaignEvent | 2
EventTypeCampaignItemEventsByDateAndUser | EventType | CampaignItemEventsByDateAndUser | 2
EventTypeOrderRel | EventType | Order | 2


FirstUriByDate

The class represents a summarization of information about the first Uniform Resource Identifier (URI) in each visit grouped by date.

Data Members

Data Member Name | Data Type | Default Value | Description
Date | FILETIME | 1900-1-1 0:0:0.0 | Key member
FirstUri | WSTR | Not available | Key member
SiteName | WSTR | Not available | Key member
TaskID | LONG | 0 | Key member
VisitCount | LONG | 0 | None

Class Key

FirstUriByDateKey is composed of the following data members:

Date + FirstUri + SiteName + TaskID

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
DateFirstUriByDate | Date | FirstUriByDate | 2
SiteFirstUriByDate | Site | FirstUriByDate | 2
TaskHistoryFirstUriByDate | TaskHistory | FirstUriByDate | 2
uriFirstUriByDate | URI | FirstUriByDate | 2


HitsByHour

The class represents a summarization of hits information grouped on an hour-by-hour basis.

Data Members

Data Member Name | Data Type | Default Value | Description
HitsCount | LONG | 0 | None
Hour | FILETIME | 1900-1-1 0:0:0.0 | Key member
SiteName | WSTR | Not available | Key member
TaskID | LONG | 0 | Key member
TotalBytesReceived | LONGREAL | 0 | None
TotalBytesSent | LONGREAL | 0 | None

Class Key

HitsByHourKey is composed of the following data members:

Hour + SiteName + TaskID

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
DateHitsByHour | Date | HitsByHour | 2
SiteHitsByHour | Site | HitsByHour | 2
TaskHistoryHitsByHour | TaskHistory | HitsByHour | 2


HitsInfo

This class represents summary information about hits on a Web site.

Data Members

Data Member Name | Data Type | Default Value | Description
Date | FILETIME | 1900-1-1 0:0:0.0 | Key member
HitsCount | LONG | 0 | None
HttpStatus | ULONG | 0 | Key member
IsRequest | SHORT | 0 | Key member
SiteName | WSTR | Not available | Key member
TaskID | LONG | 0 | Key member
URI | WSTR | Not available | Key member
Win32Status | ULONG | 0 | Key member

Class Key

HitsInfoKey is composed of the following data members:

Date + HttpStatus + IsRequest + SiteName + TaskID + URI + Win32Status

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
DateHitsInfo | Date | HitsInfo | 2
HttpStatusHitsInfo | HttpStatus | HitsInfo | 2
SiteHitsInfo | Site | HitsInfo | 2
TaskHistoryHitsInfo | TaskHistory | HitsInfo | 2
uriHitsInfo | URI | HitsInfo | 2
Win32StatusHitsInfo | Win32Status | HitsInfo | 2


HostnameRef

This class represents the host name reference for an Internet Protocol (IP) address. A HostnameRef object links to one or more IPRef objects.

Data Members

Data Member Name | Data Type | Default Value | Description
Hostname | WSTR | Not available | Stores the unique key for the object.

Class Key

HostnameRefKey is composed of a single data member, Hostname.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
HostnameRefIPRefRel | HostnameRef | IPRef | 2


HttpStatus

This class represents the HTTP status codes as stored in the Web log file.

Data Members

Data Member Name | Data Type | Default Value | Description
HttpStatus | ULONG | 0 | Stores the unique key for the object.
IsSuccessCode | SHORT |  | 2xx - success 3xx - redirect 4xx - failure 5xx - server setup incorrect

Class Key

HttpStatusKey is composed of a single data member, HttpStatus.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
HttpStatusHitsInfo | HttpStatus | HitsInfo | 2
HttpStatusRequest | HttpStatus | Request | 194


ImportOptions

The class represents the options for importing information.

Data Members

Data Member Name | Data Type | Default Value | Description
HitsBufferMaxSize | LONG | None | None
NumImportPipeline | LONG | None | None

Class Key

No key is defined for this class. It is a dependent class.

Relations

No relations are defined for this class.


IndustryCode

This class categorizes the type of industry a customer or advertising item represents. An IndustryCode object links to zero or more Customer objects and zero or more AdItem objects.

Data Members

Data Member Name | Data Type | Default Value | Description
IndustryCode | WSTR | None | Stores the code for the type of industry represented by the object.
IndustryNum | LONG | 0 | Stores the unique key for the object.
SiteName | WSTR | None | Stores the name of the site associated with the object.

Class Key

IndustryCodeKey is composed of a single data member, IndustryNum.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
AdItemIndustryCode | IndustryCode | AdItem | 2
CustomerIndustryCode | IndustryCode | Customer | 2


IPRef

This class represents an Internet Protocol (IP) reference for a LogUser object. An IPRef object contains information on the IP address, number of look-ups associated with the address, and the status of the reference.

An IPRef object associates with a HostNameRef object, describing the host associated with the IP address.

Data Members

Data Member Name | Data Type | Default Value | Description
Hostname | WSTR | Not available | None
IPAddress | WSTR | 0.0.0.0 | Stores the unique key for the object.
LastModifiedTime | FILETIME | None | Records when the object was last modified.
Status | LONG | None | Indicates whether the IP address is resolved: 0 - Unresolved 1 - Resolved

Class Key

IPRefKey is composed of a single data member, IPAddress.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
HostnameRefIPRefRel | HostnameRef | IPRef | 2
IPRefUserRel | IPRef | LogUser | 2


LastUriByDate

The class represents a summarization of information about the last URI in each visit grouped by date.

Data Members

Data Member Name | Data Type | Default Value | Description
Date | FILETIME | 1900-1-1 0:0:0.0 | Key member
LastUri | WSTR | Not available | Key member
SiteName | WSTR | Not available | Key member
TaskID | LONG | 0 | Key member
VisitCount | LONG | 0 | None

Class Key

LastUriByDateKey is composed of the following data members:

Date + LastUri + SiteName + TaskID

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
DateLastUriByDate | Date | LastUriByDate | 2
SiteLastUriByDate | Site | LastUriByDate | 2
TaskHistoryLastUriByDate | TaskHistory | LastUriByDate | 2
uriLastUriByDate | URI | LastUriByDate | 2


Level1Dir

This class represents the first level in a hierarchical directory structure. Each level contains a link to a URI object.

Data Members

Data Member Name | Data Type | Default Value | Description
DirName1 | WSTR | / | Stores the unique key for the object.

Class Key

Level1DirKey is composed of a single data member, DirName1.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
Level1DirURIRel | Level1Dir | URI | 2


Level2Dir

This class represents the second level in a hierarchical directory structure. Each level contains a link to a URI object.

Data Members

Data Member Name | Data Type | Default Value | Description
DirName2 | WSTR | * | Stores the unique key for the object.

Class Key

Level2DirKey is composed of a single data member, DirName2.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
Level2DirURIRel | Level2Dir | URI | 2


Level3Dir

This class represents the third level in a hierarchical directory structure. Each level contains a link to a URI object.

Data Members

Data Member Name | Data Type | Default Value | Description
DirName3 | WSTR | * | Stores the unique key for the object.

Class Key

Level3DirKey is composed of a single data member, DirName3.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
Level3DirURIRel | Level3Dir | URI | 2


Level4Dir

This class represents the fourth level in a hierarchical directory structure. Each level contains a link to a URI object.

Data Members

Data Member Name | Data Type | Default Value | Description
DirName4 | WSTR | * | Stores the unique key for the object.

Class Key

Level4DirKey is composed of a single data member, DirName4.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
Level4DirURIRel | Level4Dir | URI | 2


Level5Dir

This class represents the fifth level in a hierarchical directory structure. Each level contains a link to a URI object.

Data Members

Data Member Name | Data Type | Default Value | Description
DirName5 | WSTR | * | Stores the unique key for the object.

Class Key

Level5DirKey is composed of a single data member, DirName5.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
Level5DirURIRel | Level5Dir | URI | 2


Level6Dir

This class represents the sixth and final level in a hierarchical directory structure. Each level contains a link to a URI object.

Data Members

Data Member Name | Data Type | Default Value | Description
DirName6 | WSTR | * | Stores the unique key for the object.

Class Key

Level6DirKey is composed of a single data member, DirName6.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
Level6DirURIRel | Level6Dir | URI | 2


LinkMVQStringName

This class links a SiteURL object to a MVQStringName object. The MVQStringName object represents a custom query string that queries multi-value columns in the data store.

Data Members

Data Member Name | Data Type | Default Value | Description
QStringName | WSTR | DEFAULT | Key member
URL | WSTR | Not available | Key member

Class Key

LinkMVQStringNameKey is composed of the following data members:

QStringName + URLID

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
MVQStringNameLinkMVQStringNameRel | MVQStringName | LinkMVQStringName | 2
SiteURLLinkMVQStringNameRel | SiteURL | LinkMVQStringName | 2


LinkSVQStringName

This class links a SiteURL object to a SVQStringName object. The SVQStringName object represents a custom query string that queries single-value columns in the data store.

Data Members

Data Member Name | Data Type | Default Value | Description
QStringName | WSTR | DEFAULT | Key member
URL | WSTR | Not available | Key member

Class Key

LinkSVQStringNameKey is composed of the following data members:

QStringName + URL

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
SiteURLLinkSVQStringNameRel | SiteURL | LinkSVQStringName | 2
SVQStringNameLinkSVQStringNameRel | SVQStringName | LinkSVQStringName | 2


LogUser

This class stores information on user interactions with a Commerce Server 2000 Web site.

Someone who visits a Commerce Server 2000 Web site is called a user. A LogUser object is created for every user and used to record information about that user (such as cookie data, user name, and so on). A Visit object is created every time the user visits the Web site. The new Visit object is linked to the LogUser object for that user. A LogUser object may represent an anonymous user, a user who is part of an organization, or a user who is registered on the Commerce Server 2000 Web site.

The Internet Protocol (IP) information for the user is stored in an IPRef object associated with the LogUser object. A HostNameRef object stores host name information for the IPRef object.

Data Members

Data Member Name | Data Type | Default Value | Description
DateCreated | FILETIME | None | None
HasCookie | SHORT |  | None
IpAddress | WSTR | 0.0.0.0 | None
UserDomainName | WSTR | None | Stores the Domain Name Service (DNS) domain name associated with the user.
UserId | WSTR | Not available | None
UserKey | UUID | {00000000-0000-0000-0000-000000000000} | Stores the unique key for the object.
UserName | WSTR | Not available | Stores the user name (cs-username) from a World Wide Web Consortium (W3C) formatted log file.

Class Key

LogUserKey is composed of a single data member, UserKey.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
IPRefUserRel | IPRef | LogUser | 2
LogUserBasketRel | LogUser | Basket | 2
LogUserCampaignEventRel | LogUser | CampaignEvent | 2
LogUserCampaignItemEventsByDateAndUser | LogUser | CampaignItemEventsByDateAndUser | 2
LogUserOrderRel | LogUser | Order | 2
LogUserRequestRel | LogUser | Request | 2
LogUserUniqueUserKeyByDate | LogUser | UniqueUserKeyByDate | 2
RegisteredUserUserRel | RegisteredUser | LogUser | 2
UserVisit | LogUser | Visit | 194
UserVisitInfo | LogUser | VisitInfo | 2


MVQStringName

This class represents the names for custom multi-value query strings. The MVQStringName object associates with a SiteURL object through a LinkMVQStringName object.

Data Members

Data Member Name | Data Type | Default Value | Description
QStringName | WSTR | DEFAULT | Stores the name of the multi-value query string.

Class Key

MVQStringNameKey is composed of a single data member, QStringName.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
MVQStringNameLinkMVQStringNameRel | MVQStringName | LinkMVQStringName | 2


OpenUserVisit

This class represents a visit to a Web site that was open when the containing log files were imported. This allows the open visit to be connected and closed in the following log imports. After a visit is completed (closed), the OpenUserVisit object is deleted and a VisitInfo object is instantiated.

Data Members

Data Member Name | Data Type | Default Value | Description
CountOfRequest | ULONG | None | None
FirstRequestNum | IDENTITY | None | None
FirstTimeStamp | FILETIME | None | None
FirstUri | WSTR | Not available | None
LastRequestNum | IDENTITY | None | None
LastTimeStamp | FILETIME | None | None
LastUri | WSTR | Not available | None
ReferrerDomainName | WSTR | Not available | None
SecondRequestNum | IDENTITY | None | None
SecondUri | WSTR | Not available | None
SiteName | WSTR | Not available | None
TaskID | LONG | 0 | None
UserAgentName | WSTR | Not available | None
UserId | WSTR | Not available | None
UserKey | UUID | None | None
VisitNum | IDENTITY | 0 | Stores the unique key for the object.

Class Key

OpenUserVisitKey is composed of a single data member, VisitNum.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
ReferrerDomainOpenUserVisit | ReferrerDomain | OpenUserVisit | 2
RegisteredUserOpenUserVisit | RegisteredUser | OpenUserVisit | 2
SiteOpenUserVisitRel | Site | OpenUserVisit | 2
TaskHistoryOpenUserVisitRel | TaskHistory | OpenUserVisit | 2
UserAgentOpenUserVisit | UserAgent | OpenUserVisit | 2


Order

This class stores requests to save or submit purchase orders.

Data Members

Data Member Name | Data Type | Default Value | Description
EventName | WSTR | Not available | None
ordergroup_id | UUID | {00000000-0000-0000-0000-000000000000} | None
SiteName | WSTR | Not available | None
TaskID | LONG | 0 | None
TimeStamp | FILETIME |  | None
URI | WSTR | Not available | None
UserId | WSTR | Not available | None
UserKey | UUID | {00000000-0000-0000-0000-000000000000} | None
VisitNum | IDENTITY | 0 | None

Class Key

No key is defined for this class. It is a dependent class.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
DateOrderTimeStamp | Date | Order | 2
EventTypeOrderRel | EventType | Order | 2
LogUserOrderRel | LogUser | Order | 2
OrderGroupOrderRel | OrderGroup | Order | 2
RegisteredUserOrderRel | RegisteredUser | Order | 2
SiteOrder | Site | Order | 2
TaskHistoryOrder | TaskHistory | Order | 2
UriOrder | URI | Order | 2


OrderDiscount

This class represents discounted sale items. The class contains data members describing the items and conditions of the sale.

Data Members

Data Member Name | Data Type | Default Value | Description
CampItemNum | LONG | 0 | None
DiscAwardExpr | LONG | None | None
DiscAwardMax | LONG | None | Stores the maximum amount of discount awarded.
DiscClickRequired | SHORT | None | Indicates if a click is required to activate the discount.
DiscCondBasis | LONG | None | Stores the base condition code for the discount.
DiscCondExpr | LONG | None | None
DiscCondMin | LONGREAL | None | Stores the minimum amount that must be spent before applying the discount.
DiscDescription | WSTR | None | Stores a description of the order discount item.
DiscDisjointCondAward | SHORT | None | Indicates if there is a disjoint condition governing awards of the discount.
DiscExprUsedForDisplay | SHORT | None | Indicates if the discount item is used only for display.
DiscLimit | LONG | None | Stores the limit on discount item orders.
DiscNum | LONG | 0 | Stores the unique key for the object.
DiscOfferType LONG None Stores a code indicating the type of discount offer:
  • 1 - Flat amount

  • 2 - Percentage
DiscOfferValue | LONGREAL | None | Stores the value of the discount offer.
DiscOrderLevelDiscount | SHORT | None | None
DiscQtyCondMin | LONG | None | Stores the minimum quantity required before the discount can be applied.
DiscRank | LONG | None | Stores the relative rank for the discount item.
DiscSpecialOfferType | WSTR | None | Stores a code indicating the type of special offer associated with the discount.
DiscTemplate | LONG | None | Stores the code for the template used for the discount item.
SiteName | WSTR | None | Stores the name of the site associated with the object.

Class Key

OrderDiscountKey is composed of a single data member, DiscNum.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
OrderDiscountCampaignItem | CampaignItem | OrderDiscount | 2


OrderFormHeader

This class represents the header information for an order form. An OrderFormHeader object has contact information, buyer information, and other data necessary to process an order form. An OrderFormHeader object links to zero or more OrderFormLineItems objects, representing the ordered items. An OrderGroup object, representing a purchase order, links to zero or more OrderFormHeader objects.

Data Members

Data Member Name | Data Type | Default Value | Description
billing_currency | WSTR | None | None
buying_org_name | WSTR | None | Stores the name of the buyer organization.
cc_auth_number | WSTR | None | Stores the authorization code for the credit card.
d_DateCreated | DATETIME | None | None
d_DateLastChanged | DATETIME | None | None
g_UserIDChangedBy | WSTR | None | None
OrderForm_date | DATETIME | None | Stores the date of the order form.
OrderForm_date_UnNorm | DATETIME | None | None
OrderForm_Id | UUID | {00000000-0000-0000-0000-000000000000} | Stores the second part of the unique key for the object.
ordergroup_id | UUID | {00000000-0000-0000-0000-000000000000} | Stores the first part of the unique key for the object.
po_number | WSTR | None | None
receiver_email_address | WSTR | None | None
receiver_fax_number | WSTR | None | None
receiver_first_name | WSTR | None | Stores the first name of the receiver.
receiver_last_name | WSTR | None | Stores the last name of the receiver.
receiver_tel_number | WSTR | None | None
saved_cc_expiration | WSTR | None | Stores the expiration code for the saved credit card.
saved_cc_number | WSTR | None | Stores the number of the saved credit card.
saved_cy_tax_total | CURRENCY | None | None
saved_cy_total_total | CURRENCY | None | None
selling_org_name | WSTR | None | Stores the name of the seller organization.
tax_exempt_code | WSTR | None | None
tax_exempt_id | WSTR | None | None
total_lineitems | LONG | None | None
user_email_address | WSTR | None | Stores the e-mail address for the purchaser.
user_fax_number | WSTR | None | Stores the fax number for the purchaser.
user_first_name | WSTR | None | Stores the first name of the purchaser.
user_id | WSTR | None | Stores the user ID for the purchaser.
user_last_name | WSTR | None | Stores the last name of the purchaser.
user_name | WSTR | None | Stores the name of the purchaser.
user_org_id | WSTR | None | Stores the identifier of the organization for the purchaser.
user_org_name | WSTR | None | Stores the organization name of the purchaser.
user_tel_number | WSTR | None | Stores the phone number for the purchaser.

Class Key

OrderFormHeaderKey is composed of the following data members:

ordergroup_id + OrderForm_Id

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
DateToOrderFormHeader | Date | OrderFormHeader | 194
OrderFormHeaderToOrderFormLineItems | OrderFormHeader | OrderFormLineItems | 2
OrderGroupToOrderFormHeader | OrderGroup | OrderFormHeader | 2


OrderFormLineItems

This class represents the items in an order form. An OrderFormHeader object, representing the information used to process the order form, links to zero or more OrderFormLineItems objects.

Data Members

Data Member Name | Data Type | Default Value | Description
cy_lineitem_total | CURRENCY | None | None
cy_unit_price | CURRENCY | None | Stores the sales price of the item after any discounts or adjustments.
d_DateCreated | DATETIME | None | None
d_DateLastChanged | DATETIME | None | None
description | WSTR | None | None
g_UserIDChangedBy | WSTR | None | None
lineitem_id | WSTR | Not available | Key member
OrderForm_id | UUID | {00000000-0000-0000-0000-000000000000} | Key member
ordergroup_id | UUID | {00000000-0000-0000-0000-000000000000} | Key member
product_catalog | WSTR | None | None
product_catalog_base | WSTR | None | None
product_id | WSTR | None | None
product_identifying_property | WSTR | None | None
product_Variant_id | WSTR | None | None
product_variant_identifying_property | WSTR | None | None
ProductNameCat | WSTR400 | Not available | Stores the catalog name concatenated with the product name and the variant name.
quantity | LONG | None | None
shipping_address_id | WSTR | None | None
shipping_method_name | WSTR | None | None
tax_exempt_code | WSTR | None | None
tax_id | WSTR | None | None
unit_code | WSTR | None | None

Class Key

OrderFormLineItemsKey is composed of the following data members:

lineitem_id + OrderForm_id + ordergroup_id

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
OrderFormHeaderToOrderFormLineItems | OrderFormHeader | OrderFormLineItems | 2
OrderFormLineItemsToOrderGroupAddresses | OrderGroupAddresses | OrderFormLineItems | 2
OrderFormLineItemsToProducts | Products | OrderFormLineItems | 2
OrderGroupToOrderFormLineItems | OrderGroup | OrderFormLineItems | 2


OrderGroup

This class describes purchase order information. Specifically, the OrderGroup object links to one or more OrderFormHeader objects and one or more OrderGroupAddresses objects. The OrderFormHeader class represents control information for the purchase order such as billing codes, tax codes, and other data required to process the purchase order. The OrderFormHeader object links to one or more OrderFormLineItems objects, which describe the specific products to be purchased. The OrderGroupAddresses class represents mailing and shipping information for purchase orders.

Data Members

Data Member Name | Data Type | Default Value | Description
alt_currency | WSTR | None | Stores the alternate currency type for the order.
alt_lcid | LONG | None | Stores the alternate currency identifier code for the order.
billing_currency | WSTR | None | Stores the type of currency used in the order.
d_DateCreated | DATETIME | None | Records the date the order was created.
d_DateLastChanged | DATETIME | None | Records the date the order was last changed.
default_currency | WSTR | None | Stores the default type of currency used in the order.
default_lcid | LONG | None | Stores the local currency identifier code for the order.
g_UserIDChangedBy | UUID | None | Stores the globally unique identifier (GUID) of the user who last changed the order.
order_approval_decision_date | DATETIME | None | Records when the order was approved.
order_create_date | DATETIME | None | Records when the order was created.
order_number | WSTR | None | Stores the order number.
order_status_code | LONG | None | Stores a code indicating the status of the order. User definable.
ordergroup_id | UUID | {00000000-0000-0000-0000-000000000000} | Stores the unique key for the object.
previous_order_id | UUID | None | Store the previous order_id for the order, if it exists.
saved_cy_oadjust_subtotal | CURRENCY | None | Stores the adusted current year subtotal for the order.
saved_cy_total_total | CURRENCY | None | Stores the saved current year total for the order.
saved_order_name | WSTR | None | Stores the saved name for the order.
SiteName | WSTR | Not available | None
total_lineitems | LONG | None | Stores the total number of line items.
user_first_name | WSTR | None | Stores the first name of the user associated with the order.
user_id | WSTR | None | Stores the universally unique identifier (UUID) of the user associated with the order.
user_last_name | WSTR | None | Stores the last name of the user associated with the order.
user_name | WSTR | None | Stores the full name of the user associated with the order.
user_org_name | WSTR | None | Stores the name of the organization associated with the order.

Class Key

OrderGroupKey is composed of a single data member, ordergroup_id.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
DateOrderGroup | Date | OrderGroup | 2
OrderGroupOrderRel | OrderGroup | Order | 2
OrderGroupSite | Site | OrderGroup | 2
OrderGroupToOrderFormHeader | OrderGroup | OrderFormHeader | 2
OrderGroupToOrderFormLineItems | OrderGroup | OrderFormLineItems | 2
OrderGroupToOrderGroupAddresses | OrderGroup | OrderGroupAddresses | 2
UserToOrderGroup | RegisteredUser | OrderGroup | 2


OrderGroupAddresses

This class represents mailing and shipping information for purchase orders.

Data Members

Data Member Name | Data Type | Default Value | Description
Address_id | WSTR | Not available | Key member
Address_Name | WSTR | None | None
Address_type | LONG | None | None
City | WSTR | None | None
country_code | WSTR | None | None
Country_Name | WSTR | None | None
d_DateCreated | DATETIME | None | None
d_DateLastChanged | DATETIME | None | None
First_Name | WSTR | None | None
g_UserIDChangedBy | UUID | None | None
Last_Name | WSTR | None | None
ordergroup_id | UUID | {00000000-0000-0000-0000-000000000000} | Key member
Postal_Code | WSTR | None | None
region_code | WSTR | None | None
region_name | WSTR | None | None
tel_number | WSTR | None | None

Class Key

OrderGroupAddressesKey is composed of the following data members:

Address_id + ordergroup_id

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
OrderFormLineItemsToOrderGroupAddresses | OrderGroupAddresses | OrderFormLineItems | 2
OrderGroupToOrderGroupAddresses | OrderGroup | OrderGroupAddresses | 2


PageGroup

This class represents a group of custom content items used on a Web page for a marketing campaign. The page is part of one or more marketing campaign events; a link from the PageGroup object to one or more CampaignEvent objects represents this information. CampaignItem objects represent the custom content items, and link to the PageGroup object through one or more PageGroupXRef objects.

Data Members

Data Member Name | Data Type | Default Value | Description
PgDescription | WSTR | None | Stores a description of the Web page.
PgNum | LONG | 0 | Stores the unique key for the object.
PgTag | WSTR | None | Stores the HTML tag associated with the Web page.
SiteName | WSTR | None | None

Class Key

PageGroupKey is composed of a single data member, PgNum.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
PageGroupCampaignEventRel | PageGroup | CampaignEvent | 2
PageGroupPageGroupXRefRel | PageGroup | PageGroupXref | 2


PageGroupXRef

This class cross-references custom Web page content with the Web page or logical set of Web pages that contain the content. A PageGroupXRef associates a CampaignItem object, which describes the custom content, with a PageGroup object. The PageGroup object represents a Web page or logical set of Web pages that contains custom content.

A single piece of custom content may span multiple Web pages; this is represented by a CampaignItem object linked to multiple PageGroupXRef objects. A single Web page or logical set of Web pages may have multiple separate content items; this is represented by a PageGroup object linked to multiple PageGroupXRef objects.

Data Members

Data Member Name | Data Type | Default Value | Description
CampItemNum | LONG | 0 | Key member
PgNum | LONG | 0 | Key member
SiteName | WSTR | None | Stores the name of the site associated with the object.

Class Key

PageGroupXRefKey is composed of the following data members:

CampItemNum + PageNum

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
CampaignItemPageGroupXRefRel | CampaignItem | PageGroupXRef | 2
PageGroupPageGroupXRefRel | PageGroup | PageGroupXRef | 2


Products

This class represents the products contained in a sales catalog.

Data Members

Data Member Name | Data Type | Default Value | Description
CatalogName | WSTR | Not available | Stores the name of the catalog containing the product.
CategoryNameCat | WSTR400 | Not available | Stores the catalog name concatenated with the category name containing the product.
cy_list_price | CURRENCY | Not available | None
ProductNameCat | WSTR400 | Not available | Stores the catalog name concatenated with the product name and the variant name.
ProductId | WSTR | Not available | None
VariantId | WSTR | Not available | None

Class Key

ProductsKey is composed of a single data member, ProductNameCat.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
Category | Category | Products | 3
ProductsBasketRel | Products | Basket | 2
OrderFormLineItemsToProducts | Products | OrderFormLineItems | 2


Referrer

This class represents the referring Uniform Resource Locator (URL) for a request.

Data Members

Data Member Name | Data Type | Default Value | Description
ReferrerURL | WSTR | Not available | Stores the unique key for the object.

Class Key

ReferrerKey is composed of a single data member, ReferrerURL.

Relations

No relations are defined for this class.


ReferrerDomain

This class represents the referring domain for a request.

Data Members

Data Member Name | Data Type | Default Value | Description
ReferrerDomainName | WSTR | Not available | Stores the unique key for the object.

Class Key

ReferrerDomainKey is composed of a single data member, ReferrerDomainName.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
ReferrerDomainOpenUserVisit | ReferrerDomain | OpenUserVisit | 2
ReferrerDomainRequest | ReferrerDomain | Request | 194
ReferrerDomainVisitInfo | ReferrerDomain | VisitInfo | 194


RegisteredUser

This class represents user profile data. By default, the Commerce Server 2000 User Profile Data Import Data Transformation Services (DTS) Task imports data from the UserObject table into this class. Data in this table may or may not correspond to users of the Commerce Server 2000 Web site.

Data Members

Data Member Name | Data Type | Default Value | Description
AccountClass | LONG | None | Stores a classification code for the user account.
AccountStatus | LONG | None | Stores the account status for the user: 0 - inactive 1 - active
ApprovalLimit | LONG | None | Stores the approved spending limit for the user.
ApprovalLimitCurrency | WSTR | None | Stores the type of currency for the spending limit.
ApprovingManagerID | LONG | None | Stores an identifier code for the manager who approved the spending limit for the user.
AuthType | SHORT | None | Stores the type of authentication required for the user.
DateCreated | FILETIME | None | Records when the object was created.
DateLastChanged | FILETIME | None | Records when the object was last changed.
DateRegistered | FILETIME | None | Records the date and time when the user registered on the site.
DefaultBlanketPONumber | WSTR | None | Stores the default purchase order number for the user.
DefaultBlanketPOProfileID | LONG | None | Stores the default purchase order profile ID.
DefaultCostCenterNumber | WSTR | None | Stores the default cost center identifier.
DefaultCostCenterProfileID | LONG | None | Stores the default cost center profile identifier.
Email | WSTR | None | Stores the e-mail address for the user.
EmployeeClassID | LONG | None | Stores a classification code for the user employee ID.
FaxNumber | WSTR | None | Stores the fax number of the user.
FirstName | WSTR | None | Stores the first name of the user.
ID | UUID | {00000000-0000-0000-0000-000000000000} | None
IDCode | WSTR | None | Stores a code for the user ID.
IDCodeQualifier | WSTR | None | Stores a code for the qualifier of the user identification.
LastName | WSTR | None | Stores the last name of the user.
LocationID | LONG | None | Not used.
Logon_Name | WSTR | None | Stores the logon name of the user.
Name | WSTR | None | Not used.
OrgID | WSTR | None | Stores an identifier of the organization for the user.
ShipToID | LONG | None | Not used.
ShipToMethodCode | LONG | None | Stores a code for the method of shipping preferred by the user.
SiteName | WSTR | Not available | None
TelephoneNumber | WSTR | None | Stores the phone number of the user.
UserID | WSTR | Not available | Stores the unique key for the object.
UserIDChangedBy | WSTR | None | Records who last changed/set the UserID.
UserTitle | WSTR | None | Stores the title of the user.
UserType | LONG | Registered (1). | Stores the user type: 0 - Guest (Anonymous) 1 - Registered

Class Key

RegisteredUserKey is composed of a single data member, UserID.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
AddressUserRel | Address | RegisteredUser | 2
RegisteredUserBasketRel | RegisteredUser | Basket | 2
RegisteredUserCampaignEventRel | RegisteredUser | CampaignEvent | 2
RegisteredUserOpenUserVisit | RegisteredUser | OpenUserVisit | 2
RegisteredUserOrderRel | RegisteredUser | Order | 2
RegisteredUserRequestRel | RegisteredUser | Request | 2
RegisteredUserUserRel | RegisteredUser | LogUser | 2
RegisteredUserVisitInfoRel | RegisteredUser | VisitInfo | 2
SiteRegisteredUserRel | Site | RegisteredUser | 3
UserToOrderGroup | RegisteredUser | OrderGroup | 2


Request

This class represents a request made in the context of a visit. A Request object connects to information describing the user and other details of the visit.

A request may be a part of a Uniform Resource Identifier (URI), in which case a URI object is linked to the Request object. The query string contained in the URI is represented by a URIQuery object linked to the Request object.

Alternatively, a Request may be made through a site Uniform Resource Locator (URL). The site URL is represented by a SiteURL object linked to the Request object through a URI object. The SiteURL object may represent an actual Web site or a virtual server. If the Request object involves query strings through the site, the SiteURL object will have one or more LinkSVQStringName or LinkMVQStringName objects linking the SiteURL object to the query strings.

Data Members

Data Member Name | Data Type | Default Value | Description
BytesReceived | LONGREAL | None | Stores the number of bytes received while processing the request.
BytesSent | LONGREAL | None | Stores the number of bytes sent while processing the request.
DirName1 | WSTR | / | None
DirName2 | WSTR | Inherited | None
DirName3 | WSTR | Inherited | None
DirName4 | WSTR | Inherited | None
DirName5 | WSTR | Inherited | None
DirName6 | WSTR | Inherited | None
HasCommerceEvent | SHORT | None | None
HttpStatus | ULONG | 0 | None
IsRequest | SHORT | None | Identifies the object as a request or a link between a Visit object and Web configuration objects. 0 - Link 1 - Request
IsSecure | SHORT | None | None
IsSuccessCode | SHORT | None | None
Processed | BOOL | 0 | None
QueryString | WSTR | No query string | None
ReferrerDomainName | WSTR | Not available | None
RequestIndex | SHORT | None | None
RequestNum | IDENTITY | 0 | Stores the unique key for the object.
SiteName | WSTR | Not available | None
TaskID | LONG | 0 | None
Timestamp | FILETIME | None | Records when the object was created.
Title | WSTR | Inherited | None
URI | WSTR | Not available | None
URL | WSTR | Not available | None
UserAgentBrowserCategoryID | ULONG | 1 | None
UserAgentName | WSTR | Not available | None
UserAgentOperatingSystemID | ULONG | 1 | None
UserAgentPortalID | ULONG | 1 | None
UserAgentSecurityID | ULONG | 1 | None
UserAgentVersionID | ULONG | 1 | None
UserID | WSTR | Not available | None
UserKey | UUID | {00000000-0000-0000-0000-000000000000} | None
VisitNum | IDENTITY | 0 | None
Win32Status | ULONG | 0 | None

Class Key

RequestKey is composed of a single data member, RequestNum.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
HttpStatusRequest | HttpStatus | Request | 194
LogUserRequestRel | LogUser | Request | 2
ReferrerDomainRequest | ReferrerDomain | Request | 194
RegisteredUserRequestRel | RegisteredUser | Request | 2
SiteRequestRel | Site | Request | 2
TaskHistoryRequestRel | TaskHistory | Request | 2
UriQueryRequest | UriQuery | Request | 2
UriRequest | URI | Request | 194
UserAgentRequest | UserAgent | Request | 194
Win32StatusRequest | Win32Status | Request | 194


RequestByDateByUriByQueryString

The class represents a summarization.

Data Members

Data Member Name | Data Type | Default Value | Description
Date | FILETIME | 1900-1-1 0:0:0.0 | Key member
QueryString | WSTR | Not available | Key member
RequestCount | LONG | 0 | None
SiteName | WSTR | Not available | Key member
TaskID | LONG | 0 | Key member
URI | WSTR | Not available | Key member

Class Key

RequestByDateByUriByQueryStringKey is composed of the following data members:

Date + QueryString + SiteName + TaskID + URI

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
DateRequestByDateByUriByQueryString | Date | RequestByDateByUriByQueryString | 2
SiteRequestByDateByUriByQueryString | Site | RequestByDateByUriByQueryString | 2
TaskHistoryRequestByDateByUriByQueryString | TaskHistory | RequestByDateByUriByQueryString | 2
uriRequestByDateByUriByQueryString | URI | RequestByDateByUriByQueryString | 2
UriQueryRequestByDateByUriByQueryString | UriQuery | RequestByDateByUriByQueryString | 2


ServerBinding

This class represents a binding to a server for a virtual server. A VirtualServer object links to one or more ServerBinding objects.

Data Members

Data Member Name | Data Type | Default Value | Description
HostHeaderName | WSTR | Not available | Key member
IPAddress | WSTR | 0.0.0.0 | Key member
IPPort | LONG | 0 | Key member
IsSecureBinding | SHORT | None | None

Class Key

ServerBindingKey is composed of the following data members:

HostHeaderName + IPAddress + IPPort

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
ServerBindingVirtualServerRel | ServerBinding | VirtualServer | 2


ServerGroup

This class represents server groups. A ServerGroup object links to one or more VirtualServer objects.

Data Members

Data Member Name | Data Type | Default Value | Description
LogFileDir | WSTR | None | Stores the default directory used to store log files for the server group.
LogFormatID | LONG | None | None
ServerGroupName | WSTR | Not available | Stores the unique key for the object.
Timezone | LONG | None | Stores a code indicating the time zone for the server group.

Class Key

ServerGroupKey is composed of a single data member, ServerGroupName.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
ServerGroupVirtualServerRel | ServerGroup | VirtualServer | 2


Site

This class represents a Commerce Server 2000 Web site. All logged information pertaining to the use of a Commerce Server 2000 Web site is stored in or connected to a Site object. The Uniform Resource Locator (URL) for the site is a composition of a SiteURL object and a URI object.

The site may be part of a virtual server group. If this occurs, the site connects to a VirtualServer object through a SiteURL object. A business transaction may occur through a Uniform Resource Identifier (URI) query; this is represented by a link between one or more Request objects and the URI object. Any visits to the site are linked through one or more Visit objects. If the site has a crawler associated with it, a Crawler object is created and linked to the Site object.

Data Members

Data Member Name | Data Type | Default Value | Description
CookieIdentifiers | WSTR | None | None
EndImportAction | LONG | None | Stores a code for the action taken when a log import ends.
IsAdjustTimeStamps | SHORT | None | Indicates if the timestamps in the log data are adjusted for the site.
IsExcludeSpiders | SHORT | None | Indicates if the site object excludes spiders.
IsSeparateUriAndQueryString | SHORT | None | None
IsUseCookiesForInferences | SHORT | None | Indicates if the site object uses cookies for inferences.
IsUseUPMCookiesForInferences | SHORT | None | None
IsUseUsernameForInferences | SHORT | None | Indicates if the site uses user names for inferences.
OverlapAction | LONG | None | Stores a code for the action taken when log files for the site overlap.
OverlapMins | LONG | None | Stores the number of minutes consecutive log files for the site overlap between imports.
SiteName | WSTR | Not available | Stores the unique key for the site.
TimeZone | LONG | None | Stores a code for the time zone of the site.
VisitTimeout | LONG | None | Stores the time limit (in minutes) applied to visits on the Site object.
WeekStartDay | SHORT | None | Stores the day the week starts on.

Class Key

SiteKey is composed of a single data member, SiteName.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
CatalogSite | Site | CatalogGlobal | 3
OrderGroupSite | Site | OrderGroup | 2
SiteAddressRel | Site | Address | 3
SiteBasket | Site | Basket | 2
SiteCampaignEvent | Site | CampaignEvent | 2
SiteCampaignItemEventsByDateAndUser | Site | CampaignItemEventsByDateAndUser | 2
SiteCrawlerRel | Site | Crawler | 2
SiteFirstUriByDate | Site | FirstUriByDate | 2
SiteHitsByHour | Site | HitsByHour | 2
SiteHitsInfo | Site | HitsInfo | 2
SiteLastUriByDate | Site | LastUriByDate | 2
SiteOpenUserVisitRel | Site | OpenUserVisit | 2
SiteOrder | Site | Order | 2
SiteRegisteredUserRel | Site | RegisteredUser | 3
SiteRequestByDateByUriByQueryString | Site | RequestByDateByUriByQueryString | 2
SiteRequestRel | Site | Request | 2
SiteSiteSummaryRel | Site | SiteSummary | 2
SiteSiteURIRel | Site | SiteURL | 2
SiteUniqueUserKeyByDate | Site | UniqueUserKeyByDate | 2
SiteVisitInfoRel | Site | VisitInfo | 2
SiteVisitRel | Site | Visit | 2


SiteSummary

This class stores summary information, such as total visits and total hits, pertaining to a site.

Data Members

Data Member Name | Data Type | Default Value | Description
EndTime | FILETIME | None | Records when the summary finished.
SiteName | WSTR | Not available | Stores the unique key for the object.
StartTime | FILETIME | None | Records when the summary was started.
TotalBadServerCount | LONG | None | Stores the total number of bad server connections to the site.
TotalBadSiteCount | LONG | None | Stores the total number of bad site connections to the site.
TotalExcludeCriteriaCount | LONG | None | Stores the total of exclude criteria for the site.
TotalExcludeHostCount | LONG | None | Stores the total number of hosts excluded from the site.
TotalHits | LONG | None | Stores the total number of hits on the site.
TotalImportHits | LONG | None | Stores the total number of import hits on the site.
TotalMatchCrawlerCount | LONG | None | Stores the total number of crawler matches on the site.
TotalVisits | LONG | None | Stores the total number of visits to the site.

Class Key

SiteSummaryKey is composed of a single data member, SiteName.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
SiteSiteSummaryRel | Site | SiteSummary | 2


SiteURL

This class represents a Uniform Resource Locator (URL) based connection between sites and virtual servers. The relationship between a Web site and a virtual server is represented by a link to a Site object and a link to a VirtualServer object.

The SiteURL object stores the first portion, or top level, (for example, domain name) of a site. If needed, a URI object is linked to the SiteURL object to form the entire URL for the site.

If there are any query strings (SVQStringName or MVQStringName objects) associated with the site URL, they will be linked to the SiteURL object using the LinkSVQStringName or LinkMVQStringName objects.

Data Members

Data Member Name | Data Type | Default Value | Description
ExcludeCriteria | WSTR | None | Stores the exclude criteria for the URL.
ExcludeHosts | WSTR | None | Stores the hosts excluded from access through the URL.
GoodStatusCodes | WSTR | None | None
IncludeCriteria | WSTR | None | None
IsChopTopLevelDir | SHORT | None | Indicates if the top-level directory is cut from the URL.
SiteName | WSTR | Not available | None
URL | WSTR | Not available | Stores the first portion, or top level, of a site. Stores the URL as the unique key for the object.
URLExt | WSTR | None | Stores the extended data for the URL.
VServerName | WSTR | Not available | None

Class Key

SiteURLKey is composed of a single data member, URL.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
SiteSiteURIRel | Site | SiteURL | 2
SiteURLLinkMVQStringNameRel | SiteURL | LinkMVQStringName | 2
SiteURLLinkSVQStringNameRel | SiteURL | LinkSVQStringName | 2
SiteURLURIRel | SiteURL | URI | 2
VirtualServerSiteURLRel | VirtualServer | SiteURL | 3


SVQStringName

This class represents custom single-valued query strings associated with a Uniform Resource Locator (URL). An SVQStringName object associates with a SiteURL object through a LinkSVQStringName object.

Data Members

Data Member Name | Data Type | Default Value | Description
QStringName | WSTR | DEFAULT | Stores the unique key for the object.

Class Key

SVQStringNameKey is composed of a single data member, QStringName.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
SVQStringNameLinkSVQStringNameRel | SVQStringName | LinkSVQStringName | 2


Target

This class defines a target for marketing and custom Web content, such as a particular type of user. A TargetGroup object links to one or more Target objects to form target groups. The custom content for the group of targets links to the TargetGroup object through a TargetGroupXRef object.

Data Members

Data Member Name | Data Type | Default Value | Description
SiteName | WSTR | None | Stores the site name associated with the object.
TargetAction | LONG | None | Stores the action code for the target.
TargetExprID | LONG | None | Stores the expression ID for the target.
TargetGroupNum | LONG | 0 | None
TargetNum | LONG | 0 | Stores the unique key for the object.

Class Key

TargetKey is composed of a single data member, TargetNum.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
TargetGroupTarget | TargetGroup | Target | 2


TargetGroup

This class defines a group of targets for marketing and custom Web content. One or more Target objects linked with a TargetGroup object forms a target group. A target group links to the content for the group through a TargetGroupXRef object.

Data Members

Data Member Name | Data Type | Default Value | Description
SiteName | WSTR | None | Stores the site associated with the object.
TargetGroupName | WSTR | None | Stores the name of the group of targets.
TargetGroupNum | LONG | 0 | Stores the unique key for the object.

Class Key

TargetGroupKey is composed of a single data member, TargetGroupNum.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
TargetGroupTarget | TargetGroup | Target | 2
TargetGroupTargetGroupXRefRel | TargetGroup | TargetGroupXRef | 2


TargetGroupXRef

This class cross-references a target group with the custom content for the target group. Target objects form target groups by linking with a TargetGroup object. The custom content, represented by a CampaignItem object, links to the TargetGroup object through the TargetGroupXRef object.

Data Members

Data Member Name | Data Type | Default Value | Description
CampItemNum | LONG | 0 | Key member
SiteName | WSTR | None | Stores the name of the site associated with the object.
TargetGroupNum | LONG | 0 | Key member

Class Key

TargetGroupXrefKey is composed of the following data members:

CampItemNum + TargetGroupNum

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
CampaignItemTargetGroupXRefRel | CampaignItem | TargetGroupXRef | 2
TargetGroupTargetGroupXRefRel | TargetGroup | TargetGroupXRef | 2


TaskHistory

This class tracks Data Transformation Services (DTS) task execution and the outcome of the execution. It maintains a history of all the imports (and deletes) that have occurred within the Data Warehouse.

Data Members

Data Member Name | Data Type | Default Value | Description
CommerceSiteName | WSTR | None | None
Description | WSTR | None | None
DetailLevel | WSTR | None | None
EndTime | FILETIME | None | None
OlapExport | SHORT | None | None
OperationDetailID | LONG | None | None
OperationID | LONG | None | None
SourceInfo | WSTR | None | None
StartTime | FILETIME | None | None
Status | LONG | None | None
TaskID | LONG | 0 | Stores the unique key for the object.

Class Key

TaskHistoryKey is composed of a single data member, TaskID.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
TaskHistoryBasket | TaskHistory | Basket | 2
TaskHistoryCampaignEvent | TaskHistory | CampaignEvent | 2
TaskHistoryCampaignItemEventsByDateAndUser | TaskHistory | CampaignItemEventsByDateAndUser | 2
TaskHistoryFirstUriByDate | TaskHistory | FirstUriByDate | 2
TaskHistoryHitsByHour | TaskHistory | HitsByHour | 2
TaskHistoryHitsInfo | TaskHistory | HitsInfo | 2
TaskHistoryLastUriByDate | TaskHistory | LastUriByDate | 2
TaskHistoryOpenUserVisitRel | TaskHistory | OpenUserVisit | 2
TaskHistoryOrder | TaskHistory | Order | 2
TaskHistoryRequestByDateByUriByQueryString | TaskHistory | RequestByDateByUriByQueryString | 2
TaskHistoryRequestRel | TaskHistory | Request | 2
TaskHistoryUniqueUserKeyByDate | TaskHistory | UniqueUserKeyByDate | 2
TaskHistoryVisitInfoRel | TaskHistory | VisitInfo | 2
TaskHistoryVisitRel | TaskHistory | Visit | 2


UniqueUserKeyByDate

The class represents a summarization of user information grouped by date.

Data Members

Data Member Name | Data Type | Default Value | Description
CountRequests | ULONG | 0 | None
Date | FILETIME | 1900-1-1 0:0:0.0 | Key member
SiteName | WSTR | Not available | Key member
TaskID | LONG | 0 | Key member
userKey | UUID | {00000000-0000-0000-0000-000000000000} | Key member
VisitCount | LONG | 0 | None

Class Key

UniqueUserKeyByDateKey is composed of the following data members:

Date + SiteName + TaskID + userKey

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
DateUniqueUserKeyByDate | Date | UniqueUserKeyByDate | 2
LogUserUniqueUserKeyByDate | LogUser | UniqueUserKeyByDate | 2
SiteUniqueUserKeyByDate | Site | UniqueUserKeyByDate | 2
TaskHistoryUniqueUserKeyByDate | TaskHistory | UniqueUserKeyByDate | 2


URI

This class represents Uniform Resource Identifiers (URIs) used to distinguish a Uniform Resource Locator (URL), as well as make queries and transactions on Commerce Server 2000 Web sites. A URI object associates with the Commerce Server 2000 Web site through a SiteURL object.

A site is identified by a SiteURL object, which stores the first portion, or top level, (for example, domain name) of a site and a linked URI object, which stores the remainer of the URL for the site. If the URI object represents a hierarchical directory structure, it will be linked to the appropriate LevelNDir objects.

A business transaction may occur through a URI query; this is represented by a link between one or more Request objects and the URI object.

A URI object only represents a page, not graphics, banners, and so on.

Data Members

Data Member Name | Data Type | Default Value | Description
DirName1 | WSTR | / | None
DirName2 | WSTR | Inherited | None
DirName3 | WSTR | Inherited | None
DirName4 | WSTR | Inherited | None
DirName5 | WSTR | Inherited | None
DirName6 | WSTR | Inherited | None
Title | WSTR | None | Stores a title for the URI.
URI | WSTR | Not available | Stores the unique key for the object.
URL | WSTR | Not available | None

Class Key

URIKey is composed of a single data member, URI.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
Level1DirURIRel | Level1Dir | URI | 2
Level2DirURIRel | Level2Dir | URI | 2
Level3DirURIRel | Level3Dir | URI | 2
Level4DirURIRel | Level4Dir | URI | 2
Level5DirURIRel | Level5Dir | URI | 2
Level6DirURIRel | Level6Dir | URI | 2
SiteURLURIRel | SiteURL | URI | 2
UriBasket | URI | Basket | 2
UriCampaignEvent | URI | CampaignEvent | 2
uriFirstUriByDate | URI | FirstUriByDate | 2
uriHitsInfo | URI | HitsInfo | 2
uriLastUriByDate | URI | LastUriByDate | 2
UriOrder | URI | Order | 2
UriRequest | URI | Request | 194
uriRequestByDateByUriByQueryString | URI | RequestByDateByUriByQueryString | 2


URIQuery

This class represents a Uniform Resource Identifier (URI) query associated with one or more transaction requests. A URIQuery object links to one or more Request objects.

Data Members

Data Member Name | Data Type | Default Value | Description
QueryString | WSTR | No query string | Stores the unique key for the object.

Class Key

URIQueryKey is composed of a single data member, QueryString.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
URIQueryRequest | URIQuery | Request | 2
URIQueryRequestByDateByUriByQueryString | URIQuery | RequestByDateByUriByQueryString | 2


UserAgent

This class represents the software infrastructure, such as the operating system and browser, used by a user in a visit to a Web site. A UserAgent object links to one or more Request objects and one or more VisitInfo objects.

Data Members

Data Member Name | Data Type | Default Value | Description
Processed | BOOL | 0 | None
UserAgentBrowserCategoryID | ULONG | 1 | None
UserAgentName | WSTR | Not available | Stores the unique key for the object.
UserAgentOperatingSystemID | ULONG | 1 | None
UserAgentPortalID | ULONG | 1 | None
UserAgentSecurityID | ULONG | 1 | None
UserAgentVersionID | ULONG | 1 | None

Class Key

UserAgentKey is composed of a single data member, UserAgentName.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
UserAgentOpenUserVisit | UserAgent | OpenUserVisit | 2
UserAgentRequest | UserAgent | Request | 194
UserAgentVisitInfo | UserAgent | VisitInfo | 194


VirtualServer

This class represents a virtual server, which logically binds independent Web sites to one or more servers.

The Web sites associated with the virtual server are represented through a set of SiteURL objects. The binding to a server occurs through association with one or more ServerBinding objects.

The VirtualServer object may be a part of a larger group of servers. If this occurs, the VirtualServer objects will be linked through a ServerGroup object.

If business transactions are made through a Uniform Resource Identifier (URI) to the virtual server, a Request object is linked through the appropriate SiteURL and URI objects.

Data Members

Data Member Name | Data Type | Default Value | Description
Description | WSTR | None | Stores a description of the virtual server.
DirIndexes | WSTR | None | Stores the directory indices for the virtual server.
HostHeaderName | WSTR | Not available | None
IPAddress | WSTR | 0.0.0.0 | None
IPPort | LONG | 0 | None
LocalDomain | WSTR | None | Stores the name of the local domain for the virtual server.
ServerGroupName | WSTR | Not available | None
VServerName | WSTR | Not available | Stores the unique key for the object.
VServerType | LONG | None | Stores a code for the type of virtual server.

Class Key

VirtualServerKey is composed of a single data member, VServerName.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
ServerBindingVirtualServerRel | ServerBinding | VirtualServer | 2
ServerGroupVirtualServerRel | ServerGroup | VirtualServer | 2
VirtualServerSiteURLRel | VirtualServer | SiteURL | 3


Visit

This class records information describing user activity on a Commerce Server 2000 Web site. A Visit object is associated with a LogUser object and a Site object. The LogUser object contains information about the user. A Visit object describes the context of a visit, including the time and date of the visit.

Data Members

Data Member Name | Data Type | Default Value | Description
DateCreated | FILETIME | None | None
HasCookie | SHORT | None | None
IPAddress | WSTR | 0.0.0.0 | None
SiteName | WSTR | Not available | None
TaskID | LONG | 0 | None
Timestamp | FILETIME | None | Records when the visit started.
UserDomainName | WSTR | None | None
UserID | WSTR | Not available | None
UserKey | UUID | {00000000-0000-0000-0000-000000000000} | None
UserName | WSTR | Not available | None
VisitNum | IDENTITY | 0 | Stores the unique key for the object.

Class Key

VisitKey is composed of a single data member, VisitNum.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
SiteVisitRel | Site | Visit | 2
TaskHistoryVisitRel | TaskHistory | Visit | 2
UserVisit | LogUser | Visit | 194


VisitInfo

This class represents information about a completed visit to a Web site. If a visit has not been completed at log import time, an OpenUserVisit object is instantiated instead.

The VisitInfo class is the primary structure for recording user activity on a Commerce Server 2000 Web site. Someone who interacts with a Commerce Server 2000 Web site is called a user. The VisitInfo class records information describing user activity.

A VisitInfo object is associated with a LogUser object and a UserAgent object. The LogUser object contains information on the user. The UserAgent object contains information describing the software and computer the user is using.

A VisitInfo object describes the context of a visit, including the time and date of the visit. The VisitInfo object links to a Date structure that contains date information.

Data Members

Data Member Name | Data Type | Default Value | Description
CountOfRequest | ULONG | None | None
Duration | ULONG | None | None
FirstHTimeStamp | FILETIME | None | None
FirstRequestNum | IDENTITY | None | None
FirstTimeStamp | FILETIME | None | Stores the time the visit started.
FirstUri | WSTR | Not available | None
LastRequestNum | IDENTITY | None | None
LastUri | WSTR | Not available | None
Processed | BOOL | 0 | None
ReferrerDomainName | WSTR | Not available | None
SecondRequestNum | IDENTITY | None | None
SecondUri | WSTR | Not available | None
SiteName | WSTR | Not available | None
TaskID | LONG | 0 | None
UserAgentBrowserCategoryID | ULONG | 1 | None
UserAgentName | WSTR | Not available | None
UserAgentOperatingSystemID | ULONG | 1 | None
UserAgentPortalID | ULONG | 1 | None
UserAgentSecurityID | ULONG | 1 | None
UserAgentVersionID | ULONG | 1 | None
UserID | WSTR | Not available | None
UserKey | UUID | {00000000-0000-0000-0000-000000000000} | None
VisitNum | IDENTITY | 0 | Stores the unique key for the object.

Class Key

VisitInfoKey is composed of a single data member, VisitNum.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
DateVisitInfoFirstTimeStamp | Date | VisitInfo | 2
ReferrerDomainVisitInfo | ReferrerDomain | VisitInfo | 194
RegisteredUserVisitInfoRel | RegisteredUser | VisitInfo | 2
SiteVisitInfoRel | Site | VisitInfo | 2
TaskHistoryVisitInfoRel | TaskHistory | VisitInfo | 2
UserAgentVisitInfo | UserAgent | VisitInfo | 194
UserVisitInfo | LogUser | VisitInfo | 2


Win32Status

This class represents the Win32 status codes as stored in the Web log file.

Data Members

Data Member Name | Data Type | Default Value | Description
Win32Status | ULONG | 0 | Stores the unique key for the object.

Class Key

Win32StatusKey is composed of a single data member, Win32Status.

Relations

For a description of the relation type, see Data Warehouse Classes.

Relation Name | Parent | Child | Type
Win32StatusHitsInfo | Win32Status | HitsInfo | 2
Win32StatusRequest | Win32Status | Request | 194


Data Warehouse Meta-Model

The meta-model of the Commerce Server 2000 Data Warehouse is a set of definitions used to construct the Data Warehouse logical schema. These definitions, or meta-data, describe how to create classes, data members, relations, and keys. Additionally, the meta-data describes the data source used for the logical schema. The primary purpose of the meta-data is to separate the logical schema from the physical schema. The logical schema may be accessed and extended without detailed knowledge of the underlying physical store. Using the values given to the meta-data attributes, the OLE DB Provider for Commerce Server creates the physical tables and columns to store the user data. This ensures consistency and simplifies the use of the Data Warehouse. For information about creating a new class of objects, see Extending the Data Warehouse.

Note

  • When accessing the meta-data tables through ActiveX Data Objects (ADO), fields appear in the returned Record object in addition to those listed in the tables. ADO does not recognize the objects contained in these fields and produces a run time error. To access these objects, use OLE DB Provider for Commerce Server. The following is a partial list of these columns (ADO Field objects):

    __COMMIT, __NEXT, ALLMEMBERS, ATTRIBUTES, CHILDCLSDEF, CHILDREFMEMDEF, CLASSGUID, CLSDEF, DEFAULTVIEW, KEYDEFINITIONS, KEYMEMBERS, MEMBERDEF, MEMDEFS, MEMNONREFDEFS, PARENTCLASSES, PARENTCLSDEF, PARENTKEYDEF, PERSISTENTKEYMEMS, REFERENCEMEMBERS, REFMEMBERS, RELMEMDEFS, TOPLEVELMEMBERS

This section contains:

  • Conventions. Describes the values used in the meta-data tables.

  • Class Definition Meta-data. Describes the attributes used for the class definitions.

  • Member Definition Meta-data. Describes the attributes used for the class member definitions.

  • Key Definition Meta-data. Describes the attributes used for the class key definitions.

  • Key Member Definition Meta-data. Describes the attributes used for the key member definitions.

  • Relation Definition Meta-data. Describes the attributes used for the class relation definitions.

  • Relation Member Definition Meta-data. Describes the attributes used for the class member relation definitions.

  • Source Definition Meta-data. Describes the attributes of the data source for the Data Warehouse.


Conventions

Class/Member/Key/Relation Names

  • Valid characters are: a - z, A - Z, 0 - 9, and '_'.

  • The double underscore character, '__', is not allowed.

Requirement Column

  • A value in quotes is required and must be supplied by the user.

  • An unquoted value indicates the default, which can be overridden by the user.

  • "Leave blank" indicates that the attribute should not be assigned.

  • "Optional" indicates that the value is user-assigned but can be left blank.

  • "Required" indicates that the value is user-assigned and required.


Class Definition Meta-data

The Class meta-data contains attributes used to define a class. The OLE DB Provider for Commerce Server creates the tables and links required to store the class information based on the attribute values. A class defines a set of logically related data. Classes typically model physical objects (user, product, server, organization) or conceptual entities (visit, Web hit, event). Classes are combined into logical structures through class relations.

For an overview of the logical grouping of these classes into primary business categories, see Primary Business Categories.

For information about creating a new class, see Creating a New Class.

The following table shows the attributes used for the class definitions. A set of these attributes is stored in the ClsDef table for each class defined.

Attribute | Data Type | Constraint | Requirement | Description
ClassDefID | int | NOT NULL | Leave blank | Stores the unique identifier for the class.
BaseClassName | nvarchar (128) | NULL | Optional | Stores the name of the base class. Used for aggregations.
CatalogID | int | NULL | Leave blank | Stores the identifier for the schema catalog.
CatalogName | nvarchar (128) | NULL | Leave blank | Stores the name of the schema catalog, "DWSchema."
ClassDefName | nvarchar (128) | NULL | Required | Stores the name of the class.
ClassGUID | varbinary (16) | NULL | Leave blank | Stores the GUID for the class.
ClassType | smallint | NULL | Optional | Stores the class type. Valid types are: 0 = cdtNone 1 = cdtDimension 2 = cdtFact 3 = cdtAggregation
CreatedTime | datetime | NULL | Leave blank | Stores the time the class was created.
DefaultParentURL | nvarchar (128) | NULL | Leave blank | Stores the default parent URL for the class.
DefaultTableName | nvarchar (128) | NULL | Leave blank | Stores the default table name associated with the class. If this is left blank or if GenerateTableDef = True, the name of the class is used.
Description | nvarchar (128) | NULL | Optional | Stores the description of the class for potential UI display.
DisplayName | nvarchar (128) | NULL | Optional | Stores the name used for potential UI display.
GenerateIdentity | tinyint | NULL | Leave blank | True (1) indicates the ID for the class will be generated automatically.
GenerateKeyDef | tinyint | NULL | 1 | True (1) indicates the class key definition will be generated automatically.
GeneratePartitionDef | tinyint | NULL | Leave blank | True (1) indicates the partition definition will be generated automatically.
GenerateTableDef | tinyint | NULL | Leave blank | True (1) indicates the table definition will be generated automatically.
IdSize | int | NULL | Leave blank | Stores the size of the identifier data in bytes.
InstExclusionExpr | nvarchar (128) | NULL | Optional | Used as a filter for aggregations.
IsAbstract | tinyint | NULL | 0 | Indicates if the class is abstract.
IsActive | tinyint | NULL | 1 | Indicates if the class is active (instances may be added).
IsPersistent | tinyint | NULL | 1 | Indicates if the class is persisted in the underlying data store.
IsReadOnly | tinyint | NULL | 0 | Indicates if the class is read-only.
IsTransactioned | tinyint | NULL | Optional for PROFILING SYSTEM. Leave blank for Analysis | Used by the Profiling System.
IsUIDeletedEnabled | tinyint | NULL |  | Reserved.
MajorVersion | int | NULL | Optional | Stores the major version number for the class.
MinorVersion | int | NULL | Optional | Stores the minor version number for the class.
ModifiedTime | datetime | NULL | Leave blank | Stores the last time the class was modified.
PartCriteriaExpr | nvarchar (128) | NULL | Leave blank | Not used.
PartitionID | int | NULL | Leave blank | Reserved.
PartitionName | nvarchar (128) | NULL | Leave blank | Stores the name of the default partition for the class.
PartViewName | nvarchar (128) | NULL | Leave blank | Reserved.
SourceDefName | nvarchar (128) | NULL | Required | Stores the name of the data source.
SourceID | int | NULL | Leave blank | Stores the identifier for the data source.
Status | int | NULL | Leave blank | Reserved.


Member Definition Meta-data

The Member meta-data contains attributes used to add a data member to an existing class. The attributes of these members include the name of the data member, the data type of the data member, and others. The provider populates the tables in the underlying store with columns configured using these meta-data attribute values.

In order to create a member of a class, the Class definition must already be created. The ClassDefName attribute creates the actual link to the encompassing class; thus the class name must match the ClassDefName attribute for the encompassing class.

For information about creating a new data member for an existing class, see Creating a New Class Data Member.

The following table shows the attributes used for the data member definitions. A set of these attributes is stored in the MemDef table for each class member defined.

Attribute | Data Type | Constraint | Requirement | Description
MemberDefID | int | NOT NULL | Leave blank | Stores the unique identifier for the data member.
CatalogID | int | NULL | Leave blank | Stores the identifier for the schema catalog.
CatalogName | nvarchar (128) | NULL | Leave blank | Stores the name of the schema catalog, "DWSchema."
ClassDefID | int | NULL | Leave blank | Stores the identifier of the containing class.
ClassDefName | nvarchar (128) | NULL | Required | Stores the name of the containing class.
ColumnID | int | NULL | Leave blank | Stores the identifier of the column for the data member.
ColumnName | nvarchar (128) | NULL | Required if GenerateColumnDef = False, otherwise leave blank | Stores the name of the column for storing the data member.
CreatedTime | datetime | NULL | Leave blank | Records when the data member definition was created.
DefaultValueAsStr | nvarchar (128) | NULL | Optional | Stores the default value of the data member as a string. If this is not NULL, the IsDfltNull attribute should be set to False.
Description | nvarchar (128) | NULL | Optional | Stores the description potentially displayed in the UI.
DisplayName | nvarchar (128) | NULL | Optional | Stores the name potentially displayed in the UI.
ExpressionStr | nvarchar (128) | NULL | Optional | Used by aggregation classes. Stores the expression string using the data member. Can contain any valid base class member or aggregation function.
GenerateColumnDef | tinyint | NULL | 1 | True (1) indicates the table column definition in the underlying data store should be generated automatically.
IdxFileGroupPolicy | smallint | NULL | Leave blank | Not used.
IsActive | tinyint | NULL | 1 | Indicates if the data member is active (instances may be added).
IsCached | tinyint | NULL | 0 | Indicates if the data member is cached for fast access. Used by the Profiling System only.
IsDateDeleteMember | tinyint | NULL | Optional | Used to determine which date member (for a class with multiple date members) will be used when deleting fact data by date.
IsDfltNull | tinyint | NULL | 0 | Indicates if the default value for the data member is NULL. If a default value is specified, this should be False (0).
IsDimension | tinyint | NULL | Optional | Indicates if the data member represents a dimension.
IsEncrypted | tinyint | NULL | Optional | Indicates if the data member is encrypted. Used by the Profiling System only.
IsExported | tinyint | NULL | 0 | Indicates if children of the class inherit the data member. Used by the Profiling System only.
IsHashingKey | tinyint | NULL | Optional | Indicates if the data member is a hashing key. Used by the Profiling System only.
IsHidden | tinyint | NULL | Optional | Indicates if the data member is hidden.
IsIdentityMember | tinyint | NULL | 0 | Indicates if the data member is an identity data member.
IsJoinKey | tinyint | NULL | Leave blank | Indicates if the data member is used as a join key across classes.
IsMeasure | tinyint | NULL | Optional | Indicates if the data member represents a measure.
IsMultiValued | tinyint | NULL | Leave blank | Indicates if the data member is multi-valued.
IsPersistent | tinyint | NULL | 1 | Indicates if the data member is persisted in the underlying data store.
IsPrimaryKey | tinyint | NULL | Optional | Indicates if the data member is a part of the primary key for the class.
IsPrivate | tinyint | NULL | Optional | Indicates if the data member is private.
IsRDNAttribute | tinyint | NULL | Optional | When referring to an Active Directory data-source, True indicates this is the RDN attribute for the class.
IsRequired | tinyint | NULL | 0 | Indicates if the data member requires a value.
IsSearchable | tinyint | NULL | 0 | Indicates if the data member is searchable.
IsTextSearchable | tinyint | NULL | 0 | Indicates if the data member is searchable by a text search engine.
IsUniqueKey | tinyint | NULL | Leave blank | Indicates if the data member is part of a unique key for the class.
LinkTableName | nvarchar (128) | NULL | Leave blank | Stores the name of the link table for a multi-valued data member.
MajorVersion | int | NULL | Optional | Stores the major version number for the data member definition.
MemberDefName | nvarchar (128) | NULL | Required | Stores the name of the data member.
MinorVersion | int | NULL | Optional | Stores the minor version number for the data member.
ModifiedTime | datetime | NULL | Leave blank | Records when the data member definition was last modified.
OrdinalPosInClass | int | NULL | Leave blank | Indicates the ordinal position of the data member in the class. Used by the Profiling System only.
ParentGroupName | nvarchar (128) | NULL | Leave blank | Stores the name of the parent group. Used by the Profiling System only.
RelationName | nvarchar (128) | NULL | Leave blank | Stores the name of the relation for a member relation object.
Status | int | NULL | Leave blank | Reserved.
TypeID | int | NULL | Leave blank | Stores the identifier code for the data type of the data member.
TypeName | nvarchar (128) | NULL | Required | Stores the name of the data type for the data member. See the table immediately following this table.
UseHashInSearch | tinyint | NULL | Leave blank | Indicates whether to use a hash index when searching for this data member. Used by the Profiling System only.
ValColumnName | nvarchar (128) | NULL | Optional | Stores the name of the value column for the data member. Used when creating multi-value members.
ValTableName | nvarchar (128) | ULL | Optional | Stores the name of the value table. Used when creating multi-value members.

The following table contains the valid data types used for the TypeName attribute of the Member meta-data. Binary data is not supported.

TypeName | Description
BOOL | Boolean (0 or 1)
CURRENCY | 64-bit currency
DATE | Standard date
DATETIME | SQL datetime
FILETIME | Standard file date/time stamp
IDENTITY | 48-bit numerical identifier
IDENTITY6 | 48-bit numerical identifier
INT64 | 64-bit integer
LONG | 32-bit integer
LONGREAL | 64-bit floating point number
None | Empty type
NULL | No value
REAL | 32-bit floating point number
SHORT | 16-bit integer
TIME | Standard time
UINT64 | 64-bit unsigned integer
ULONG | 32-bit unsigned integer
UUID | Packed decimal number used for GUIDs
WORD | 16-bit unsigned integer
WSTR | Unicode string of length 255
WSTR8, WSTR12. WSTR16, WSTR24, WSTR32, WSTR48, WSTR64, WSTR80, WSTR96, WSTR112, WSTR128, WSTR144, WSTR160, WSTR255, WSTR400, WSTR512 | Unicode string of designated length


Key Definition Meta-data

The Key meta-data contains attributes for defining a key for a class. A key defines the unique identification for a class. Use the Key meta-data to manually specify a single key or to create a multi-part key.

In order to create a key, the Class definition must already be created. The ClassDefName attribute creates the actual link to the encompassing class; thus the class name in the ClassDefName attribute must match the ClassDefName attribute for the wanted class.

Instead of using the Key and Key Member meta-data, a single key may be set through the IsPrimaryKey attribute of the Member meta-data. Multi-valued keys must always be defined using the Key and Key Member meta-data.

For information about creating a new class key, see Creating a New Class Key.

The following table shows the attributes used for the class key definitions. A set of these attributes is stored in the ClsKeyDef table for each class key defined.

Attribute | Data Type | Constraint | Requirement | Description
ClassKeyDefID | int | NOT NULL | Leave blank | Stores the unique identifier for the key.
CatalogID | int | NULL | Leave blank | Stores the identifier for the Commerce Server 2000 schema catalog.
CatalogName | nvarchar (128) | NULL | Leave blank | Stores the name of the schema catalog. For this release of Commerce Server, the catalog name is "DWSchema."
ClassDefName | nvarchar (128) | NULL | Required | Stores the name of the class associated with the key.
ClassID | int | NULL | Leave blank | Stores the identifier of the class associated with the key.
ClassKeyDefName | nvarchar (128) | NULL | Required | Stores the name of the class key.
CreatedTime | datetime | NULL | Leave blank | Records when the key was created.
Description | nvarchar (128) | NULL | Optional | Stores the description for the key potentially displayed on the UI.
DisplayName | nvarchar (128) | NULL | Optional | Stores the name potentially displayed on the UI for the key.
IsPrimaryKey | tinyint | NULL | Optional | Indicates if this is the primary key. Defaults to False (0).
MajorVersion | int | NULL | Optional | Stores the major version number for the key.
MinorVersion | int | NULL | Optional | Stores the minor version number for the key.
ModifiedTime | datetime | NULL | Leave blank | Records when the key was last modified.
Status | int | NULL | Leave blank | Reserved.


Key Member Definition Meta-data

The Key Member meta-data contains attributes for defining a member of a key. The meta-data includes an indication of the ordinal position of the data member for a multi-valued key. The Key and Member definitions must already be completed. A Key Member definition is not required if the IsPrimaryKey attribute is set to True on a member definition of the class.

The following paragraph is more relevant for the Profiling System than for Data Warehouse and Analysis.

Three attributes are required to set a data member as part of a key. The MemDefName attribute of the KeyMem meta-data must be set to the MemberDefName value specified in the Member meta-data. The KeyDefName attribute for the KeyMem meta-data must be set to the ClassKeyDefName value specified in the Key meta-data. Finally, the OrdinalPosInKey attribute must be set to the position in the key for the data member. For example, if there are three data members comprising a key, the OrdinalPosInKey attributes will be set to 0, 1, and 2 for the first, second, and third data members, respectively. The sequence of data members is important for the composition of a unique key.

For information about creating a new key member for a class key, see Creating a New Class Key Member.

The following table shows the attributes used for the key member definitions. A set of these attributes is stored in the KeyMem table for each key member defined.

Attribute | Data Type | Constraint | Requirement | Description
KeyMemID | int | NOT NULL | Leave blank | Stores the unique identifier for the key member.
CatalogID | int | NULL | Leave blank | Stores the identifier for the schema catalog.
CatalogName | nvarchar (128) | NULL | Leave blank | Stores the name of the schema catalog, "DWSchema."
CreatedTime | datetime | NULL | Leave blank | Records when the key member was created.
Description | nvarchar (128) | NULL | Optional | Stores the description for the key member potentially displayed on the UI.
DisplayName | nvarchar (128) | NULL | Optional | Stores the name potentially displayed on the UI for the key member.
KeyDefID | int | NULL | Leave blank | Stores the identifier for the key containing this key member.
KeyDefName | nvarchar (128) | NULL | Required | Stores the name of the class key.
MajorVersion | int | NULL | Optional | Stores the major version number for the key member.
MemDefID | int | NULL | Leave blank | Stores the identifier for the data member used for this key member.
MemDefName | nvarchar (128) | NULL | Required | Stores the name of the data member used for this key member.
MinorVersion | int | NULL | Optional | Stores the minor version number for the key member.
ModifiedTime | datetime | NULL | Leave blank | Records when the key member was last modified.
OrdinalPosInKey | int | NULL | Required | Stores a 0-based index for the position of the key member in the key.
Status | int | NULL | Leave blank | Reserved.


Relation Definition Meta-data

The Relation meta-data contains attributes for creating a relation between two classes. In order to define the relation, the Class definition must already be created for BOTH the parent and child classes. In the Commerce Server 2000 Data Warehouse, most relations are of the one-to-many type.

To link two classes, the ParentClassName attribute for the Relation must be set to the ClassDefName of the parent Class object. Likewise, the ChildClassName attribute for the Relation must be set to the ClassDefName of the child Class object. Any data members in the parent that are marked for inheritance are copied to the child when the relation is created.

To link specific class members, create a Relation Member that defines the members to link for the relation.

For information about creating a new relation between two existing classes, see Creating a New Class Relation.

The Relation definition meta-data contains an attribute used to define the type of the relation (RelType). The following table contains the valid relation types and the corresponding type codes. In the Commerce Server 2000 Data Warehouse, most relations are of the one-to-many type.

Relation Type | Code | Description
One-to-Many | 2 | Each parent has zero or more children, each child has one parent. The identifier ("Classname"ID) of the parent is used as a foreign key by the child.
Many-to-Many | 3 | Each parent has zero or more children, each child has one or more parents.
One-to-Many with Inheritance | 194 | Same as one-to-many except all members of the parent are visible to the children. (In a regular one-to-many relation, only the key members of the parent class are visible.)

The following table shows the attributes used for the class relation definitions. A set of these attributes is stored in the RelDef table for each class relation defined.

Attribute | Data Type | Constraint | Requirement | Description
RelDefID | int | NOT NULL | Leave blank | Stores the unique identifier for the relation.
CatalogID | int | NULL | Leave blank | Stores the identifier for the schema catalog.
CatalogName | nvarchar (128) | NULL | Leave blank | Stores the name of the schema catalog, "DWSchema."
ChildClassID | int | NULL | Leave blank | Stores the class identifier of the child class for the relation.
ChildClassName | nvarchar (128) | NULL | Required | Stores the name of the child class for the relation.
CreatedTime | datetime | NULL | Leave blank | Records when the relation was created.
Description | nvarchar (128) | NULL | Optional | Stores the description potentially displayed in the UI.
DisplayName | nvarchar (128) | NULL | Optional | Stores the name potentially displayed in the UI.
MajorVersion | int | NULL | Optional | Stores the major version number for the relation.
MinorVersion | int | NULL | Optional | Stores the minor version number for the relation.
ModifiedTime | datetime | NULL | Leave blank | Records when the relation was last modified.
ParentClassID | int | NULL | Leave blank | Stores the class identifier of the parent class for the relation.
ParentClassKey | nvarchar (128) | NULL | Required | Stores the name of the key for the parent class.
ParentClassName | nvarchar (128) | NULL | Required | Stores the name of the parent class for the relation.
RelDefName | nvarchar (128) | NULL | Required | Stores the name of the relation.
RefMemName | nvarchar (128) | NULL | Leave blank | Reserved.
RelType | smallint | NULL | Required | Stores the type of the relation.
Status | int | NULL | Leave blank | Reserved.


Relation Member Definition Meta-data

The Relation Member meta-data contains attributes for denormalizing specific members from a parent class into a child class. In order to link specific members within a relation, the Relation definition must already be created. In addition, because the Relation Member specifies the members of the classes that comprise the relation, these class members must also already be defined. The RelationName attribute creates the actual link to the encompassing relation; thus the relation name in the RelationName attribute must match the RelDefName attribute for the wanted relation.

The Member meta-data contains the required fields for defining a class member. The ParentMemName and ChildMemName attributes create the link to the corresponding class members; thus, these names must match the MemberDefName attribute for the required data members in the Member object for the class.

For information about creating a new relation-member for a class, see Creating a New Class Relation Member.

The following table shows the attributes used for the relation member definitions. A set of these attributes is stored in the RelMem table for each relation member defined.

Attribute | Data Type | Constraint | Requirement | Description
RelMemDefID | int | NOT NULL | Leave blank | Stores the unique identifier for the relation member.
CatalogID | int | NULL | Leave blank | Stores the identifier for the schema catalog.
CatalogName | nvarchar (128) | NULL | Leave blank | Stores the name of the schema catalog, "DWSchema."
ChildMemID | int | NULL | Leave blank | Stores the identifier for the data member of the child class to relate.
ChildMemName | nvarchar (128) | NULL | Required | Stores the name of the data member of the child class to relate.
CreatedTime | datetime | NULL | Leave blank | Records when the relation member was created.
Description | nvarchar (128) | NULL | Optional | Stores the description for the relation member potentially displayed on the UI.
DisplayName | nvarchar (128) | NULL | Optional | Stores the name potentially displayed on the UI for the relation member.
MajorVersion | int | NULL | Optional | Stores the major version number for the relation member.
MinorVersion | int | NULL | Optional | Stores the minor version number for the relation member.
ModifiedTime | datetime | NULL | Leave blank | Records when the relation member was last modified.
ParentMemID | int | NULL | Leave blank | Stores the identifier of the data member of the parent class to relate.
ParentMemName | nvarchar (128) | NULL | Required | Stores the name of the data member of the parent class to relate.
RelationID | int | NULL | Leave blank | Stores the identifier of the relation containing the relation member.
RelationName | nvarchar (128) | NULL | Required | Stores the name of the class relation.
Status | int | NULL | Leave blank | Reserved.


Source Definition Meta-data

The Source meta-data describes the data source for the Commerce Server 2000 Data Warehouse. The SourceName and SourceID attributes of the Source meta-data are used in the SourceDefName and SourceID attributes, respectively, of the Class meta-data.

The following table defines the attributes of the SourceDef meta-data.

Attribute | Data Type | Constraint | Requirement | Description
SourceID | int | NOT NULL | Leave blank | Stores the unique identifier for the source.
SourceName | nvarchar (128) | NULL | Required | Stores the name of the data source.
ADDomainName | nvarchar (128) | NULL | Optional for PROFILING SYSTEM. Leave blank for Analysis | Used by the Profiling System only.
CatalogID | int | NULL | Leave blank | Stores the identifier for the Commerce Server 2000 schema catalog.
CatalogName | nvarchar (128) | NULL | Leave blank | Stores the name of the schema catalog. For this release of Commerce Server, the catalog name is "DWSchema."
ClsComponentID | int | NULL | Optional | Used by the Profiling System.
ConnStr | nvarchar (128) | NULL | Required | Stores the connection string for the data source.
CreatedTime | datetime | NULL | Leave blank | Records when the source definition was created.
DBCodePage | int | NULL | Optional | Used by the Profiling System.
Description | nvarchar (128) | NULL | Optional | Stores the description for the source potentially displayed on the UI.
DisplayName | nvarchar (128) | NULL | Optional | Stores the name potentially displayed on the UI for the source.
DoesDistributedTrans | tinyint | NULL | Optional | Indicates if the data source supports distributed transactions.
DoesSQLBatch | tinyint | NULL | Optional | Indicates if the data source supports SQL batch operations.
DoesSQLDelete | tinyint | NULL | Optional | Indicates if the data source supports SQL Delete operations.
DoesSQLInsert | tinyint | NULL | Optional | Indicates if the data source supports SQL Insert operations.
DoesSQLStoredProc | tinyint | NULL | Optional | Indicates if the data source supports storing SQL procedures.
DoesSQLUpdate | tinyint | NULL | Optional | Indicates if the data source supports SQL Update operations.
DoesTransactions | tinyint | NULL | Optional | Indicates if the data source supports transactions.
IsDefault | tinyint | NULL |  | Indicates if this is the default data source.
MajorVersion | int | NULL | Optional | Stores the major version number.
MaxColNameSize | int | NULL | Optional | Stores the maximum size of the names for columns in the data source.
MaxTblNameSize | int | NULL | Optional | Stores the maximum size of the names for tables in the data source.
MinorVersion | int | NULL | Optional | Stores the minor version number.
ModifiedTime | datetime | NULL | Leave blank | Records when the source definition was last modified.
SourceGroupName | nvarchar (128) | NULL | Optional for the Profiling System. Leave blank for Analysis. | Used by the Profiling System only.
Status | int | NULL | Leave blank | Reserved.
Type | int | NULL | Optional | Stores a code for the type of data store. See the table immediately following this table.

The following table contains the valid source types used for the Type attribute of the Source meta-data. This information is more relevant for the Profiling System than for Data Warehouse and Analysis.

Source Type | Code | Description
stOLEDB20 | 1 | Generic OLE DB 2.0
stSQL7x | 2 | SQL Server 7.0 or greater
stSQL65 | 3 | SQL Server 6.5
stActiveDirectory | 4 | Active Directory
stGeneric | 5 | Generic data source


Physical Schema

This topic describes the physical data store underlying the Data Warehouse.

By default, a logical class is mapped to a physical table of the same name. To override this behavior, in the ClsDef table, set the GenerateTableDef attribute to False and specify the table name in the DefaultTableName attribute.

By default, a non-inherited, non-multi-valued class member is mapped to a physical column of the same name. To override this behavior, in the MemDef table, set the GenerateColumnDef attribute to False and specify the column name in the ColumnName attribute.

Inherited class members are mapped to the associated column of the parent table.

For multi-valued class members (IsMultiValued = True in the MemDef table), the associated link and value tables are automatically generated with no provision for overriding the behavior. The names of these tables are stored in the LinkTableName and ValTableName attributes in the MemDef table.

Commerce Server 2000 does not support partitions; thus, there is one partition per data source.


Predictor Schema

This section describes the Predictor schema used for models and model configurations.

Two types of analysis models are available in Microsoft Commerce Server 2000: Prediction models and Segment models. A Prediction model is used to recommend products and fill in missing profile data. A Segment model separates users into segments which are groups of users with similar behavior and attributes. A Segment model is used to categorize a user into one or more of these segments.

These analysis models use a specified set of cases as a basis for their predictions. A case is all that is known about a previous user, and consists of attribute/value pairs. An attribute is some distinction about the world (for example, age, income, whether a particular product was purchased or not, and so on). A case typically contains transactional data and may sometimes contain demographic information.

A model configuration contains information used by the Predictor resource to build the models. This information includes pointers to the tables and views that contain the case information as well as the model build properties. The model configuration is stored as a collection of tables in a database. There is no application programming interface (API) available to create a new model configuration. The tables must be modified directly.

This topic includes descriptions of the required tables and entries, an example of creating a model configuration, and results from building both types of models.

This section contains:

  • PredictorModelCfgs Table. Describes the available model configurations.

  • PredictorDataTables Table. Serves as an index to the source data tables and an attributes table.

  • Attributes Table. Describes attributes about the properties used to build the models.

  • PredictorModels Table. Stores the actual models and the parameters that were used to build them.

  • Predictor Schema Example. Shows an example of creating a model configuration along with the results from building both Prediction and Segment models.

See Also

Prediction Objects

PredictorClient Object

PredictorServiceAdmin Object

PredictorServiceSiteAdmin Object

PredModelBuilder Object

Running the Predictor Resource


PredictorModelCfgs Table

This table lists the model configurations. The model configurations are displayed in Commerce Server Manager when the Model Configurations node, under the Predictor resource, is selected.

Column Name | Type | Description | Required?
ModelCfgName | DBTYPE_WSTR | Model configuration name | Yes
SiteName | DBTYPE_WSTR | Not used | No


PredictorDataTables Table

This table serves as an index to the source data tables and an attributes table. For each model configuration, there must be at least one Dense (Type 0) or Sparse (Type 1) source data table, and one Attributes (Type 2) table. Only one Dense table is allowed, but there can be multiple Sparse tables. A blank attributes table is created if one is not specified.

Column Name | Type | Description | Required?
ModelCfgName | DBTYPE_WSTR | Model configuration name (foreign key to the PredictorModelCfgs table). | Yes
TableName | DBTYPE_WSTR | Table name. | Yes
Type DBTYPE_UI2 Type of table:
  • 0 = Dense (1 row per user, such as for demographic information)

  • 1 = Sparse (1 row per transaction, such as for product purchases)

  • 2 = Attributes
 Yes
AggregateColumn DBTYPE_WSTR Column on which the PivotColumn is aggregated.

For example, QTY if the QTY column represents the quantity of each SKU purchased.

 Yes, if Type = Sparse.

Otherwise should be NULL.
AggregateOperation DBTYPE_UI2 Valid values are:
  • 0 = SUM

  • 1 = MAX

  • 2 = MIN

  • 3 = AVG

  • 4 = COUNT
 Yes, if Type = Sparse.

Otherwise should be NULL.
CaseColumn DBTYPE_WSTR Column in TableName where the case ID (usually UserID) is stored. Yes, if Type = Dense or Sparse.

Not applicable if Type = Attributes.
PivotColumn DBTYPE_WSTR Column in TableName that specifies the transactional property to pivot.

For example, SKU if the SKU column contains the products a user purchased.

 Yes, if Type = Sparse.

Otherwise should be NULL.


Attributes Table

This table indicates the properties of each attribute used in the model, including the distribution type for the attribute, and whether the attribute is used to build the model or is to be predicted by the model. Entries in the attributes table are not required unless the default behavior needs to be overridden. The default behavior is for each attribute to be used for the prediction as well as to be predicted. The default distribution is Autodetect. A blank attributes table is created if one is not specified.

Note

  • There is no table named Attributes. Each model configuration specifies the name of its attribute table as an entry in the PredictorDataTables table.
Column Name | Type | Description | Required?
PropID | DBTYPE_UI4 | Unique key – Property ID. | Yes.
ParentID | DBTYPE_UI4 | ID of parent (0 = root). | Yes.
Name | DBTYPE_WSTR | Name of attribute, hierarchy element, or Pivot Column. | Yes.
TableName | DBTYPE_WSTR | Not used. | No.
ColumnName | DBTYPE_WSTR | Not used. | No.
Distribution DBTYPE_UI2 Distribution type

B - Model As Binary

NB - Not Model As Binary

Valid values are:

  • 0 - Discrete, NB

  • 1 – Continuous, Normal, NB

  • 2 – Continuous, LogNormal, NB

  • 3 - Invalid

  • 4 - Discrete, Autodetect, B

  • 5 - Continuous, Normal, B

  • 6 - Continuous, Lognormal, B

  • A description of the different distribution types follows this table.
 No.

NULL implies Autodetect.

Must be NULL if row describes a hierarchy element.
Predict DBTYPE_BOOL Indicates whether this is an output property.

Valid values are:

  • True (Default) – Build a model that can predict this property.

  • False – Do not predict this property.
 No.

NULL implies True.

Must be NULL if row describes a hierarchy element.
UseToPredict DBTYPE_BOOL Indicates whether this an input property.

Valid values are:

  • True (Default) – Use as input property to predict other properties.

  • False – Do not use this property to predict other properties.
 No.

NULL implies True.

Must be NULL if row describes a hierarchy element.

Distribution Attribute

  • Discrete vs. Continuous. Discrete means that only certain data values are legal and there is no specific relationship between sequential values. For example, the two-letter state abbreviations are discrete. All non-numeric attributes are treated as discrete. Numerical attributes may or may not be discrete.

  • Normal vs. LogNormal. Certain continuous data, such as Income, is better represented as a Normal (Gaussian) distribution while other data, such as the number of products purchased, better fit a LogNormal distribution which is skewed towards 0. An attribute with a LogNormal distribution means the logarithm of the attribute has a Normal distribution.

  • Autodetect. An algorithm to auto-detect the above properties can be used. For discrete attributes, the algorithm also eliminates those attributes that have only one distinct value or too many distinct values to be useful (over 500). Note that "missing" counts as a distinct value.

  • Model As Binary. For a property that has the Model As Binary attribute, the model is only concerned with whether the property exists, not the value of the property. For example, consider the case of an attribute that corresponds to the number of products purchased, it may be more useful to model whether the product was purchased or not, rather than modeling the quantity purchased.


PredictorModels Table

The actual models and the parameters used to build them are stored in this table by the Predictor resource when the models are built. The models are displayed in Commerce Server Manager when the Models node, under the Predictor resource, is selected. In/Out specifies whether the parameter is an input or output parameter. The Model Type specifies which model type uses that parameter. The last column, Data, is a Blob containing the binary representation for the actual model data.

Column Name Data Type In/
Out 		Model
Type 		Description Required?
ModelName | DBTYPE_WSTR | In | Both | Model name. | Yes
ModelCfgName | DBTYPE_WSTR | In | Both | Model configuration name (foreign key to the PredictorModelCfgs table). | Yes
ModelType DBTYPE_UI2 In Both Algorithm used to build the model. Default is Prediction.

Valid values are:

  • 0 = Prediction (Dependency Net)

  • 1 = Segment (Clustering)
 No
BuildTime | DBTYPE_UI4 | Out | Both | Time spent building model (milliseconds). | No
ComplexityPenality DBTYPE_UI4 In Prediction Larger values prevent trees from growing too large (Prediction models only).

Valid range is 1 to MaxInt.

Default = 100

 No
DataFitScore DBTYPE_R8 Out Prediction Measures the quality of predictions made to supply missing profile data. The higher the score, the better the model.

Valid range is minus infinity to plus infinity.

 No
DateCreated DBTYPE_DB
TIMESTAMP 		Out Both Date model was built.

Default is getdate()

 Yes
InputAttributeFraction DBTYPE_R8 In Both Fraction of attributes used for feature selection as input to predictions.

The default number of attributes is 1000 or all attributes, whichever is less.

Valid range is 0 to 1.

  • 1 - use all attributes.

  • < 1 - use feature selection to identify the most significant attributes. Results in a smaller model.
 No
K DBTYPE_UI4 In Segment Number of segments to build.

The default is 10.

Valid range is 1 to 32756.

 No
MaxBufferSize DBTYPE_UI4 In Segment Maximum buffer size in bytes.

Default is 1,056,784 bytes (1 MB)

 No
MeasuredAccuracy
MaxPredictions 		DBTYPE_UI4 In Both Maximum number of recommendation made.

Valid range is 1 to MaxInt.

Default is 10.

 No
MeasuredAccuracy
SampleFraction 		DBTYPE_R8 In Both Fraction of sample data to hold out for automatic accuracy measurement.

Valid range is 0 to 1.

Default is 40% (0.4) of all cases or 1000, whichever is less.

 No
MinimumCasesToSplit DBTYPE_UI4 In Prediction Minimum number of cases for a split to occur in a tree.

Default = 5

 No
OutputAttributeFraction DBTYPE_R8 In Both Fraction of attributes used for feature selection as output of predictions.

The default number of attributes is 1000 or all attributes, whichever is less.

Valid range is 0 to 1.

  • 1 - build a model that can predict all attributes.

  • < 1 - use feature selection to identify attributes that are significant. Results in a smaller model.
 No
RecommendScore DBTYPE_R8 Out Prediction Measures the quality of a ranked list of recommendations. The higher the score, the better the model.

Valid range is 0 to 1.

 No
SampleSize DBTYPE_UI4 In Both Number of cases to randomly sample from the input data.

Default is -1 (use all data) or 20,000, whichever is less.

 No
Data | DBTYPE_BYTES | Blob containing the model data. | No


Predictor Schema Example

This example shows all the related tables and entries for a model configuration named PurchaseCfg1.

PredictorModelCfgs

ModelCfgName | SiteName
PurchaseCfg1 | Retail

This example assumes that the PurchaseCfg1 model configuration consists of three sources of data:

Demographic information from the User table (additional rows not shown).

UserID | Age | Gender | Education
jilluser@roguecellars.com | 23 | F | 19
barneyuser@arborshoes.com | 49 | M | 3
jackuser@frogkick.com | 28 | M | 13

Product Purchase information from the Purchases table (additional rows not shown).

UserID | SKU | QTY
jilluser@roguecellars.com | wine_fine_au_zin_19 | 3
jilluser@roguecellars.com | tv_big_36_m3 | 1
jilluser@roguecellars.com | pumps_bl_6 | 1

Ad Click information from the AdClicks table (additional rows not shown).

UserID | URL | Count
jilluser@roguecellars.com | www.thewinecellar.com/ad_zin12 | 3
jilluser@roguecellars.com | www.thewinecellar.com/ad_cab3 | 2
jilluser@roguecellars.com | www.arborshoes.com/ad4c | 1

PredictorDataTables

ModelCfgName | TableName | Type | Case Column | Pivot Column | Aggregate Column | Aggregate Type
PurchaseCfg1 | User | 0 | UserID | <NULL> | <NULL> | <NULL>
PurchaseCfg1 | Purchases | 1 | UserID | SKU | QTY | 0
PurchaseCfg1 | AdClicks | 1 | UserID | URL | Count | 0
PurchaseCfg1 | PurchaseCfg1_Attributes | 2 | Not applicable | <NULL> | <NULL> | <NULL>

The entries in the following table override the default behavior. The first three entries construct a hierarchy where "tv_big_36_m3" is the child of "TVs" and "TVs" is the child of "Electronic Devices". "Electronic Devices" stands at the top of the hierarchy and therefore does not have a parent. The fourth entry specifies all of the SKUs to have a Discrete and Modeled As Binary distribution. The fifth row specifies to use the Age attribute to predict other attributes, but not to be predicted. This means that no Decision Tree predicting the Age attribute will be built. The entry also specifies the Distribution to be Continuous, Lognormal and not Modeled As Binary.

PredictorAttributes_PurchaseCfg1

Prop ID | Parent ID | Name | Table Name | Column Name | Distri- bution | UseTo Predict | Predict
1 | 0 | Electronic Devices | <NULL> | <NULL> | <NULL> | <NULL> | <NULL>
2 | 1 | TVs | <NULL> | <NULL> | <NULL> | <NULL> | <NULL>
3 | 2 | tv_big_36_m3 | <NULL> | <NULL> | 4 | True | True
4 | 0 | SKU | <NULL> | <NULL> | 4 | True | True
5 | 0 | Age | <NULL> | <NULL> | 2 | True | False

The following table shows two models built from the PurchaseCfg1 model configuration. The first model, Purchase1, was built as a prediction (type 0) model. The second model, Demog1, was built as a segment (type 1) model.

PredictorModels

Model Name | ModelCfg Name | Model Type | Date Created | Build Time | Measured Accuracy Sample Fraction | Measured Accuracy Max Predictions | K
Purchase1 | PurchaseCfg1 | 0 | getdate() | 30000 | .05 | 10 | <NULL>
Demog1 | PurchaseCfg1 | 1 | getdate() | 45000 | .05 | 10 | 10

(PredictorModels continued)

Max Buffer Size | Input Attribute Fraction | Output Attribute Fraction | Sample Size | Complexity Penality | Minimum CasesTo Split | Data Fit Score | Recommend Score | Data
<NULL> | 1 | 1 | -1 | 100 | 5 | 11.08 | 0.3946 | <Binary>
1000000 | 1 | 1 | 16000 | <NULL> | <NULL> | 4.177 | 0.1874 | <Binary>


Profiles Schema

The profiles schema defines the structure of profiles. Profiles represent business objects (site users, customers, trading partners, and so on) and correspond to classes in the Commerce Server Data Warehouse.

This topic describes the profiles schema included with Microsoft Commerce Server 2000. The ability to extend or delete these schemas is readily available through the Profile Designer in Commerce Server Business Desk. The Profile Definition snap-in in Commerce Server Manager provides the functionality to create new schemas.

This section contains:

  • Conventions. Explains the table entries used to describe the profiles.

  • Address Profile Schema. Defines a structure for address entities.

  • Organization Profile Schema. Defines a structure for organization entities.

  • UserObject Profile Schema. Defines a structure for registered and anonymous user entities.

See Also

Profile Objects

Profile XML Structures

ProfileObject Object

ProfileService Object


Conventions

This section explains the table entries used to describe the logical profiles schema.

Data Type

This column indicates the data type of the property. For pre-defined profiles, a logical property is mapped to a physical property of the same name, prefixed with the first letter of the data type and an underscore (for example, the logical address_id, a GUID data type, is mapped to the physical g_address_id).

Exported (Exp)

True (1) indicates the property is exported into the Data Warehouse by the Commerce Server 2000 User Import DTS Task. The DTS task extends the Data Warehouse schema to accommodate any new properties. This property is set in the IsExported attribute of the Property element of the XML representation. If IsExported is set to True for at least one property of the profile definition, then the date_last_changed property must be defined on the profile definition.

Group

A group is a collection of related profile properties, for example, a group named GeneralInfo could be a group containing Name, Address, and Phone properties. Group names must be unique to the profile. Property names, even across different groups must also be unique. Profile properties are accessed either by their names or in combination with their group name in the format Group.Property (for example, GeneralInfo.address_line1).

Required (Req)

This column indicates whether the property is required.


Address Profile Schema

An instance of this profile schema stores both user and organization addresses. The profile is mapped to the physical Addresses table. The Commerce Server 2000 User Import DTS Task extends and exports data into the Data Warehouse for properties with the Exported (Exp) attribute marked as True (1). The corresponding class in the Data Warehouse that the Address profiles are exported into is set via the DWClassName attribute of the Address profile and defaults to Address. For information about the table entries, see Conventions.

Property Name | Data Type | Req | Exp | Group | Display Name/ Description
address_id (Primary and Join Key) | GUID | T | T | General Info | AddressID Supplied by the system.
address_line1 | Unicode String | T | F | General Info | AddressLine1
address_line2 | Unicode String | F | F | General Info | AddressLine2
address_name | Unicode String | F | T | General Info | Address Name
address_type | Integer | F | T | General Info | Address Type 0 – Address 1 – ShipTo address 2 – BillTo address
city | Unicode String | F | T | General Info | City
country_code | Unicode String | T | T | General Info | Country (ISO) Code
country_name | Unicode String | F | T | General Info | Country Name
date_created | Date Time | F | T | Profile System | Date Created The default is getdate()
date_last_changed | Date Time | F | T | Profile System | Date Last Changed The default is getdate()
description | Unicode String | F | F | General Info | Description
first_name | Unicode String | F | T | General Info | (User) First Name
id | GUID | F | F | General Info | ID of the organization/user to which this entry refers
last_name | Unicode String | F | T | General Info | (User) Last Name
locale | Integer | F | F | General Info | Locale Id Locale (character set) in which to render the address form
postal_code | Unicode String | T | T | General Info | Postal (zip) Code
region_code | Unicode String | T | T | General Info | Region or State Code
region_name | Unicode String | F | T | General Info | Region or State Name
tel_extension | Unicode String | F | T | General Info | Telephone (number) Extension
tel_number | Unicode String | F | T | General Info | Telephone Number at this address
user_id_changed_by | Unicode String | F | F | General Info | Changed by Person making the last change


Organization Profile Schema

An instance of this profile schema stores data about organizations (trading partners, home companies, subsidiaries, and so on). This profile is not imported into the Data Warehouse by default. For information about the table entries, see Conventions.

Property Name | Data Type | Req | Exp | Group | Display Name/ Description
org_id (Join Key) | GUID | T | F | General Info | OrganizationID Supplied by the system
name (Primary Key) | Unicode String | T | F | General Info | Name
date_created | Date Time | F | F | Profile System | Date Created The default is getdate()
date_last_changed | Date Time | F | F | Profile System | Date Last Changed The default is getdate()
org_catalog_set | Unicode String | F | F | General Info | Organization Catalog Set Specific to the organization
trading_partner_number | Unicode String | F | F | General Info | Trading Partner Number Assigned by the supplier to the customer organization to represent an account number
user_id_admin_contact | GUID | F | F | General Info | Administrative Contact
user_id_changed_by | GUID | F | F | General Info | Changed by Person making the last change
user_id_purchasing_manager | GUID | F | F | Purchasing | Purchasing manager of the buying organization
user_id_receiver | GUID | F | F | General Info | Receiver The default person to receive products shipped from the supplier


UserObject Profile Schema

An instance of this profile schema stores information about both registered and anonymous users. The Commerce Server 2000 User Import DTS Task extends and exports data into the Data Warehouse for properties with the Exported (Exp) attribute marked as True (1). The corresponding class in the Data Warehouse that the UserObject profiles are exported into is set via the DWClassName attribute of the UserObject profile and defaults to RegisteredUser. For information about the table entries, see Conventions.

Property Name | Data Type | Req | Exp | Group | Display Name/ Description
user_id (Join Key) | GUID | T | T | General Info | User ID Supplied by the system by default
logon_name (Primary Key) | Unicode String | T | T | General Info | Logon Name User principle name (Commerce Server Business Desk/Partnerdesk sets to e-mail by default)
account_status | Integer | F | T | Account Info | Account Status Windows account status bitmask (including active/inactive)
date_created | Date Time | F | T | Profile System | Date Created The default is getdate()
date_last_changed | Date Time | F | T | Profile System | Date Changed The default is getdate()
date_registered | Date Time | F | T | Account Info | Date (and time) Registered on the site
email_address | Unicode String | F | T | General Info | Email (address)
fax_extension | Unicode String | F | F | General Info | Fax (Number) Extension
fax_number | Unicode String | F | F | General Info | Fax Number
first_name | Unicode String | F | T | General Info | First Name
last_name | Unicode String | F | T | General Info | Last Name
org_id | GUID | F | F | General Info | Organization ID to which the user belongs
partner_desk_role | Integer | F | F | Business Desk | PartnerDeskRoleFlags Role ID for the user
tel_extension | Unicode String | F | F | General Info | Telephone Extension
tel_number | Unicode String | F | T | General Info | Telephone Number
user_catalog_set | Unicode String | F | F | Account Info | User Catalog Set
user_id_changed_by | GUID | F | F | General Info | Changed by Person making the last change
user_security_password | Unicode String | F | F | General Info | User Password To identify and authenticate the user
user_title | Unicode String | F | F | General Info | User Title (For example, "Purchase Manager")
user_type | Integer | F | T | General Info | User Type 0 = Anonymous 1 = Registered (default)


Database Table Reference

This section provides a list of tables contained in Commerce Server databases. The tables are categorized by product resource. They do not necessarily reflect the distribution of these tables in your configuration. The location of these tables depends on which databases you create when you unpack your site. By default, Commerce Server creates the following databases: Administration, Direct Mailer, Commerce, and Data Warehouse. However, you can divide the Commerce database into smaller databases, based on the resources you install.

This section contains:

  • Administration Database Tables

  • Analysis/Report Database Tables

  • Data Warehouse Database Tables

  • Direct Mailer Database Tables

  • Marketing Database Tables

  • Prediction Database Tables

  • Product Catalog Database Tables

  • Profiles Database Tables

  • Transactions Database Tables

  • TransactionConfig Database Tables


Administration Database Tables

The following tables are contained in the MSCS_Admin database.

Table Name | Description
ExtendedProps | Contains schema for all properties contained in all resources in the system, except those contained in the SystemProps table.
PupDBScripts | Contains SQL scripts used with the GenericPuP object.
ResourceProps | Contains instance data for the properties whose schema are listed in the ExtendedProps table.
Resources | Contains instance data for the properties whose schema are listed in the SystemProps table.
SiteResources | Contains keys (or links) for all resources in a site.
Sites | Lists the sites contained in this database.
SystemProps | Contains schema for properties that all resources must have in common, such as flags.


Analysis/Report Database Tables

The following tables are contained in the Data Warehouse.

Table Name | Description
Report | Describes the attributes used in the main report definition table.
ReportDbObject | Describes database objects created for use in a static report.
ReportDimension | Describes the attributes used to add a dimension to a report.
ReportInstanceDbObject | Describes instances of database objects created for use in a static report.
ReportInstanceParam | Describes the attributes used to store the parameters entered through the user interface for use in query expressions.
ReportParam | Describes the attributes used to add a parameterized query expression to a static report.
ReportStatus | Describes the attributes used to supply status information about a static report.


Data Warehouse Database Tables

The Data Warehouse includes the classes and relations that make up the logical schema and the meta-model used to create them. For information about the tables contained in the Data Warehouse, see Data Warehouse Schema.


Direct Mailer Database Tables

These tables are contained in the Direct Mailer database.

Table Name | Description
Dml_attachments | Contains attributes used to specify file attachments for Direct Mailer jobs.
Dml_job_errors | Contains attributes used to describe errors that occurred during the sending of Direct Mailer messages.
Dml_jobs | Contains a list of Direct Mailer jobs.


Marketing Database Tables

The Marketing tables are found in the database referred to by the Campaigns site resource.

Table Name | Description
Ad_item | Represents scheduled advertising content for a Web page, contains data members describing when the advertisement runs and codes linking the advertisement to the products it represents.
Campaign | Defines the business process involved in running a marketing campaign for an advertiser.
Campaign_item | Represents the content included in a marketing campaign and/or a scheduled advertisement
Campaign_item_types | Describes the types of campaign items available in the marketing system.
Campaigns_version | Contains schema versioning information. If custom campaign item types are created, they should be registered here.
Creative | Contains information on how to display an advertisement or discount.
Creative_property | Describes the substitution strings contained in each creative type, with one entry per substitution string per creative type.
Creative_property_value | Contains values for creative properties.
Creative_size | Describes the size of the slot required to display a given creative on a page.
Creative_type | Contains formatting information describing how to display the creative.
Creative_type_xref | Determines which creative types (templates) are available for each type of campaign item.
Customer | Defines a customer who uses advertising through a Commerce Server 2000 Web site.
Dm_item | Describes scheduled direct mailing items such as address and format information.
Event_type | Categorizes marketing events.
Industry_code | Contains attributes that allow the selection algorithm to prevent showing two ads from the same industry and from different customers on the same page.
Order_discount | Represents discounted sale items. The class contains data members describing the items and conditions of the sale.
Order_discount_expression | Identifies the eligibility requirement expressions for discounts.
Order_discount_misc | For Internal Business Desk use only.
Page_group | Represents a group of custom content items used on a Web page for a marketing campaign.
Page_group_xref | Cross-references custom Web page content with the Web page or logical set of Web pages that contain the content.
Performance_total | Records aggregate counts of events such as clicks and requests for each campaign item.
Target | Defines a target for marketing and custom Web content, such as a particular type of user.
Target_group | Defines a group of targets for marketing and custom Web content.
Target_group_xref | Cross-references a target group with the custom content for the target group.


Prediction Database Tables

The following tables are included in the Data Warehouse.

Table Name | Description
PredictorModelCfgs | Describes the available model configurations.
PredictorDataTables | Serves as an index to the source data tables and an attributes table.
PredictorModels | Stores the actual models and the parameters that were used to build them.


Product Catalog Database Tables

The Product Catalog tables are found in the database referred to by the Product Catalog site resource.

The following table describes each of the tables in a product catalog database.

Table Name | Description
CatalogAttributes | Contains a row for each user defined catalog property definition, describing the attributes of the property.
CatalogDefinitions | Contains a row for each category or product definition.
CatalogDefinitionProperties | Relates category and product definitions to the properties they contain.
CatalogGlobal | Contains a row for each product catalog.
CatalogUsedDefinitions | Records which product or category definitions are in use by one of more catalogs.
CatalogEnumValues | Defines the legal values for the catalog enumeration data type properties.
CatalogStatus | Records the status of import and export operations.
CatalogCustomCatalogs | Contains a row for each custom catalog.
CatalogCustomPrices | Records the custom price rules applied to categories in custom catalogs.
catalogname_ProductsComplete | Contains all the products, product variants, and categories for the catalog named catalogname.
catalogname_Relationships | Contains all the relationships between products and/or categories for the catalog named catalogname.
catalogname_Hierarchy | Records the category hierarchy (parent-child relationships) for the catalog named catalogname.
CatalogSet_Catalogs | Defines the mapping of catalogs to catalog sets.
CatalogSet_Info | Contains a row for each catalog set with details about the catalog set.
CatalogToVendorAssociation | Contains details about a vendor associated with each catalog.


Profiles Database Tables

The Profiles tables are found in the database referred to by the Profiles site resource.

Table Name | Description
Addresses | Contains user and organization addresses. Used to store the Profiling System run-time data collected by the sites.
BlanketPOs | Contains purchase order information. Used to store the Profiling System run-time data collected by the sites.
ClassDef | Contains profile/Data Warehouse schema information.
ClsAttrib | Contains profile/Data Warehouse schema information.
ColDef | Contains profile/Data Warehouse schema information.
CommerceServerCatalogs | Contains profile/Data Warehouse schema information.
ES_ExprExprDeps | Contains the dependencies of expressions on one another.
ES_ExprInfo | Contains information for expressions.
ES_ExprProfDeps | Contains the dependencies of expressions on profiles.
GroupMem | Contains profile/Data Warehouse schema information.
MemAttrib | Contains profile/Data Warehouse schema information.
MemberDef | Contains profile/Data Warehouse schema information.
OrganizationObject | Contains organization object information. Used to store the Profiling System run-time data collected by the sites.
RelDef | Contains profile/Data Warehouse schema information.
SourceAttrib | Contains profile/Data Warehouse schema information.
SourceDef | Contains profile/Data Warehouse schema information.
TableDef | Contains profile/Data Warehouse schema information.
UserObject | Contains user object information. Used to store the Profiling System run-time data collected by the sites.


Transactions Database Tables

The Transactions tables are found in the database referred to by the Transactions site resource.

Table Name | Description
BasketGroup | Holds order groups with status=basket or status=template.
CatalogProducts_AuctionBid | Holds auction item bids.
CatalogProducts_AuctionItem | Describes the items being auctioned.
counters | Contains counters used by the GenId object. For example, it is used for sequential order tracking numbers.
OrderFormHeader | Stores order group information at the order form level.
OrderFormLineItems | Stores order group information at the item level.
OrderGroup | Holds outer-level order group information.
OrderGroupAddresses | Holds the addresses contained in an order group.
TransCategory | Contains the tables the Transaction DTS task will transfer.
TransDimension | Contains the columns that the DTS will display in the user interface. Key fields are transferred by default, and are not displayed in the user interface. The RequiredDim column determines the default column selection in the user interface.
UserFilter | Holds user search state, for customer and partner services.


TransactionConfig Database Tables

The TransactionConfig tables are found in the database referred to by the TransactionConfig site resource.

Table Name | Description
CatalogCache_Virtual_Directory | Contains a list of applications that are using a cache based on catalog information. This table is used by servers in a Web farm to announce that they are caching catalog information to Business Desk.
Decode | Decodes codes (for example 1=basket; 2=template; 3=order).
Region | Holds names and codes for country/region and state/province.
RegionalTax | Contains tax rates for the SampleRegionalTax pipeline component.
ShippingConfig | Contains information on available shipping methods.
TableShippingRates | Contains shipping rate information for StepwiseShipping pipeline components.
TxVirtual_Directory | Contains a list of applications that are using shipping and tax caches. It is used by servers in a Web farm to announce its caches to Business Desk.


Style Sheet Reference

Customizable style sheets, found in files with .css extensions, allow the appearance of whole classes of visual HTML elements to be controlled from one centralized location. Commerce Server Business Desk makes extensive use of two such style sheet files: Bizdesk.css and Navtree.css. The former is used control the look of the content pane, and the latter is used to control the look of the navigation pane.

Notes

  • Extreme care should be exercised when changing styles since unwanted effects may be caused in other areas of Business Desk.

  • Some of the styles defined in these two .css files are no longer used. If they are not listed in this reference, you should assume that they are obsolete.

Since there are hundreds of styles defined in these two files, this reference provides a logical division and brief explanation of these styles.

This section contains:

  • Bizdesk.css. Provides information about the styles designed for controlling the look of the content pane, as defined in the file Bizdesk.css.

  • Navtree.css. Provides information about the styles designed for controlling the look of the navigation pane, as defined in the file Navtree.css.


Bizdesk.css

The customizable style sheet file, Bizdesk.css, defines the styles used within the content pane of Commerce Server Business Desk. These styles can be divided into two broad categories. First, those styles that apply directly to the action page being displayed in the content pane. And second, those styles that apply to one of the HTML components (HTCs) that are commonly used in the action pages.

This section provides further detail about each of these categories.

This section contains:

  • Action Page Styles. Describes the action page styles defined in the file Bizdesk.css.

  • HTML Component Styles. Describes the HTC styles defined in the file Bizdesk.css.


Action Page Styles

Action page styles can be divided into five basic categories: styles that apply to the overall action pages, title bar styles, task bar styles, status bar styles, and find pane styles. This section provides further details based on this division.

This section contains:

  • Base Action Page Styles. Provides information about the styles in the file Bizdesk.css that apply directly to the action page.

  • Title Bar Styles. Provides information about the styles in the file Bizdesk.css that apply to the title bar.

  • Task Bar Styles. Provides information about the styles in the file Bizdesk.css that apply directly to the task bar.

  • Status Bar Styles. Provides information about the styles in the file Bizdesk.css that apply directly to the status bar.

  • Find Pane Styles. Provides information about the styles in the file Bizdesk.css that apply directly to the find pane.


Base Action Page Styles

Action pages in Commerce Server Business Desk have certain basic styles to which they conform, allowing them to be changed centrally, in the file Bizdesk.css.

These styles are defined for certain HTML elements, and also for elements associated with particular class and id attribute values. These three categories of styles are discussed separately below.

Element Styles

A

Defines style characteristics used when rendering an anchor tag.

BODY

Defines base style characteristics used when rendering the body tag.

BUTTON

Defines style characteristics used when rendering a button tag.

DIV

Defines style characteristics used when rendering a DIV tag.

FORM

Defines style characteristics used when rendering a form.

H1

Defines style characteristics used when rendering a first-level heading.

H2

Defines style characteristics used when rendering a second-level heading.

H3

Defines style characteristics used when rendering a third-level heading.

H4

Defines style characteristics used when rendering a fourth-level heading.

H5

Defines style characteristics used when rendering a fifth-level heading.

H6

Defines style characteristics used when rendering a sixth-level heading.

INPUT

Defines style characteristics used when rendering a single line text box element.

LABEL

Defines style characteristics used when rendering a label element.

OPTION

Defines style characteristics used when rendering a selection option element.

P

Defines style characteristics used when rendering a paragraph.

SELECT

Defines style characteristics used when rendering a selection element.

SPAN

Defines style characteristics used when rendering a span element.

SPAN.bdexpandicon

Defines style characteristics used when rendering a span element that has had the class "bdexpandicon" associated with it. The "bdexpandicon" class is used for elements that contain the characters "3", "4", "5", or "6" that are displayed with the Webdings font to produce left, right, up, or down arrows, respectively.

STRONG

Defines style characteristics used when rendering the content that has been designated as strong.

TD

Defines style characteristics used when rendering a normal table cell.

TEXTAREA

Defines style characteristics used when rendering a multi-line text box element.

TH

Defines style characteristics used when rendering a table heading cell.

Class Styles

.bdbutton

Defines a base style for shared characteristics used when rendering buttons in the content pane. This class should be used for any buttons displayed anywhere in Business Desk.

.bdDebug

Defines style characteristics applied to debug text when debugging is enabled by setting the global variable SHOW_DEBUG_TEXT to True in the file Global.asa.

.editPageContainer

Defines style characteristics used when rendering the main page containing element (usually a DIV) on an edit page.

.waitDisplay

Defines style characteristics used when rendering the wait display in the content pane, the ExpressionBuilder HTC, or the ListSheet HTC.

.webdings

Defines style characteristics used when rendering an element using the webding font. The "webdings" class is most often used for elements that contain the characters "3", "4", "5", or "6" that are displayed with the Webdings font to produce left, right, up, or down arrows, respectively.

ID Styles

#bdcontentarea

Defines style characteristics used when rendering the content area containing element (usually a DIV) on an action page, located between the task bar and the status bar.

#bdhelparea

Defines style characteristics used when rendering the help button area, located at the right end of the task bar.


Title Bar Styles

The following styles are associated with the title bar, using the class and id attributes.

Class Styles

.bdcolorbar

Defines style characteristics used when rendering the colored title bar and status bar that distinguishes list pages from edit pages.

.bdcolorbar IMG

Defines style characteristics used to show or hide the title bar image within the colored title bar.

.bdeditmode .bdcolorbar

Defines style characteristics used when rendering the colored title bar and status bar on edit pages.

.bdeditmode .bdcolorbar IMG

Defines style characteristics used when rendering the page title bar image within the colored title bar on edit pages.

ID Styles

#bdtitlebar

Defines style characteristics used when rendering the title bar.

#bdtitletext

Defines style characteristics used when rendering the page title text within the title bar.


Task Bar Styles

The following styles are associated with the task bar, using the class and id attributes.

Class Styles

.bdtaskbutton

Defines style characteristics used when rendering a normal task button.

.bdtaskbutton IMG

Defines style characteristics used when rendering the task icon image within a normal task button.

.bdtaskbuttonmenu

Defines style characteristics used when rendering a dropdown task button.

.bdtaskbuttonmenu IMG

Defines style characteristics used when rendering the task icon image within a dropdown task button.

.bdtaskdisabled

Defines style characteristics used when rendering a task as disabled.

.bdtaskdisabled IMG

Defines style characteristics used when rendering the task icon image within a disabled task.

.bdtaskmenu

Defines style characteristics used when rendering a task menu.

.bdtaskmenu DIV

Defines style characteristics used when rendering a menu item within a task menu.

.bdtaskover

Defines style characteristics used when rendering a task button with the mouse hovering over it.

.bdtaskpress

Defines style characteristics used when rendering a pressed (clicked) task button.

.bdtasktextbutton

Defines style characteristics used when rendering text-based task button (when no task icon is defined).

BUTTON.bdtaskover IMG

Defines style characteristics used when rendering the task icon image associated with a button over which the mouse is hovering.

BUTTON.bdtaskpress IMG

Defines style characteristics used when rendering the task icon image associated with a button that has been pressed (clicked).

ID Styles

#bdtaskarea

Defines style characteristics used when rendering the task button area, located at the left end of the task bar.

#bdtaskbar

Defines style characteristics used when rendering the entire task area, including the areas associated with the id attribute values "bdtaskarea" and "bdhelparea".


Status Bar Styles

The following styles are associated with the status bar, using the class and id attributes.

Class Styles

.bdcolorbar

Defines style characteristics used when rendering the colored title bar and status bar that distinguishes list pages from edit pages.

.bdcolorbar IMG

Defines style characteristics used to show or hide the title bar image within the colored title bar.

.bdeditmode .bdcolorbar

Defines style characteristics used when rendering the colored title bar and status bar on edit pages.

.bdeditmode .bdcolorbar IMG

Defines style characteristics used when rendering the page title bar image within the colored title bar on edit pages.

ID Styles

#bdstatusbar

Defines style characteristics used when rendering the status bar at the bottom of the right pane.

#bdstatusbar IMG

Defines style characteristics used when rendering the animated loading image within the status bar.

#bdstatusbar NOBR

Defines style characteristics used when rendering text within a NOBR element in the status bar.


Find Pane Styles

The following styles are associated with the find pane, using the class and id attributes.

Class Styles

DIV.filtertext

Defines style characteristics used when rendering a DIV element associated with the class attribute value "filtertext". This class is used to format the "Filtered View" text displayed over a filtered list.

.findByContent

Defines style characteristics used to render the element that will be displayed in the find pane. This style should be used on an element of a list page that has the class attribute value "bdfindbycontent" and contains all the UI controls to be displayed in the find pane.

ID Styles

#bdfindbybody

Defines style characteristics used when rendering the portion of the find pane below the title. This is the container drawn by the InsertTaskBar and InsertEditTaskbar routines within which the "id=bdfindbycontent" element for a list page will be displayed.

#bdfindbyclose

Defines style characteristics used when rendering the right-hand portion of the find pane containing the close button.

#bdfindbycontent

Defines style characteristics used when rendering the find by content on a page within the find pane. The element with id "bdfindbycontent" should contain all the UI controls to be displayed in the find pane. It should also have "findByContent" set as its class attribute.

#bdfindbytitle

Defines style characteristics used when rendering the portion of the title text on the left side of the find pane title bar.

#bdfindbytitlebar

Defines style characteristics used when rendering the portion of the find pane containing the title text and the close button.

DIV#bdfindby

Defines style characteristics used when rendering the DIV element containing the entire find pane including the title bar and find content area.

#bdtaskbtnfindclose

Defines style characteristics used when rendering the find pane close button (the "x" in the upper right corner of the find pane).


HTML Component Styles

HTML Component (HTC) styles can be divided into basic categories according to the type of HTC to which they apply. This section provides further details based on this division.

This section contains:

  • Calendar HTC Styles. Provides information about the styles in the file Bizdesk.css that apply to the Calendar HTC used in the drop-down list for the date type EditField HTC.

  • DynamicTable HTC Styles. Provides information about the styles in the file Bizdesk.css that apply to the DynamicTable HTC.

  • EditField HTC Styles. Provides information about the styles in the file Bizdesk.css that apply to the EditField HTC.

  • EditSheet HTC Styles. Provides information about the styles in the file Bizdesk.css that apply to the EditSheet HTC.

  • ExpressionBuilder HTC Styles. Provides information about the styles in the file Bizdesk.css that apply to the ExpressionBuilder HTC.

  • ListBox HTC Styles. Provides information about the styles in the file Bizdesk.css that apply to the ListBox HTC.

  • ListEditor HTC Styles. Provides information about the styles in the file Bizdesk.css that apply to the ListEditor HTC.

  • ListSheet HTC Styles. Provides information about the styles in the file Bizdesk.css that apply to the ListSheet HTC.

  • QueryBuilder HTC Styles. Provides information about the styles in the file Bizdesk.css that apply to the QueryBuilder HTC.

  • TreeView HTC Styles. Provides information about the styles in the file Bizdesk.css that apply to the TreeView HTC.


Calendar HTC Styles

The following styles are associated with the Calendar HTC, using the class attribute. Add the "calendar" class attribute value to an element to create a Calendar HTC instance.

Class Styles

.calendar

Associates an element with the DHTML behavior implemented in the file Calendar.htc. This is used to create a calendar control within the drop-down of the date type EditField HTC.

.WholeCalendar

Defines style characteristics used when rendering the containing table that makes up the Calendar HTC as a whole.

.WholeCalendar .CalTable

Defines style characteristics used when rendering the table containing the grid of days in the Calendar HTC.

.WholeCalendar .DateControls

Defines style characteristics used when rendering the table cell that contains the month and year controls at the top of the Calendar HTC.

.WholeCalendar .Day

Defines style characteristics used when rendering a day cell that is a day in the current month being displayed, and which is not currently selected.

.WholeCalendar .DaySelected

Defines style characteristics used when rendering the currently selected day cell in the Calendar HTC.

.WholeCalendar .DayTitle

Defines style characteristics used when rendering the weekday title cells at the top of the day grid in the Calendar HTC.

.WholeCalendar .OffDay

Defines style characteristics used when rendering a day cell that is either one of the last days of the previous month or one of the first days of the next month instead of a day in the month currently being displayed.


DynamicTable HTC Styles

The following styles are associated with the DynamicTable HTC, using the class attribute. Add the "dynamictable" class attribute value to an element to create a DynamicTable HTC instance.

Class Styles

.dtBtn

Defines style characteristics used when rendering the Accept, Cancel, New, and Remove buttons within the DynamicTable HTC.

.dtContainer

Defines style characteristics used when rendering the main container DIV element for the DynamicTable HTC.

.dtDataRow TD.dtCell

Defines style characteristics used when rendering a normal table cell in the data table for the DynamicTable HTC.

.dtHeaderTable TD

Defines style characteristics used when rendering a normal table cell in the header row of the DynamicTable HTC.

.dtHeaderTable TR

Defines style characteristics used when rendering the header row of the DynamicTable HTC.

.dtTableStyle

Defines style characteristics used when rendering the main table element for the DynamicTable HTC.

.dtTableStyle .dtDataRow

Defines style characteristics used when rendering a row of data in the DynamicTable HTC.

.dtTableStyle .efDisabled

Defines style characteristics used when rendering a disabled EditField HTC in the control row of the DynamicTable HTC.

.dtTableStyle .lsRowOver TD

Defines style characteristics used when rendering normal table data with the mouse hovering over it within the DynamicTable HTC.

.dtTableStyle DIV.dtContainer

Defines style characteristics used when rendering the main container DIV element within the DynamicTable HTC.

.dtTableStyle TH.dtCell

Defines style characteristics used when rendering a table heading cell in the DynamicTable HTC.

.dtTableStyle TR.lsRowSelected TD, .dtTableStyle TR.lsRowSelected INPUT

Defines style characteristics used when rendering a selected data table cell or a selected single line text box in the DynamicTable HTC (an HTML INPUT element of type "password" is used to display data in a password type column so that "*" characters are displayed instead of the password text).

.dynamicTable

Associates an element with the DHTML behavior implemented in the file DynamicTable.htc.

.efField

Defines common style characteristics used when rendering various types of EditField HTCs within the EditSheet and DynamicTable HTCs.

.efHide

Defines style characteristics used when hiding EditField HTC cells in the DynamicTable HTC.


EditField HTC Styles

The following styles are associated with the EditField HTC, using the class attribute. Add the "editfield" class attribute value to an element to create an EditField HTC instance. The node type in the EditField metadata used to describe a particular instance will determine which sub-control type HTC will be associated with the instance (for example, "efText", "efDate", and so on).

Class Styles

.editField

Associates an element with the DHTML behavior implemented in the file EditField.htc.

.efBoolean

Associates an element with the DHTML behavior implemented in the file efBoolean.htc.

.efBoolean INPUT

Defines style characteristics used when rendering the check box that is the child of a Boolean type EditField HTC.

.efBorderless

Defines style characteristics that eliminate any borders on the input element within and EditField HTC.

.efBrowseReadOnly

Defines style characteristics used when rendering elements within any EditField HTC that are defined to require the use of a corresponding browse button.

.efBrowseReadOnly INPUT

Defines style characteristics used when rendering single line text boxes that are defined to require the use of a corresponding browse button within any EditField HTC.

.efBrowseReadOnly TEXTAREA

Defines style characteristics used when rendering multi-line text boxes that are defined to require the use of a corresponding browse button within any EditField HTC.

.efDate

Associates an element with the DHTML behavior implemented in the file efDate.htc.

.efDatePicker

Defines style characteristics used when rendering the dropdown in the date type EditField HTC that reveals the calendar when clicked.

.efDisabled

Defines style characteristics used when rendering an EditField HTC element that has been designated as disabled.

.efDisabled INPUT

Defines style characteristics used when rendering a single line text box within an EditField HTC that has been designated as disabled.

.efDisabled LABEL

Defines style characteristics used when rendering a LABEL element within a Boolean type EditField HTC that has been designated as disabled.

.efDisabled TEXTAREA

Defines style characteristics used when rendering a multi-line text box within a long text type EditField HTC that has been designated as disabled.

.efDownBtn

Defines style characteristics used when rendering the down button associated with the calendar and select type EditField HTCs.

.efDropDown

Defines style characteristics used when rendering the dropdown DIV element associated with the calendar and select type EditField HTCs.

.efEllipsisBtn

Defines style characteristics used when rendering the browse button that can be associated with any of the EditField HTCs.

.efField

Defines common style characteristics used when rendering various types of EditField HTCs within the EditSheet and DynamicTable HTCs.

.efHide

Defines style characteristics used when hiding EditField HTC cells in the DynamicTable HTC.

.efInvalid

Defines style characteristics used when rendering EditField HTCs that contain invalid data or are required and contain an empty value.

.efInvalid INPUT

Defines style characteristics used when rendering single line text boxes that contain invalid data or are required and contain an empty value.

.efInvalid TD DIV

Defines style characteristics used when rendering DIV elements within EditField HTCs that contain invalid data or are required and contain an empty value.

.efInvalid TEXTAREA

Defines style characteristics used when rendering multi-line text boxes within a long text type EditField HTC that contains invalid data or that is required and contains an empty value.

.efNumeric

Associates an element with the DHTML behavior implemented in the file efNumeric.htc.

.efOption

Defines style characteristics used when rendering an option in a select type EditField HTC dropdown list.

.efOptionSelect

Defines style characteristics used when rendering a selected option in a select type EditField HTC dropdown list.

.efPrompt

Defines style characteristics used when rendering prompt text within an EditField HTC.

.efReadOnly

Defines style characteristics used when rendering a read-only EditField HTC.

.efReadOnly INPUT

Defines style characteristics used when rendering a read-only single line text box in an EditField HTC.

.efReadOnly TEXTAREA

Defines style characteristics used when rendering a read-only multi-line text box in a long text type EditField HTC.

.efReadWrite

Defines style characteristics used when rendering a read/write EditField HTC.

.efSelect

Associates an element with the DHTML behavior implemented in the file efSelect.htc.

.efSelectScroll

Defines style characteristics used when rendering a scrollable select type EditField HTC. Select type EditField HTCs that have more than six options will use this style while ones that have fewer options will not.

.efText

Associates an element with the DHTML behavior implemented in the file efText.htc when the subtype is "short" or "password", and defined to be one line tall.

.efTextLong

Associates an element with the DHTML behavior implemented in the file efText.htc when the subtype is "long", and defined to be multiple lines tall.

.efTextLong .efPrompt

Defines style characteristics used when rendering the prompt text within a long text type EditField HTC.

.efTextLong TEXTAREA

Defines style characteristics used when rendering the multi-line text box within a long text EditField HTC.

.efTime

Associates an element with the DHTML behavior implemented in the file efTime.htc.


EditSheet HTC Styles

The following styles are associated with the EditSheet HTC, using the class attribute. Add the "editsheet" class attribute value to an element to create an EditSheet HTC instance.

Class Styles

DIV.esCollapsed

Defines style characteristics used when rendering a collapsed edit group in an EditSheet HTC.

DIV.esCollapsed DIV.esEditgroup

Defines style characteristics used when rendering an edit group within a collapsed DIV element in an EditSheet HTC.

DIV.esContainer

Defines style characteristics used when rendering the container DIV element for an edit group within an EditSheet HTC.

DIV.esEdittitle

Defines style characteristics used when rendering the title DIV element for an edit group within an EditSheet HTC.

DIV.esExpanded

Defines style characteristics used when rendering an expanded edit group in an EditSheet HTC.

DIV.esExpanded DIV.esEditgroup

Defines style characteristics used when rendering an edit group within an expanded DIV element in an EditSheet HTC.

.editSheet

Associates an element with the DHTML behavior implemented in the file EditSheet.htc.

.efField

Defines common style characteristics used when rendering various types of EditField HTCs within the EditSheet and DynamicTable HTCs.

.esEditgroup

Defines style characteristics used when rendering an edit group within an EditSheet HTC.

.esEditgroup DIV.esContainer

Defines style characteristics used when rendering a nested EditSheet HTC container DIV element within an edit group of another EditSheet HTC.

.esEditgroup DIV.esEdittitle

Defines style characteristics used when rendering a nested EditSheet HTC title DIV element within an edit group of another EditSheet HTC.

.esEditgroup SPAN.bdexpandicon

Defines style characteristics used when rendering a span containing the expand icon in a nested EditSheet HTC within an edit group of another EditSheet HTC.

.esEditgroup SPAN.esEditbar

Defines style characteristics used when rendering the span containing the title bar for a nested EditSheet HTC within an edit group of another EditSheet HTC.

.esTableStyle .esDataCell

Defines style characteristics used when rendering a normal data cell (right side of standard layout in an EditSheet HTC) within tables that have their class attribute set to "esTableStyle".

.esTableStyle .esLabelCell

Defines style characteristics used when rendering a label cell (left side of standard layout in an EditSheet HTC) within tables that have their class attribute set to "esTableStyle".

.esTableStyle .reqIcon

Defines style characteristics used when rendering the required icon table cell within tables that have their class attribute set to "esTableStyle".

SPAN.esEditbar

Defines style characteristics used when rendering the span containing the title bar for an EditSheet HTC.

TABLE.esTableStyle

Defines style characteristics used when rendering tables with which the "esTableStyle" class attribute value is associated.


ExpressionBuilder HTC Styles

The following styles are associated with the ExpressionBuilder HTC, using the class and id attributes.

Class Styles

.clsBtnDrop

Defines style characteristics used when rendering the button associated with a dropdown list in the ExpressionBuilder HTC.

.clsClauseBldr

Defines style characteristics used when rendering the QueryBuilder HTC within the ExpressionBuilder HTC.

.clsClauseInput

Defines style characteristics used when rendering a text input element within the ExpressionBuilder HTC.

.clsClauseList

Defines style characteristics used when rendering the clause list within the ExpressionBuilder HTC.

.clsClauseList TR

Defines style characteristics used when rendering a table row within the clause list in the ExpressionBuilder HTC.

.clsDropDown

Defines style characteristics used when rendering the text box associated with a dropdown list in the ExpressionBuilder HTC.

.clsExprBldr

Defines style characteristics used when rendering the ExpressionBuilder HTC.

.clsExprBldr TD

Defines style characteristics used when rendering a normal table cell within the ExpressionBuilder HTC.

.clsExprBldr TH

Defines style characteristics used when rendering a table heading cell within the ExpressionBuilder HTC.

.clsExprRef

Defines style characteristics used when rendering a nested expression reference within the ExpressionBuilder HTC.

ID Styles

#pmGroup, #pmMarker, #pmProfile

Used internally by the QueryBuilder HTC (also within the ExpressionBuilder HTC). Do not modify.


ListBox HTC Styles

The following styles are associated with the ListBox HTC, using the class attribute. Add the "listbox" class attribute value to an element to create a ListBox HTC instance.

Class Styles

.lbDisabled

Defines style characteristics used when rendering a disabled ListBox HTC.

.listBox

Associates an element with the DHTML behavior implemented in the file Listbox.htc.

.listBox .lbHighlighted

Defines style characteristics used when rendering a highlighted item within a ListBox HTC.


ListEditor HTC Styles

The following styles are associated with the ListEditor HTC, using the class and id attributes. Add the "listeditor" class attribute value to an element to create a ListEditor HTC instance.

Class Styles

.listEditor

Associates an element with the DHTML behavior implemented in the file ListEditor.htc.

.listEditor .listSheetF

Defines style characteristics used when rendering a ListSheet HTC embedded within a ListEditor HTC.

.listEditor .lsNoSort

Defines style characteristics used when rendering a non-sortable column heading within a ListEditor HTC.

ID Styles

.listEditor #leListContainer

Defines style characteristics used when rendering the container element for the ListSheet HTC embedded within a ListEditor HTC.


ListSheet HTC Styles

The following styles are associated with the ListSheet HTC, using the class and id attributes. Add the "listsheet" class attribute value to an element to create a ListSheet HTC instance.

Class Styles

.listSheet

Associates an element with the DHTML behavior implemented in the file ListSheet.htc.

.listSheet .lsPageButton

Defines style characteristics used when rendering page buttons in a ListSheet HTC.

.listSheet .lsPageText

Defines style characteristics used when rendering page number text box in a ListSheet HTC.

.listSheet .lsSelectButtons

Defines style characteristics used when rendering the selection buttons in a ListSheet HTC.

.listSheetF

Associates an element with the DHTML behavior implemented in the file ListSheetF.htc. This is a stripped down version of the ListSheet that does not support hierarchical lists, paging or multi-selection. This HTC is embedded within the ListEditor HTC.

.listSheetF TR

Defines style characteristics used when rendering a data table row in the ListSheet HTC used in the ListEditor HTC.

.lsListArea

Defines style characteristics used when rendering the scrollable area containing rows of data in a ListSheet HTC.

.lsSpacer

Defines style characteristics used when rendering the column resizing controls in the heading row of a ListSheet HTC.

.lsTableStyle .lsNoSort

Defines style characteristics used when rendering a non-sortable column heading within a ListSheet HTC.

.lsTableStyle .lsRowClosed TD

Defines style characteristics used when rendering normal table cells in a closed row of a ListSheet HTC.

.lsTableStyle .lsSortButton

Defines style characteristics used when rendering a column heading sort button in a ListSheet HTC.

.lsTableStyle TD.lsCell SPAN

Defines style characteristics used when rendering a data-bound span within a table cell in a ListSheet HTC.

.lsTableStyle TD.lsCell SPAN.bdexpandicon

Defines style characteristics used when rendering a expand icon span within a table cell in a ListSheet HTC. This renders as a right arrow when the group is closed and a down arrow when the group is expanded.

.lsTableStyle TD.lsObjectCell

Defines style characteristics used when rendering a sub-object table cell in the detail row of a two-tiered ListSheet HTC.

.lsTableStyle TH.lsCell

Defines style characteristics used when rendering a table heading cell within a ListSheet HTC.

.lsTableStyle THEAD TR

Defines style characteristics used when rendering a table heading row within a ListSheet HTC.

.lsTableStyle TR TR.lsRowClosed TD

Defines style characteristics used when rendering a normal table cell within a closed row in a ListSheet HTC.

.lsTableStyle TR.lsRowOver

Defines style characteristics used when rendering a table row within a ListSheet HTC when the mouse is hovering over it.

.lsTableStyle TR.lsRowSelected, .lsTableStyle TR.lsRowSelected INPUT

Defines style characteristics used when rendering a selected table row within a ListSheet HTC, including one that contains a single-line text box (an HTML INPUT element of type "password" is used to display data in a password type column so that "*" characters are displayed instead of the password text).

TABLE.lsTableStyle

Defines style characteristics used when rendering the table within a ListSheet HTC.

TABLE.selected #objectTable TR .lsCell

Defines style characteristics used when rendering cells within a sub-object table under a selected row in a ListSheet HTC.

TABLE.selected #objectTable TR TH.lsNoSort

Defines style characteristics used when rendering table heading cells as non-sortable in a sub-object table under a selected row in a ListSheet HTC.

TABLE.selected TD.lsCell

Defines style characteristics used when rendering normal data cells within a selected table within a ListSheet HTC.

#objectTable TR TH.lsNoSort

Defines style characteristics used when rendering table heading cells as non-sortable within a detail row in a sub-object table within a ListSheet HTC.

.selected, .selected INPUT

Defines style characteristics used when rendering ListSheet HTC elements that are in selected rows, and single line text boxes that are children of such elements (password columns are displayed using an INPUT element set to type "password" so the value is replaces with "*" characters).

.wait DIV, .wait SPAN, .wait TD, .wait TH, .wait BUTTON, .wait INPUT

Defines style characteristics used when rendering elements that are of the "wait" class, and DIV elements, spans, normal table cells, table heading cells, buttons, and single line text boxes that are children of such elements. This class is used to add a wait cursor to all elements of a ListSheet when it is loading.

.waitDisplay

Defines style characteristics used when rendering the wait display in the content pane, ExpressionBuilder HTC, or ListSheet HTC.

ID Styles

.listSheet #btnSelectAll, .listSheet #btnUnselectAll

Defines style characteristics used when rendering the Select All and the Deselect All buttons in a ListSheet HTC.


QueryBuilder HTC Styles

The following styles are associated with the QueryBuilder HTC, using the class attribute. Add the "/widgets/exprbldHTC/querybuilder.htc" behavior style to an element to create a QueryBuilder HTC instance.

Class Styles

.clsQueryBldr

Defines style characteristics used when rendering the QueryBuilder HTC as a whole.

.clsQueryBldr .clsDisabled

Defines style characteristics used when rendering child elements of the QueryBuilder HTC that have been classified as disabled.

.clsQueryBldr .clsDisabled A

Defines style characteristics used when rendering anchor elements within disabled child elements of the QueryBuilder HTC.

.clsQueryBldr .clsSelected, .clsQueryBldr .clsSelected TD

Defines style characteristics used when rendering child elements of the QueryBuilder HTC that have been classified as selected, as well as normal table cells within any such child elements.

.clsQueryBldr TD

Defines style characteristics used when rendering normal table cells within the QueryBuilder HTC.

.clsQueryBldr TH

Defines style characteristics used when rendering table heading cells within the QueryBuilder HTC.

.clsQueryBldr TR

Defines style characteristics used when rendering table rows within the QueryBuilder HTC.

ID Styles

.clsQueryBldr #menuitem

Defines style characteristics used when rendering menu items in a dropdown list within the QueryBuilder HTC.

.clsQueryBldr #popupmenu

Defines style characteristics used when rendering a pop-up (sub) menu within the QueryBuilder HTC.

.clsQueryBldr #submenumark

Defines style characteristics used when rendering the arrow that indicates the presence of a submenu within the QueryBuilder HTC.


TreeView HTC Styles

The following styles are associated with the TreeView HTC, using the class attribute. Add the "treeview" class attribute value to an element to create a TreeView HTC instance.

Class Styles

.treeView

Associates an element with the DHTML behavior implemented in the file TreeView.htc.

.treeView DIV DIV

Defines style characteristics used when rendering a second-level DIV element within the TreeView HTC.

.treeView DIV.tvClosed DIV

Defines style characteristics used when rendering a second-level DIV element in a closed first-level DIV element in the TreeView HTC.

.treeView DIV.tvDisabled

Defines style characteristics used when rendering a disabled DIV element in the TreeView HTC.

.treeView DIV.tvGroupOver

Defines style characteristics used when rendering a highlighted DIV element that is not a leaf node in the TreeView HTC.

.treeView DIV.tvHide

Defines style characteristics used when hiding a DIV element in the TreeView HTC.

.treeView DIV.tvOver

Defines style characteristics used when rendering a highlighted DIV element that is a leaf node in the TreeView HTC.

.treeView DIV.tvSkip DIV

Defines style characteristics used when rendering a DIV element within a skipped DIV element in the TreeView HTC. Styles including the "tvSkip" class are used to format data elements within a skipped element.

.treeView DIV.tvSkip DIV DIV

Defines style characteristics used when rendering a second-level DIV element under a skipped DIV element in the TreeView HTC. Styles including the "tvSkip" class are used to format data elements within a skipped element.

.treeView DIV.tvSkip DIV LABEL

Defines style characteristics used when rendering a label under a skipped DIV element in the TreeView HTC. Styles including the "tvSkip" class are used to format data elements within a skipped element.

.treeView DIV.tvSkip DIV SPAN

Defines style characteristics used when rendering a span within a DIV element under a skipped DIV element in the TreeView HTC. Styles including the "tvSkip" class are used to format data elements within a skipped element.

.treeView DIV.tvSkip DIV.tvClosed DIV

Defines style characteristics used when rendering a DIV element within a closed DIV element under a skipped DIV element in the TreeView HTC. Styles including the "tvSkip" class are used to format data elements within a skipped element.

.treeView DIV.tvSkip DIV.tvDisabled DIV

Defines style characteristics used when rendering a DIV element within a disabled DIV element under a skipped DIV element in the TreeView HTC. Styles including the "tvSkip" class are used to format data elements within a skipped element.

.treeView DIV.tvSkip DIV.tvHide DIV

Defines style characteristics used when rendering a DIV element within a hidden DIV element under a skipped DIV element in the TreeView HTC. Styles including the "tvSkip" class are used to format data elements within a skipped element.

.treeView DIV.tvSkip LABEL

Defines style characteristics used when rendering a label within a skipped DIV element in the TreeView HTC. Styles including the "tvSkip" class are used to format data elements within a skipped element.

.treeView DIV.tvSkip SPAN

Defines style characteristics used when rendering a span within a skipped DIV element in the TreeView HTC. Styles including the "tvSkip" class are used to format data elements within a skipped element.

.treeView LABEL

Defines style characteristics used when rendering a label within the TreeView HTC.

.treeView LABEL.tvSelected

Defines style characteristics used when rendering a selected label within the TreeView HTC.

.treeView SPAN

Defines style characteristics used when rendering a span within the TreeView HTC.


Navtree.css

The customizable style sheet file Navtree.css defines the styles used within the navigation pane of Commerce Server Business Desk. There are element styles and class styles. Element styles are those that apply to an element regardless of any class or id attribute settings on that element. Class styles are those that apply to one or more element types only if the class attribute has the particular value that is indicated. Often, the situations in which the styles apply are restricted according to some characteristic of a parent or grandparent element.

The remainder of this topic provides further detail about each of these style categories.

Element Styles

.bdcategory NOBR

Defines style characteristics used when rendering text without line breaks in the category level of the navigation pane.

BODY

Defines base style characteristics used when rendering the contents of the body element in the navigation pane.

.categoryhighlight NOBR

Defines style characteristics used when rendering text without line breaks in a highlighted category level entry in the navigation pane.

.categoryhighlight NOBR SPAN

Defines style characteristics used when rendering a span within text without line breaks in a highlighted category level entry in the navigation pane.

DIV.bdcs4 A

Defines style characteristics used when rendering the anchor tag with the link to www.microsoft.com in the navigation pane.

DIV.bdmenu UL

Defines style characteristics used when rendering category-level unordered list elements within the navigation tree.

DIV.bdmenu UL DIV

Defines style characteristics used when rendering DIV elements within the first-level unordered list elements within the navigation tree.

DIV.bdmenu UL UL

Defines style characteristics used when rendering module-level unordered list elements within the navigation tree.

DIV.bdmenu UL UL DIV

Defines style characteristics used when rendering DIV elements within the module-level unordered list elements within the navigation tree.

.expanded NOBR

Defines style characteristics used when rendering text without line breaks within an expanded category in the navigation tree.

HTML

Defines base style characteristics used when rendering any HTML in the navigation pane.

Class Styles

.bdDebug

Defines style characteristics applied to debug text when debugging is enabled by setting the global variable SHOW_DEBUG_TEXT to True in the file Global.asa.

.bdmodule

Defines style characteristics used when rendering a module entry in the navigation pane.

.categoryselect

Defines style characteristics used when rendering a selected category in the navigation pane.

.collapsed SPAN.bdcollapseicon

Defines style characteristics used when rendering the collapsed icon when a category is collapsed in the navigation pane.

.collapsed SPAN.bdexpandicon

Defines style characteristics used to suppress rendering of the expanded icon when a category is collapsed in the navigation pane.

.collapsed UL.bdmodulelist

Defines style characteristics used to suppress rendering of the corresponding modules when a category is collapsed in the navigation pane.

DIV.bdfooter

Defines style characteristics used when rendering the footer area in the navigation pane, which contains the link to Microsoft.com

DIV.bdlogo

Defines style characteristics used when rendering the logo area in the navigation pane, which contains the link to the About dialog box.

DIV.bdmenu

Defines style characteristics used when rendering the DIV element that contains the entire navigation tree in the navigation pane.

DIV.bdscrollwindow

Defines style characteristics used when rendering the scrollable window that contains the entire navigation tree.

.expanded

Defines style characteristics used when rendering an expanded category in the navigation pane.

.expanded SPAN.bdcollapseicon

Defines style characteristics used to suppress rendering of the collapsed icon when a category is expanded in the navigation pane.

.expanded SPAN.bdexpandicon

Defines style characteristics used when rendering the expanded icon when a category is expanded in the navigation pane.

.expanded UL.bdmodulelist

Defines style characteristics used when rendering the corresponding modules when a category is expanded in the navigation pane.

.modulehighlight

Defines style characteristics used when rendering a module that has been highlighted in the navigation pane.

.moduleselect

Defines style characteristics used when rendering a module that has been selected in the navigation pane.

.scrollbtn

Defines style characteristics used when rendering a scroll button at the top or bottom of the navigation pane.


Troubleshooting Commerce Server

This section addresses common problems you may encounter while using Microsoft Commerce Server 2000.

For technical support Microsoft provides online newsgroups through its Web site. For more information about Commerce Server 2000 newsgroups go to: www.microsoft.com/commerceserver/.

You should also review the Microsoft Commerce Server 2000 Readme. This document provides a list of known issues and late-breaking news for this version of Commerce Server and is included on the Commerce Server 2000 Installation CD.

This section contains:

  • Troubleshooting Your Applications. Describes problems you may encounter while developing and managing your applications and Business Desk, and offers possible solutions.

  • Troubleshooting Site Packager. Describes problems your may encounter while using Commerce Server Site Packager, and offers possible solutions.

  • Troubleshooting Commerce Server Resources. Describes problems you may encounter while using DTS tasks, the Predictor resource, the Profiles resource, and Direct Mailer, and offers possible solutions.

  • For Additional Troubleshooting Information. Lists additional troubleshooting resources available to system administrators.


Troubleshooting Your Applications

This section describes problems you may encounter while developing and managing your applications and Commerce Server Business Desk.

This section contains:

  • Use 64-bit currency to ensure availability

  • Orders totaling more than 10 million currency units fail

  • Enable "Trust computer for delegation" for Web servers

  • OLAP/SQL Server requires Windows NT Authentication

  • Length limitation for Active Directory data

  • Ads or discounts do not appear on the Web site

  • Using regtrace.exe with a debugger

  • Cannot log on to a Web application as an administrator

  • Changing computer name causes Commerce Server to stop working

  • Changing system date separators returns an error

  • Search function in Help does not return search results

  • Some DLLs do not support self-registration

  • Creating a new Administration database

  • Business Desk: Changing administrative password disconnects the Business Desk client

  • Business Desk: Adding multi-valued properties

  • Business Desk: Updated configuration not reflected

  • Business Desk: Data does not appear in List Manager or Users modules

  • Business Desk: "Library not registered" or other problems with regexp

  • Business Desk: Users with "Administrator" rights cannot access Business Desk data

  • Business Desk: Run time errors occur when you access Business Desk

  • Business Desk: Cannot access sites when logged into Business Desk as Administrator

  • Reports: Summary of Report Issues

  • Reports: Buyer Browse to Purchase report error

  • Reports: Dynamic SQL reports cannot be viewed

  • Reports: Reports contain no data

For information about debugging your applications, see the following topics:

  • Debugging Tools

  • Debugging Business Desk

  • Content Seletion Framework Concepts


Use 64-bit currency to ensure availability

If a user creates a basket with items that total more than 10 million currency units, the basket becomes unusable. The user receives the message:

An overflow occurred when computing '_product_list_price'. Consult the documentation for information on extending the range.

All subsequent orders for that user will also fail.

Solution

Upgrade currency support in the Pipeline Editor from 32-bit to 64-bit.

To set 64-bit currency

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2000, and then click Pipeline Editor.

  2. Click Open, and then navigate to the location of your pipeline file. Double-click your pipeline file to open it.

  3. On the Edit menu, click Properties.

  4. In the Pipeline Properties dialog box, in the Currency Mode box, select Currency (high-precision), and then click OK.

    Note

    • To run a pipeline in the high-precision mode, the pipeline must not include any Microsoft Site Server 3.0 Commerce Edition pipeline components. For more information about Site Server 3.0 pipeline components, see Pipeline Component Reference.
  5. Restart your Web server(s).

See Also

Orders totaling more than 10 million currency units fail


Orders totaling more than 10 million currency units fail

If a user creates a basket with items that total more than 10 million currency units, the basket becomes unusable. The user receives the message:

An overflow occurred when computing '_product_list_price'. Consult the documentation for information on extending the range.

All subsequent orders for that user will also fail.

Solution

To enable support for orders larger than 10 million currency units, you must upgrade currency support in the Pipeline Editor from 32-bit to 64-bit.

To set 64-bit currency

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2000, and then click Pipeline Editor.

  2. Click Open, and then navigate to the location of your pipline file. Double-click your pipeline file to open it.

  3. On the Edit menu, click Properties.

  4. In the Pipeline Properties dialog box, in the Currency Mode box, select Currency (high-precision), and then click OK.

    Note

    • To run a pipeline in the high-precision mode, the pipeline must not include any Microsoft Site Server 3.0 Commerce Edition pipeline components. For more information about Site Server 3.0 pipeline components, see Pipeline Component Reference.
  5. Restart your Web server(s).


Enable "Trust computer for delegation" for Web servers

Active Server Pages (ASP) pages running on a Web server can set and reset passwords for users stored in Active Directory only if the Web server is trusted for delegation.

Solution

To enable this option, go to the property sheet for the computer account in Active Directory and make sure the Trust computer for delegation check box is checked.

To set the Trust computer for delegation option

  1. Click Start, point to Program Files, point to Administrative Tools, and then click Active Directory Users and Computers.

  2. Navigate to the computer account that needs to be set, for example, Active Directory Users and Computers/<domain name>/Computers/<computer name>.

  3. Double-click the computer name in the list on the right. In the Account tab, check the Account is trusted for delegation check box, and then click OK.

You may need to reboot the associated Web server in order for this setting to take effect.


OLAP/SQL Server requires Windows NT Authentication

If you connect remotely to an SQL Server computer from a different domain or workgroup, Commerce Server Site Packager will fail when it attempts to make the OLE DB for online analytical processing (OLAP) connection for the Data Warehouse.

Solution

The OLE DB for online analytical processing (OLAP) connection for the Data Warehouse requires Microsoft Windows NT authentication.

To establish this, you must create an identical account on the workgroup SQL Server computer, for example, <computername>\share, so that <computername>\share can connect to the Data Warehouse.

Note

  • If SQL Server is in a trusted domain, the domain account must be part of the OLAP Administrative account.

See Also

Enabling Windows Authentication


Length limitation for Active Directory data

If your Commerce Server Business Desk module relies on data stored in Active Directory common names, the maximum length for a string is 64 characters. In addition, organization names stored in Active Directory include a group name (either _Admingroup, which constitutes 11 characters or _Usergroup, which constitutes 10 characters).

Solution

If you are storing an organization name in Active Directory, the maximum length for the combination of the organization name and the group name is 64 characters. Make certain your name is within this limit.


Ads or discounts do not appear on the Web site

The ads or discounts you created and expected to see on your Web site do not appear.

Solution

You can troubleshoot this problem in one of two ways:

  • To use the TraceScores.asp file

  • Using the DumpContentList.asp file

To use the TraceScores.asp file

  1. Copy the TraceScores.asp file from Program Files\Microsoft Commerce Server\SDK\Samples\Marketing\Debug into the virtual directory for your site.

  2. Modify the code that creates the ContentSelector object to add a line to include the TraceScores.asp file.

  3. Add a line that sets the Trace property to True.

  4. Add a line that calls the TraceScores subroutine.

Code Example

The following code example for the TraceScores.asp file contains the added lines in boldface font:

<!-- #include file="TraceScores.asp" -->

<%
    ' Create a ContentSelectorObject
    Set CSO = Server.CreateObject("Commerce.ContentSelector")
    CSO.Trace = true
    ' Use the GetContent method to get some content. Use the dictionary
    ' previously created in the Global.asa and referenced through the
    ' Application collection.
    Set Ads = CSO.GetContent(Application("CSFAdsContext"))
    ' Ads is a SimpleList containing the selected content.
    ' Write the content to the page, if any.
    For Each Ad in Ads
        Response.Write(Ad)
    Next
    Response.Write("<P>")
    Call TraceScores(CSO)
%>

Output Example

When tracing is enabled, all modifications to content item scores are tracked. The ad modifications found by the TraceScore.asp file are shown in boldfaced font in the following example:

ad: Volcano erupts (item_id=1) score: 1.028331

Commerce.CSFAdvertisingNeedOfDelivery,=1.89,Paid Ad Need of Delivery.
Commerce.CSFHistoryPenalty,*0.54,Reselect penalty applied

ad: Cuckoo clock (item_id=2) score: 1.112223

Commerce.CSFAdvertisingNeedOfDelivery,=1.89,Paid Ad Need of Delivery.
Commerce.CSFHistoryPenalty,*0.59,Reselect penalty applied

ad: MSPress (item_id=3) score: 1.012156

Commerce.CSFAdvertisingNeedOfDelivery,=2.02,Paid Ad Need of Delivery.
Commerce.CSFHistoryPenalty,*0.50,Reselect penalty applied

ad: Trey Research (item_id=4) score: 1

Commerce.CSFAdvertisingNeedOfDelivery,=1.00,House Ad Need of Delivery (Weight)

If the ad you expected to see does not appear in the trace, then it was not loaded into the cache. In Commerce Server Business Desk, in the Publish Campaigns module, republish the campaign to the server. If the ad still does not appear, check the following:

  • Check the start and end date for the ad.

  • Ensure that the customer, campaign, and campaign item are active.

Note

  • When the TraceScores flag is set to On, the performance of Content Selection Framework (CSF) pipelines is significantly degraded.

See Also

Campaign items do not appear as expected on the Web site

Tracing and debugging

Using the DumpContentList.asp file

The DumpContentList.asp file is another tool you can use to troubleshoot problems with threads and discount features. This tool displays all the ads or discounts that are currently loaded into memory and all their properties. It also shows the schema of the ContentList object. It can be used to dump the contents of either a ContentList object or a ContentListFactory object.

To use DumpContentList.asp

  1. Copy the DumpContentList.asp file from Program files\Microsoft Commerce Server\SDK\Samples\Marketing\Debug into the virtual directory for your site.

  2. Modify the code that creates the ContentSelector object to add a line to include the DumpContentList.asp file.

  3. Add a line that calls the DumpContentList subroutine.

Code Example

The following example shows the added lines in boldface font:

<!-- #include file="DumpContentList.asp" -->

<%
    ' Create a ContentSelectorObject
    Set CSO = Server.CreateObject("Commerce.ContentSelector")
    ' Use the GetContent method to get some content. Use the dictionary
    ' previously created in the Global.asa and referenced through the
    ' Application collection.
    Set Ads = CSO.GetContent(Application("CSFAdsContext"))
    ' Ads is a SimpleList containing the selected content.
    ' Write the content to the page, if any.
    For Each Ad in Ads
        Response.Write(Ad)
    Next
    Response.Write("<P>")
    Call DumpContentList(CSO.Value("Order").Value("_Content"))
%>


Using regtrace.exe with a debugger

Regtrace.exe is a tool that is used to enable tracing in the following ad and discount components:

  • CacheManager

  • CSFLoadAdvertisements

  • CSFLoadCampaignsCommon

  • CSFLoadDiscount

  • EvalTargetGroups

  • OrderDiscount

To use regtrace.exe

  1. Click Start, and then click Run.

  2. In the Run dialog box, type regtrace.exe, and then click OK.

  3. In the Trace Settings dialog box, on the Traces tab, select the levels of tracing you want.

  4. On the Output tab, select Debugger (OutputDebugString).

  5. Click OK.

  6. You must now connect a debugger such as WinDBG or Visual C++ 6.0, to the process where your site code is running. As the components are read by the tool, trace messages will be logged and will appear in the debugger.

If trace messages are not being logged, perform an Internet Information Services (IIS) Reset and connect to the debugger again.

Note

  • When you enable tracing, performance is adversely affected. You should disable tracing when you are not using it.


Cannot log on to a Web application as an Administrator

You can log onto Commerce Server Business Desk as an administrator, but you cannot log on to another Commerce Server application as administrator.

Solution

This problem is caused by a conflict between Business Desk and Windows domain names. To avoid this situation, create users in Business Desk, and then assign them access privileges by placing them in the appropriate domain groups. Users who need access to Business Desk can be added as domain administrators, and can access Business Desk using their standard user names.


Changing computer name causes Commerce Server to stop

If you change the name of your computer, SQL Server may not automatically find the Administration database. You may receive the following message:

"2735 CA_ADMIN_ValidateDB"

Solution

Change the necessary connection string settings in Commerce Server Manager so that they use the new computer name. The settings you change will depend on the topology used to deploy Commerce Server. Manually edit the fields in the Administrator database to the new name.

You must also delete your current SQL Server registration and then register a new instance of SQL Server. You need to change your SQL Server login and password for the Administration database. You do this by deleting your current SQL Server registration and then registering a new instance of SQL Server. Use the following procedure to register a new SQL Server instance.

To change the SQL Server login and password for the Administration database

  1. In the Microsoft Commerce Server Manager console, right-click Commerce Server Manager, and then click Properties.

  2. In the Commerce Server Manager Properties dialog box, on the Administration Database tab, click Modify.

    The Data Link Properties dialog box appears.

  3. After making the necessary changes in the Data Link Properties dialog box, click OK.

Note

  • For instructions about completing the Data Link Properties dialog box, click Help in the Data Link Properties dialog box to open the Microsoft Data Link Help file.


Changing system date separators returns an error

If you change the system date separator to a character other than a slash (/), period (.), or a dash (-), and then try to open Commerce Server Business Desk, the following error appears:

"Errors occurred while loading part of the Business Desk"

This error occurs only after restarting Internet Information Services (IIS) 5.0.

Solution

Close Business Desk and change the system date separator back to a slash (/).

To change the system data separator

  1. Click Start, point to Settings, and then click on Control Panel.

  2. Double-click Regional Options, and then click the Date tab.

  3. In the Date separator box, select / and then click OK.

    Caution

    • Restarting IIS will cause your Web site to stop running temporarily. Make certain you need to restart IIS before proceeding.
  4. Restart IIS.

  5. Reopen Business Desk.

To restart IIS

  1. Click Start, point to Programs, point to Administrative Tools and then click Internet Services Manager.

  2. Click the plus (+) sign to expand your server name group.

  3. Right click Default Web Site, and then click Stop.

  4. Right click Default Web Site, and then click Start.

IIS is restarted and you can re-open Business Desk.


The Search function in Help does not return search results

When searching for words or topics in Commerce Server Business Desk Help, no search results are returned. The following message appears:

"No documents matched the query <your search text>."

Solution

Start the Indexing Service on the Web server. The Indexing Service should always be set to "Autostart," since there can be a significant time lag between when the service starts and when the folder containing Business Desk Help content is available.

For more information, see "Indexing Service" in Windows 2000 Server Help.


Some DLLs do not support self-registration

Some dynamic-link library (DLLs) files will fail if you try to self-register them using the file Regsvr32.exe. These DLL files are:

BizDataManager.dll
CalcRenderer.dll
CatalogSets.dll
CatalogVendorAssociation.dll
CSDWDTSCatalogImp.dll
CSDWDTSDelete.dll
CSDWDTSIpResolution.dll
CSDWDTSLogImports.dll
CSDWDTSPostImport.dll
CSDWDTSSyncAdmin.dll
CSDWDTSTransImport.dll
DictionaryXMLTransforms.dll
DWMBToAdmin.dll
DWSyncAdmin.dll
Dyntablemarshaler.dll
GenericPup.dll
MSCSCfg.dll
MSCSPredDWHelper.dll
GenericPup.dll
Regionaltax.dll
ReportRenderer.dll
Requisition.dll
CSDWDTSMarketingImport.dll
Shipmgr.dll
Splitter.ocx
UPMDtsHlpr.dll
UPMDTSTask.dll


Creating a new Administration database

You need to roll back to a previous Administration database or create a new one, but you cannot reinstall Commerce Server. Running Commerce Server setup in Repair Mode does not accomplish this either.

Solution

Create a new database named MSCS_Admin and then run the file admin_schema.sql on it using SQL Query Analyzer. A new Administration database is created. Running the script will populate the schema of the Administration database but no resources will be created.

To create a new Administration database

  1. Delete or rename your existing Administration database, if necessary.

  2. Click Start, point to Programs, point to Microsoft SQL Server and then click Enterprise Manager.

  3. In Enterprise Manager, expand Microsoft SQL Servers, expand SQL Server Group, and then expand the name of the server on which you want to create the new Administration database.

  4. Right-click Databases, and then click New Database.

  5. In the Database Properties dialog box, on the General tab, in the Name box, type MSCS_Admin.

  6. Click OK.

Your new database is created. The next step is to run the file admin_schema.sql.

To run the admin_schema.sql file

  1. In Enterprise Manager, click the MSCS_Admin database.

  2. On the Tools menu, click SQL Query Analyzer.

  3. On the File menu, click Open.

  4. Browse to Program Files\Microsoft Commerce Server, and then select the admin_schema file, and then click Open.

  5. On the Query menu, click Execute.

You will need to unpack your sites again and reinstall the Direct Mailer service and Predictor resource using Commerce Server Setup.

Note

  • Immediately after you install your site, and any time you change the configuration of your Commerce Server deployment, you should back up your Administration database using a different name. You can use this copy to roll back any changes that are made later.


Business Desk: Changing the administrative password disconnects the Business Desk client

If you change the administrative password on the server on which Commerce Server Business Desk is installed, errors will appear when the Business Desk client computers attempt to access Business Desk. The following errors may appear:

  • Errors occurred while loading part of the Business Desk.

  • Errors while loading Business Desk application.

Solution

When you change the Commerce Server administrative password on the server, you must also change the password in Component Services and then save the Global.asa file.

To change the password in Component Services

  1. Click Start, point to Programs, point to Administrative Tools, and then click Component Services.

  2. Expand the nodes to the following path: Component Services/Computers/My Computer/COM+Applications/Commerce Event Logging.

  3. Right click Commerce Event Logging, and then click Properties.

  4. In the Commerce Event Logging Properties dialog box, on the Identity tab, in the Password box, type the new password.

  5. In the Confirm password box type the new password again and then click OK.

The password is updated, and Business Desk should now open.

To save the Global.asa file

  1. Navigate to the Business Desk virtual directory. For example, C:\Inetpub\wwwroot\retailbusinessdesk.

  2. Open the Global.asa file in Notepad.

  3. To save your password changes, on the File menu, click Save, and then click Exit.

Changes to the Global.asa file are saved. All users must now close and re-open Business Desk to update the password changes.

Note

  • You must also change the password for Commerce Server services such as List Manager, Direct Mailer, and the Predictor resource.

See Also

Changing a Service Account or Password


Business Desk: Adding multi-valued properties

When you enter multi-valued data in Commerce Server Business Desk, use a semi-colon (;) to separate the values. This applies to user profile data, organization profile data, and expressions in the Campaign Expressions module.

Note

  • If you have added multi-valued properties to the User profile definitions that map to data sources with date or date/time data types, the User profile data import task will export the properties to the Data Warehouse. Commerce Server 2000 does not support multi-value date or date/time members.


Business Desk: Updated configuration not reflected

If you changed the configuration of Commerce Server Business Desk and then stopped and started your Web site, Business Desk is not updated with those changes. The application is not reloaded and it still uses the old .xml files.

Solution

After you have changed the configuration of Business Desk, you must restart Business Desk on the Web server in order for those changes to appear. To do this, you can open and then save the Global.asa file, which changes the "last modified" time and makes the configuration updates appear in Business Desk.

To open and then save the Global.asa file

  1. Click Start, point to Programs, point to Accessories, and then click Notepad.

  2. On the File menu, click Open. Navigate to your Global.asa file, and then double-click the file to open it.On the File menu, click Save to save the Global.asa file without changing it.

  3. To exit Notepad, on the File menu, click Exit.

Changes to the Business Desk configuration are now saved. All Business Desk client users must now close and re-open Business Desk to see the configuration changes.


Business Desk: Data does not appear in List Manager or Users modules

Using the Users and Organizations modules to perform bulk update operations or find by operations against large user data sets may result in the process timing out.

If you are using the List Manager module against a large data set to construct a user list, the same timeout error may occur.

The operation may time out depending upon a variety of factors and you may be unable to view the data. One factor may be the large number of entities being retrieved.

Other factors for this time out may include:

  • Backend configuration (are you using Active Directory only? SQL only? Active Directory and SQL?)

  • Network bandwidth

  • System configuration (slow versus fast computers)

Solution

You may need to perform bulk update operations using a custom script against the OLE DB Provider for Commerce Server. Custom scripts are not subject to the limitations of the Session.Timeout property on the ASP intrinsic Session object. You can set the Session.Timeout property to: <% Session.Timeout = 10 %>. This sets the session timeout to 10 minutes. The Session.Timeout property has a maximum value or 24 hours.

For more information about creating custom scripts for bulk operations , see Code to Perform Bulk Operations Using ADO and SQL.

See Also

WaitOnOperation


Business Desk: "Library not registered" or other problems with regexp

When using Commerce Server Business Desk, if you receive the message "Library not registered" or another message stating that you have a problem with the regexp (Regular Expression) COM object, you may need to unregister and then re-register the Vbscript.dll file, which is located in the Windows System32 folder of the server.

This error message can appear on any page that has text edit controls (EditField) on it.

Solution

Unregister and re-register the file VBScript.dll. The following procedure assumes that Windows is installed at C:\winnt.

To unregister the file VBScript.dll

  • At the command prompt, type: regsvr32.exe c:/winnt/system32/VBScript.dll /u

To re-register the file VBScript.dll

  • At the command prompt, type: regsvr32.exe c:/winnt/system32/VBScript.dll


Business Desk: Users with "Administrator" rights cannot access Business Desk data

If you delete the Everyone user group service account in Windows, or deny privileges to that group, the administrator users are locked out of Commerce Server Business Desk.

Solution

Do not delete the Everyone user group or change the default privileges. For instructions about changing a service account or password, see Changing a Service Account or Password.


Business Desk: Runtime errors occur when you access Business Desk

When you access Commerce Server Business Desk, one of the following errors appears:

  • A Runtime Error has occurred.

  • Do you wish to Debug?

Solution

Make sure the root folder for Business Desk is configured to allow Web sharing. By default, Commerce Server allows Web sharing on these folders. Use the following procedure to allow Web sharing on a Business Desk folder.

To allow Web sharing on a Business Desk folder

  1. In Windows Explorer, navigate to the folder that contains your Business Desk application. By default this folder is located in the C:\Inetpub\wwwroot folder.

  2. Right-click the folder name (by default, the Blank Solution Site included with Commerce Server names this folder blankbizdesk), and then click Properties.

  3. In the Properties dialog box, select the Web Sharing tab.

  4. On the Web Sharing tab, click Share this folder.

  5. In the Aliases box, select blankbizdesk and then click Edit Properties.

  6. In the Edit Alias dialog box, in the Access permissions box, select the permissions for this alias according to the following:

    Read. Allow users to read files on this site. Make sure this is selected.

    Write. Allow users to write files to this site.

    Script source access. Allow users to access script source code.

    Directory browsing. Allow users to browse the contents of this folder.

  7. In the Application permissions box, select the application permissions according to the following:

    None. Prevent users from running application files in this folder.

    Scripts. Allow users to run scripts, but not applications, in this folder.

    Execute (includes scripts). Allow users to run scripts and applications in this folder.

  8. Click OK. On the Properties dialog box, review your list of sharing aliases, and then click OK again.


Business Desk: Cannot access sites when logged into Business Desk as Administrator

You successfully log on to Commerce Server Business Desk using the Administrator account created in Microsoft Windows 2000. But now you cannot access the sites. Business Desk does not allow you to access a site as Administrator because no Business Desk user profile exists for this name. However, you cannot create a user named Administrator in Business Desk, because that name already exists on the computer.

Solution

Log onto Business Desk using a user account created in Business Desk. Make sure this account has appropriate access privileges. If necessary, add Business Desk users to the Administrator group.


Summary of Report Issues

The following table summarizes the known issues with Reports.

Report | Issue
Usage Trend | Total and Grand Totals are based on the number of users for a given day. This may not correspond to the reporting period you have specified.
General Activity Statistics | The number reported for the average visits per weekday may not be accurate. It is calculated as "number of visits on a given weekday/number of weeks in the specified time period." This report does not give an accurate average in some cases. A similar issue exists for the number of visits per hour or per day.
Buyer Browse to Purchase | The percentage of registered users purchasing is based on all users, not on registered users as indicated by the report.
Customer Spend Summary and Product Sales | The unit price for both of these reports is inaccurate.


Reports: Buyer Browse to Purchase report error

If you run the Buyer Browse to Purchase report and an error message appears, it may be that Profiles System cookies are turned off. As a result, no registered user data is imported into the Data Warehouse and no registered user data is added to the BuyerVisits cube. No registered user data is available for the Buyer Browse to Purchase report.

Solution

You can resolve this in one of three ways:

  1. Enable Profiles System cookies, import user data into the Data Warehouse, and then run the Report preparation DTS task. Run the Buyer Browse to Purchase report again.

  2. Add custom static reports that report on buyer activity by registered user for anonymous registered users. Anonymous registered users have a null value for the Logon_Name in the dbo.RegisteredUser table. Run this report instead of the Buyer Browse to Purchase report.

  3. Delete the RegisteredUser shared dimension from the Basket and Web Usage cubes. You can add the RegisteredUser shared dimension back after Profiling System cookies are again enabled. Run the Buyer Browse to Purchase report again. The report will not display registered user data.


Reports: Dynamic SQL reports cannot be viewed

After data and log files have been imported into the Data Warehouse and you have run the Report preparation Data Transformation Services (DTS) task, you run a dynamic SQL Server report and the pivot control returns the following error message:

"The pivot table list "Pivot Table" could not connect to the data source "". For information about the data source, consult the creator of the file. (0x80040e4d)."

If you are viewing a dynamic report that is accessing a SQL Server database to which you have not been granted read or write permissions, then you will not be able to view the report. This issue does not affect dynamic online analytical processing (OLAP) reports.

The following reports are affected:

  • Ad Reach and Frequency per Campaign

  • Ad Reach and Frequency per Campaign Item

  • Ad Reach and Frequency per Day

  • Campaign Item Summary

  • Distinct Users and Visits by Week

  • Distinct Users by Day

  • Registered Users by Date Registered

  • User Days to Register

  • User Registration Rate

  • Visits by Browser, Version, and OS

Solution

You need to have read and write privileges on the database that is being accessed by the reports. You may want to define a user group in Microsoft Windows 2000 with read/write privileges to the SQL Server database. Then you can add users who require these privileges.

To define a user group with read/write privileges

  1. Create a new user group in Windows 2000. Add any users you want to include in this group.

  2. Click Start, point to Programs, point to Microsoft SQL Server and then click Enterprise Manager.

  3. Expand the console root node to Microsoft SQL Servers/<server name>/Security/Logins.

  4. Right click on Logins and select New Login.

  5. In the SQL Server Login Properties - New Login dialog box, on the General tab, in the Name box, type the new group login name or click Ellipsis to browse for the new group name.

  6. Select SQL Server Authentication and enter a password for the group.

  7. Click Add, and then click OK.

  8. On the Database Access tab, select the Permit box option for the database for which you are granting permissions, for example, Retail_dw.

    The new group login name appears in the User column.

  9. In the Database roles box, check the Permit boxes for db_datareader and db_datawriter, and then click OK.

You can now add yourself and any users to this group for access to dynamic SQL Server reports.


Reports contain no data

If your reports appear without data, the SiteUnfiltered shared dimension may have been deleted from one or more of the following cubes:

  • Bandwidth

  • Basket Events

  • Buyer Visits

  • OrderEvents

  • Users

  • Web Usage

  • Weekly Users Trends

Solution

If this dimension has been deleted, you must add the SiteUnfiltered shared dimension to the appropriate cubes in Analysis Manager.

To add the SiteUnfiltered shared dimension

  1. Click Start, point to Programs, point to Microsoft Commerce Server 2000, and then click Commerce Server Manager.

  2. Expand the Analysis Servers node to <Server name>/<OLAP database name>/Cubes/<name of cube>/.

  3. Right click the name of the cube, and then click Edit.

  4. In the Cube Editor dialog box, right click Dimensions, and then select Existing Dimensions.

  5. In the Dimension Manager dialog box, in the Shared dimensions box, click SiteUnFiltered, and then click the right arrow (>) button.

  6. Click OK and then click save on the toolbar.

  7. Close the Cube Editor and then rerun the Report preparation (Commerce Server) DTS task.

Note

  • You can also manually reprocess the cubes in Analysis Manager.


Troubleshooting Site Packager

This section describes problems you may encounter while using Commerce Server Site Packager, and describes possible solutions.

This section contains:

  • Site Packager Error Messages

  • "Login Failed for User" error appears when unpacking Data Warehouse

  • Cannot unpack a site to a Web server

  • "Specified path does not exist" error appears when unpacking a site

  • "Error invoking Import API…" error appears when unpacking a site

  • "Profile missing" error appears after unpacking a site

  • Databases do not appear after unpacking a site


Site Packager Error Messages

This section provides information about a few of the error messages that may appear in the Commerce Server Site Packager event log (Pup.log) file when you use Site Packager. This is not a comprehensive list.

Error finding directory for <Application> <Error Number>:<Error Description>

Site Packager encountered an error when searching for the Internet Information Services (IIS) 5.0 meta-base entries for an application, or for the physical path. This error occurs when the meta-base is pointing to a directory that does not exist, or the meta-base entry for the application has been deleted. This error occurs only during packaging.

Error finding IIS object for <Application name>:<Error Description>

Site Packager encountered an error when accessing the IIS settings for <Application name>. Either the meta-base is corrupt, or the application points to a virtual directory that does not exist. Verify that the applications in the package point to a virtual directory that actually exists.

Error importing URL for <Application name> <Error Number>:<Error Description>

Site Packager encountered an error when creating a virtual directory for the application, or when copying application files to a folder. Make sure you have administrative privileges to change IIS settings.

Error exporting object data for <Resource name> to file <Filename> <Error Number>:<Error Description>

Site Packager encountered an error when exporting the data for a resource or application. Either the data does not exist or some automation error has occurred. This error message occurs only during packaging.

Error importing object data for <Resource name> from file <Filename> <Error Number>:<Error Description>

Site Packager encountered an error when importing the data for a resource or application. Either the data was corrupt or some automation error has occurred. This error message occurs only during unpacking.

Error creating ref resource <Reference resource> for <Global resource> <Error Number>:<Error Description>

Site Packager encountered an error when creating a global resource pointer for the named global resource. After you identify the problem and fix it, run Site Packager again, using Custom mode to add the resource to an existing application.

See Also

About Site Packager


"Login Failed for User" error appears when unpacking Data Warehouse

When you are unpacking the Data Warehouse in custom mode using Commerce Server Site Packager, the following error message appears: Login Failed for User <user name>. When you click OK, the Data Warehouse Properties dialog box appears.

Solution

To continue unpacking

  • In the Data Warehouse Properties dialog box, in the Password box, delete the asterisks (**), type your password, and then click OK.

    If you do not want to set a password, leave the box blank.

Commerce Server Site Packager finishes unpacking the site.


Cannot unpack a site to a Web server

You install Commerce Server on Computer A, and the Data Warehouse on Computer B, but you cannot unpack your site on Computer A.

Solution

This problem occurs if the database server does not share a security context with the Web server. To solve the problem, run the following command on the database server:

net use \\<Web_server_name> /u:<local_computer_name>\administrator *

Enter the SQL Server password when prompted.

Another item to check is the number of SQL connections allowed on the computer. When you install Microsoft SQL Server, by default the number of SQL Server connections is set to zero (0), indicating that you can have an unlimited number of connections. If you choose to change the number of connections, allocate four connections for each computer in the Commerce Server installation.

To determine the number of SQL Server connections currently in use

To set SQL Server connections

Note

  • It is recommended that you have at least 20 connections available to unpack a site.

To determine the number of SQL Server connections currently in use

  1. Click Start, point to Programs, point to Microsoft SQL Server, and then click Query Analyzer.

  2. Type the following query in the open window:
    select * from master..sysprocesses where hostname <>''

    where '' is two single quotes.

  3. Click the Execute Query button on the toolbar.

Query Analyzer displays the number of SQL Server connections currently in use. The number of rows equals the number of SQL Server connections.

To set SQL Server connections

  1. Click Start, point to Programs, point to Microsoft SQL Server, and then click Enterprise Manager.

  2. Right-click the SQL Server to which you are adding connections, click Properties, and then click the Connections tab.

  3. On the Connections tab, in the Maximum concurrent user connections (0 = unlimited) box, type the number of connections you need, and then click OK.


"Specified path does not exist" error appears when unpacking a site

When you attempt to unpack a site, you get the following error:

"The specified path does not exist. Check the path, and then try again."

This error can occur when you try to unpack a site into a folder that contains special characters. For example, Commerce Server Site Packager will not unpack to a folder named 'my commerce $$%'.

Although you can install Commerce Server into a folder that contains special characters, you cannot unpack a site to such a folder.

Solution

Copy the package to a different directory, and then unpack it.


"Error invoking Import API…" error appears when unpacking a site

When you are unpacking a site, you receive the following error:

"Error invoking Import API on Commerce.CatalogPUP for Product Catalog 80040E14:Source:Microsoft OLE DB Provider for SQL ServerDescription:The Full-Text Service (Microsoft Search) is not available. The system administrator must start this service."

This error occurs if the Microsoft Search service is not running when Commerce Server Site Packager runs the script to create catalogs.

Solution

Start the Microsoft Search service. Then either delete the site and unpack it again, or just delete and unpack the Catalog resource.

To start the Microsoft Search service

  1. Click Start, point to Programs, point to Administrative Tools, and then click Services.

  2. In the Services dialog box, select Microsoft Search.

  3. Right-click Microsoft Search, and then click Start.


"Profile missing" error appears after unpacking a site

This error applies to the Supplier Solution Site. It occurs when the Profiles service cannot locate a user in Microsoft Active Directory.

"The user name might not be included in the following Active Directory containers: OU=MSCS_40_Root and OU=site_name."

Solution

The recommended solution depends on when the error message appears.

Log on to the Supplier site by using a name that was created using Microsoft Commerce Server 2000 run-time components.

If you receive this error just after unpacking the site

In this case, the error occurs because the site uses the Windows Integrated Authentication method by default, and the user attempts to use a login name not created using Commerce Server Business Desk or the Profiles resource.

Use Business Desk to create a user account, and then log onto the server as the newly created user. You should then be able to access the Supplier site.

Another possible solution is to enable Basic Authentication (in Internet Information Services (IIS) 5.0) with the Supplier site. Log on to the site. Make sure you use one of the following formats when typing the user name:

  • domain_name\user_name

  • username@fully_qualified_domain_name

If you receive this error (or a similar error) while using AuthFilter with the Windows Authentication mode

Determine whether the GetProfileByKey method on the Login page is functioning properly. If this method is producing an unauthorized authentication mode error message, then an anonymous user does not have permission to get or read the user profile. For more information, see GetProfileByKey.

In this case, make sure the user has a Windows user account that has permissions to get and read the user profile properties from Active Directory.

Another solution is to make sure that you can access the site without the AuthFilter ISAPI filter.

To access the site without AuthFilter

  1. Use Internet Services Manager to remove the filter.

  2. Set the security mode to Basic Authentication only on the Supplier site. Then reset IIS.

  3. Try accessing the site with the correct credentials.

If this does not work, make sure you created the user account with Business Desk, and make sure that is enabled.

See Also

Working with Site Security and Filters


Databases do not appear after unpacking a site

When you unpack a site on Computer A, and you create the databases for resources on Computer B, after you have finished unpacking the site, the new databases do not appear on Computer B.

Solution

Wait several minutes. Site Packager runs on Computer A, so if network congestion exists, there could be a delay before the resources are created. Also, you can run Commerce Server Site Packager again to make sure you have created the databases on Computer B, and not on Computer A.


Troubleshooting Commerce Server Resources

This section describes issues you may encounter while using Commerce Server resources, and describes possible solutions.

This section contains:

  • DTS Tasks: Report preparation task fails

  • DTS Tasks: Terminal Services and Report preparation task are not compatible

  • DTS Tasks: User profile data import task does not support multi-valued dates

  • Predictor: Analysis models do not build

  • Predictor: Building analysis models takes too long

  • Predictor: Loading an analysis model from the Data Warehouse takes too long

  • Predictor: Creating more than one analysis model for an application

  • Predictor: Prediction time takes too long

  • Predictor: Returns same prediction recommendations regardless of the input

  • Predictor: Analysis models does not build when using DBCS characters in the model name

  • Profiles Resource: Login failed for user

  • Direct Mailer: Jobs fail with no error message

  • Direct Mailer: Discovering details of job failures


DTS Tasks: Report preparation task fails

If you install the Data Warehouse on a computer running software that performs a real-time scan of your system (for example, virus protection software), you may not be able to run the Report preparation Data Transformation Services (DTS) task successfully.

Solution

To resolve this issue, use the Windows 2000 Task Manager to end the process in which the scanning software is running.


DTS Tasks: Terminal Services and Report preparation task are not compatible

You must run the Report Preparation Data Transformation Services (DTS) task directly on the server. Do not run the Prepare Reports DTS task from a package executed from Terminal Services; doing so creates an error in DTS.

This problem also extends to unpacking a site. When you unpack the Data Warehouse, the OLAP database may not be created properly.


DTS Tasks: User profile data import task does not support multi-valued dates

If you have defined multi-valued properties in your user profile that map to data sources with date or date/time data types, they will not be exported to the Data Warehouse by the Commerce Server 2000 User profile data import task. Commerce Server 2000 does not support multi-value date or date/time members.


Predictor: Analysis models do not build

You attempt to build a Prediction or Segment model and the build fails.

Solution

The request to build the model occurred either before the Report preparation Data Transformation Services (DTS) task was complete, or after the Report preparation DTS task failed.

Run the Report preparation DTS task again. Wait until it completes successfully, and then build the Prediction and Segment models.


Predictor: Building analysis models takes too long

The time required to build an analysis model depends on the size of the input data (the total number of cases), the sample size, the number of attributes in the data, various factors regarding the statistics of the input data, and also the hardware and network characteristics and topology.

Solution

The following are ways to improve build performance:

  • Choose a smaller sample size. Larger samples result in greater accuracy — but only up to a point. For example, if you have a total of 1,000,000 input cases, you might start by building an analysis model with 5,000 cases, then 10,000, and so on, until you find that the accuracy of the model is no longer increasing significantly.

  • If your catalog contains a very large number of products (greater than 1,000) and you are building a Prediction model, it is advisable to set the values for the Input attribute fraction and the Output attribute fraction to values less than 1.0 in the Build Model dialog box.

See Also

Building a New Analysis Model


Predictor: Loading an analysis model from the Data Warehouse takes too long

If you are trying to load a large analysis model from the Data Warehouse, it may take a long time to load. If you load the analysis model from a file, the load time required may decrease.

Solution

Instead of using the LoadModelFromDB method each time, you can cache the model as a file on the Web Server using the IPredictorClient::SaveModelToFile method, and then load it using the LoadModelFromFile method. Loading from a file will be faster and will work even if the Data Warehouse is not available.

See Also

IPredictorClient::SaveModelToFile (Visual C++)

PredictorClient.SaveModelToFile (Visual Basic)


Predictor: Creating more than one analysis model for an application

If you need more than one analysis model for a particular application, avoid resetting properties on the IPredictorClient interface on a per-page basis because the only state the PredictorClient object keeps is in the properties that are set on the object and the analysis model currently loaded.

Solution

To create more than one analysis model for an application, use separate instances of the PredictorClient object instead of loading a model on every page. Create the PredictorClient object in the Application context using Microsoft Internet Information Services (IIS) 5.0 in Application_OnStart, and then reuse the object on individual Active Server Pages (ASP) pages.

See Also

PredictorClient Object (Visual C++)

PredictorClient Object (Visual Basic)


Predictor: Prediction time takes too long

A Prediction model takes too long to open in the Prediction Model Viewer, or a Segment model takes too long to open in the Segment Viewer.

Solution

If the prediction time required is unacceptable, the following information may be helpful:

  • Use the lMaxPredictions interface in IPredictorClient::Predict to limit the number of predictions rather than asking for all predictions and post-processing the output. Prediction time is faster when fewer predictions are requested.

  • If you are using a Segment model for prediction, you can limit the number of segments used in building Segment models. Segment models build faster when fewer segments are requested at build time.

Note

  • It is recommended that you do not use Segment models for real-time recommendations because they are not optimized for this purpose and do not produce recommendations as accurate as those produced by Prediction models. Always build and use Prediction models for real-time recommendations on your site.

See Also

IPredictorClient::Predict (Visual C++)

PredictorClient.Predict (Visual Basic)

Building a New Analysis Model


Predictor: Returns same prediction recommendations regardless of the input

If you are getting the same recommendations regardless of input, it is possible that the Predictor resource does not recognize the names of the input attributes. By default, the PredictorClient object ignores input attributes that it does not recognize.

Solution

Setting bFailOnUnknownInputAttributes to True will cause the PredictorClient object to generate an error at prediction time if it cannot recognize the input. For Prediction models, use the Prediction Model Viewer to view the trees to see what it is capable of predicting and what input attributes are being used to predict given output attributes. You may find that the attribute that you are trying to predict does not depend on the input attribute strongly enough to be included in the model. For information about using the Prediction Model Viewer, see Prediction Model Viewer.

See Also

PredictorClient Object (Visual C++)

PredictorClient Object (Visual Basic)


Predictor: Analysis model does not build when using DBCS characters in the model name

You receive the error message, "Unable to load model" when you build an analysis model using double-byte character set (DBCS) characters in the model name.

Solution

If you use DBCS characters in the model name for either Prediction or Segment models, ensure that the SQL Server storing the data is installed with a compatible character set.


Profiles Resource: Login failed for user

You receive the following error message:

"Microsoft OLE DB Provider for SQL Server: Login failed for user <user name>"

If you do back up the SQL Server database tables associated with the Profiles resource, and then restore them on a different database on the same SQL Server installation or on a different SQL Server installation, Profiles Resource may not initialize because the connection string(s) to the database tables may not be valid after restoring them to the new SQL Server. The connection string(s) may not be valid because either the logon credentials are not valid, or the database is not present on the SQL Server installation, or both.

Note

  • It is not recommended that you back up and restore your databases directly. Instead, you should use Commerce Server Site Packager to back up and restore your databases.

Solution

The Profiling System depends on the s_CommerceProviderConnectionString connection string. This connection string is used by the OLE DB Provider for Commerce Server, and is stored within the Commerce Server Administration database. If you restore the Administration database from a database backup, this connection string is often incorrect and must be reset.

To reset the s_CommerceProviderConnectionString connection string

  1. Expand Commerce Server Manager, expand Global Resources, right-click Profiles, and then click Properties.

  2. In the Profiles Properties dialog box, in the Connection Strings tab, select s_CommerceProvideConnectionString, and then click Modify.

  3. In the Data Link Properties dialog box, make the necessary changes, and then click OK.

    Note

    • For information about how to complete the Data Link Properties dialog box, click Help in the Data Link Properties dialog box to open the Microsoft Data Link Help file.


Direct Mailer: Jobs fail with no error message

If SQL Server Agent is stopped when a scheduled Direct Mailer job is to run, the job will not run. You do not receive any indication that the job had failed to start, and no error condition is logged.

Solution

To start a job that did not run, you must start the job manually from the SQL Server Agent control in SQL Enterprise Manager.

To start a direct mail job manually

  1. Click Start, point to Programs, point to Microsoft SQL Server or Microsoft SQL Server 7.0 (depending on your installed database), and then click Enterprise Manager.

  2. Expand the nodes to the following path: \Microsoft SQL Servers\SQL Server Group\<SQL Server Name>\Management\SQL Server Agent\Jobs.

  3. Click on Jobs. The Direct Mailer jobs appear in the right pane of the SQL Server Enterprise Manager.


Direct Mailer: Discovering details of job failures

When a Direct Mailer job completes, Direct Mailer logs an event to the application event log. This event contains the job number, the start time of the job, the completion time of the job, the number of total recipients in the mailing, and the number of errors that occurred.

To find more information about the failures, you need to look in the dml_job_errors table in the Direct Mailer database.

Solution

Open Event Viewer and locate the application event log message logged by Direct Mailer.

To open Event Viewer

  1. Click Start, point to Programs, point to Microsoft Commerce Server and then click Commerce Server Manager.

  2. Expand the Event Viewer node and double-click Application.

  3. In the events list, find the event where the Source is Commerce Server Direct Mailer, and the Event ID is 18.

  4. Double-click the event message to open the Event Properties dialog box.

  5. In the Event Properties dialog box, copy the job number onto Microsoft Clipboard, and then open SQL Server Query Analyzer.

To open SQL Server Query Analyzer

  1. Click Start, point to Programs, point to Microsoft SQL Server and then click Query Analyzer.

  2. In the Connect to SQL Server dialog box, connect to the Direct Mailer database your server is configured to run against.

  3. Type the following query in Query Analyzer window:
    "SELECT * FROM dml_job_errors WHERE job_id = '<job id>'

    where <job id> is the job number you copied from step 5 in the To open Event Viewer procedure.

The returned result set indicates the error code and description for each failure that occurred while the Direct Mailer job was processed.


For Additional Troubleshooting Information

For additional troubleshooting information, see the following resources:

Resource | Location
Debugging topics in Commerce Server 2000 Help
  • Debugging Tools

  • Debugging Business Desk

  • Content Seletion Framework Concepts
Commerce Server 2000 Readme | Commerce Server 2000 Installation CD
Microsoft Commerce Server Web site | www.microsoft.com/commerceserver
Commerce Server Solution Sites Contains technical information and download versions of the Commerce Server Solutions Sites.

www.microsoft.com/commerceserver/solutionsites
TechNet Contains technical information and tools designed to help you plan, develop, deploy, and manage your e-commerce Web sites.

For information about Commerce Server, select Commerce Server from the Navigate by Product menu on the left side of the screen.

www.microsoft.com/technet/
Commerce Server 2000 Software Development Kit (SDK) | Contains technical information for developers creating programs or intelligent Web pages that must integrate with the Commerce Server application programming interface (API). The SDK contains a guide for programmers and references to various Commerce Server and commerce technologies. It also includes samples and header files that you can use to create your own programs. Included with Commerce Server 2000.
Commerce Server 2000 Resource Kit | The Commerce Server 2000 Resource Kit contains technical information and tools designed to help you plan, develop, deploy, and manage your e-commerce Web site. It is available from Microsoft Press.
MSDN information | Contains information about Commerce Server 2000 and other Microsoft .NET Enterprise Servers. You may find it helpful to visit this site on a regular basis. Search MSDN, and enter Commerce Server 2000 to find related documents and white papers. www.msdn.microsoft.com
Microsoft Servers site A guide to the full range of Microsoft server products for IT professionals, developers, and Internet professionals.

www.microsoft.com/servers/
Newsgroups Use peer-to-peer newsgroups to talk about Commerce Server with other administrators, developers, and Microsoft Most Valuable Professionals (MVPs). Microsoft does not monitor or support the content of these newsgroups or sites.

www.microsoft.com/commerceserver/support/NewsGrps.htm
Premier Support Premier Support for Developers is a program offered by Microsoft to help you analyze your site and also help you with other development issues.

Introducing Commerce Server 2000.


Glossary

A

action page

A single ASP file that provides a particular aspect of the functionality associated with a module in Commerce Server Business Desk. For example, defining the properties of a particular product. Action pages are typically displayed as a result of clicking a module name in the navigation pane, or as a result of clicking a task button presented by a different action page in the same module.

See also: status bar

Active Directory

The directory service for Windows NT 4.0 and Windows 2000 Server. Active Directory stores information about objects on the network and makes this information available for authorized system administrators and users. It gives network users access to permitted resources anywhere on the network using a single logon process. It also provides system administrators with an intuitive hierarchical view of the network and a single point of administration for all network objects.

Active Directory Service Interfaces (ADSI)

A Component Object Model-based (COM-based) directory service model that allows ADSI-compliant client applications to access a wide variety of distinct directory protocols, including Windows Directory Services, Lightweight Directory Access Protocol (LDAP), and Novell Directory Services (NDS), while using a single, standard set of interfaces. ADSI shields the client application from the implementation and operational details of the underlying data store or protocol.

Active Server Pages (ASP)

A server-side scripting environment used to create dynamic Web pages or to build Web applications. ASP pages are files that contain HTML tags, text, and script commands. ASP pages can call Component Object Model (COM) components to perform tasks, such as connecting to a database or performing a business calculation. With ASP, you can add interactive content to Web pages or build entire Web applications that use HTML pages as the interface to your customers.

Active Template Library (ATL)

A library of C++ templates that facilitate the development of small, efficient COM components. ATL was developed by Microsoft and is included as part of Visual C++.

Active User Object (AUO)

A framework that provides a single, unified access mechanism for all user profile information, removing the need for script authors to worry about specifying user identification and profile storage location. A system administrator can configure a computer to define a virtual namespace of profile information, specifying the configuration information needed to access profile data from a variety of sources.

AUO is technically a container of ADSI objects. A system administrator defines the number of objects that the AUO will contain and provides the information for managing these objects. This allows an extensible model for adding new storage providers or alternate profile sources. By writing or reusing ADSI providers, you can access profile information that exists in any store.

ActiveX Data Objects (ADO)

A high-level, language-independent set of object-based data access interfaces optimized for data application. ADO enables client applications to access and manipulate data from a database server through an OLE DB provider.

See also: ActiveX Data Objects (Multidimensional) (ADO MD)

ActiveX Data Objects (Multidimensional) (ADO MD)

A high-level, language-independent set of object-based data access interfaces optimized for multidimensional data application. Visual Basic and other automation languages use ADO MD as the data access interface to multidimensional data storage. ADO MD is a part of ADO version 2.0 and later.

See also: ActiveX Data Objects (ADO)

ad

A piece of content to be delivered by Commerce Server based on a specific formula for delivery referred to as Need of Delivery (NOD).

ad click

The act of a user clicking on an advertisement or other linked element on a Web page, recorded by the server, that results in the display of a new page or piece of content.

See also: ad click rate

ad click rate

The percentage of ad requests that resulted in an ad click.

See also: ad click, ad request

ad ID

The computer-generated identification number for an ad that is added to Commerce Server using the Campaign Manager module.

ad request

An opportunity to deliver an advertising element to a Web site visitor. Requests are generated by events on the site, such as a request for a particular page or the purchase of a specific item. The ad used to fulfill the request is determined by the Need of Delivery (NOD). When you create a campaign or campaign item using the Campaign Manager module, you can enter how many ad requests or clicks are to be recorded by Commerce Server for that campaign or campaign item.

See also: ad click rate, campaign goaling, Need of Delivery (NOD)

ad target

The result of a set of expressions that describes a situation or users to which an ad is aimed.

Administration database

The SQL Server database that stores the configuration data for the resources for all computers being run as part of the same (logical) installation of Commerce Server. This database is created by Commerce Server Setup.

administrator

See system administrator.

ADO

See ActiveX Data Objects.

ADO MD

See ActiveX Data Objects (Multidimensional).

ADSI

See Active Directory Service Interfaces.

advertising campaign goaling

See campaign goaling.

aggregated catalog

A catalog that you assemble from several different sources, such as different suppliers. You can import data from an accounting system or other documents, or you can enter it using the Catalog Editor module.

aggregation

A table or structure containing pre-calculated data for an online analytical processing (OLAP) cube. Aggregations support the rapid and efficient querying of a multidimensional database.

Alt text

The text string that appears in place of an image when a Web page is loading, when graphics are not being displayed, or when users pause on the image itself with their mouse. Users who either do not have a graphical browser or who have chosen not to download graphics can use the Alt text string to identify the graphic that is not displayed.

alternate currency

The currency unit used on a site to convert and format a second currency for dual display. This property is typically used on European sites that use the EuroDisplay object to display prices in both the base currency and Euro formats.

See also: base currency

ancestor category

A category that is closer to the root category through one or more parent-child relationships. A parent category is an ancestor category, as is the parent of the parent, and so forth.

See also: child category, root category, descendant category, parent category

anonymous access

See anonymous authentication.

anonymous authentication

One of the authentication methods that you can set at the Web Site or Application levels in IIS. Anonymous authentication is used to establish an anonymous Web (HTTP) connection without providing a user name or password. It is commonly used in the public areas of an Internet site. If you enable anonymous authentication for a site, an anonymous connection will be made even if authenticated access has also been enabled, unless more restrictive NTFS permissions exist on the individual file being requested. Also called anonymous access.

anonymous user

A user who accesses content on a Web site without providing a user login name and password. Sometimes called a guest user.

apartment-threaded components

COM components that reside on a single thread of execution. Apartment-threaded components rely on COM to synchronize calls to them. All COM objects created with Visual Basic are apartment threaded.

App Default Config resource

A Commerce Server resource with site-level properties, managed through Commerce Server Manager. Use App Default Config to set properties that determine site functionality in areas such as currency options, billing options, and BizTalk Server integration.

application

From a Commerce Server 2000 administration standpoint, an application is an ASP application accessible through a single Uniform Resource Locator (URL). An application appears in both the Commerce Server and IIS console trees. The application that appears in the Commerce Server Manager console tree is a logical representation of the application in IIS.

Application Center 2000

A Microsoft deployment and management tool for high-availability Web applications built on Windows 2000.

arc

A graphical representation of a statistical relationship, as displayed in a dependency network. An arc from node A to node B, for example, means that attribute A helps to predict attribute B, but it does not mean that attribute B helps to predict attribute A.

See also: dependency network

ASP

See Active Server Pages.

ATL

See Active Template Library.

ATL Pipeline Component Wizard

A Visual C++ wizard that uses ATL and additional templates to facilitate the development of pipeline components.

attribute

A characteristic that describes a property, object, or person. Attributes can include information such as the data type of the property (for example, number, text, or decimal), whether the property is exported to the Commerce Server Data Warehouse, whether the property is shown to users, or whether the property is full-text indexed. It can refer to a set of values such as hair color or age. Depending on the property or object being described, an attribute could also be called a variable, column, or dimension.

See also: node

auditing

Tracking the activities of users by recording selected types of events in the security log of a server or workstation.

AUO

See Active User Object.

authenticated access

A user access option that you can set at the Default Web Site or Application levels in IIS. As opposed to anonymous access, authenticated access requires a user to have a valid account and password to access the site. The three types of authenticated access are Basic authentication, Digest authentication, and Integrated Windows authentication.

Authentication Service

See CS Authentication resource.

authentication ticket

A ticket Commerce Server creates for registered users. Also called an MSCSAuth ticket.

See also: ticket, profile ticket

authorization

A process that verifies that a user has the correct permissions to access a resource such as a Web page or database, or has the correct privileges to perform a task such as performing backups. Authorization is typically set up by a system administrator, or site developer, and checked and cleared by the computer. The user provides some type of identification, such as a code number or a password, which the computer verifies against its internal records.

availability

A measure of fault tolerance for a computer, server cluster, or system and its programs. A highly available computer or system is one that is up and operating at an acceptable service level at least 99.9 percent of the time.

B

base catalog

A source catalog from which a custom catalog is derived.

base currency

The currency unit used on your site to perform calculations.

See also: alternate currency

basket

The list of items a user selects to purchase from a commerce Web site. The list is usually compiled into a file.

See also: Basket Manager module

Basket Manager module

The Commerce Server Business Desk module used to manage the shopping baskets of users who visit your Web site. Users can save a shopping basket so that they can return to the site and purchase the items at a later date. Use Basket Manager to find and delete abandoned baskets (saved baskets that have been left inactive for a lengthy period).

See also: basket

BizTalk Server 2000

A Microsoft product that provides the tools and infrastructure companies need to exchange business documents among various platforms and operating systems regardless of the application being used to process a business document.

Business Desk

See Commerce Server Business Desk.

Business Desk framework

The set of HTML components (HTCs), utility routines, include files, configuration files, navigation mechanisms, and conventions that allow easier and more standardized implementation of Business Desk modules.

business manager

The primary user of Commerce Server Business Desk. The business manager typically has knowledge of business goals, strategies, and processes for creating and running a successful e-commerce Web site.

business-to-business site

A commerce Web site designed for the creation and transmission of purchase orders between businesses that have an established relationship. Also known as a supplier site or a B2B site.

business-to-consumer site

A commerce Web site designed for retail shopping by the public. Also known as a retail site or a B2C site.

Buy Now

A content template used in Commerce Server to facilitate impulse shopping: a user can purchase goods from any Web page on the Internet. When a user clicks a product image, a dialog box appears prompting the user for shipping address and credit card information.

C

cache

A memory subsystem in which frequently used data values are duplicated for quick access. A cache stores the contents of frequently accessed RAM locations and the addresses where these data items are stored. When the processor references an address in memory, the cache checks to see whether it holds that address. If it does, the data is returned to the processor; if it does not, a regular memory access occurs.

A cache is useful when RAM accesses are slow compared with the microprocessor speed, because cached memory is faster than main RAM memory. Using Commerce Server Business Desk, you can empty the caches that store profile data, catalog data, transactions data, and campaign data for your site. The next time Commerce Server receives a request for this data, the updated data is loaded in the caches.

See also: Publish Campaigns module, Publish Profiles module, Publish Transactions module

Cache Loader

A component used by the CacheManager object to load data into a cache Dictionary object. Although this component is implemented as a pipeline component, it is not run in the context of a pipeline.

Cache Writer

A component used by the CacheManager object to write activity data from a cache Dictionary object. Although this component is implemented as a pipeline component, it is not run in the context of a pipeline.

caching

Storing frequently used documents, images, Common Gateway Interface (CGI) or ASP scripts, or Internet Server API (ISAPI) extension dynamic-link libraries (DLLs) in memory to improve performance. For more information, see "Caching Applications" in the IIS Help. Also called file caching or document caching.

campaign

A marketing program that uses many communication vehicles (for example, ads and direct mail) to accomplish a specific result, such as increasing marketing share, introducing new products, or retaining customers.

Campaign Expressions module

The Commerce Server Business Desk module used to create and manage expressions.

See also: personalization

campaign goaling

Determining the number of ads to deliver in a specified amount of time. You can goal by any event, such as clicks or amount sold. Commerce Server supports goaling for ads, but not for discounts. Using Commerce Server Business Desk, you can goal campaigns at the campaign level or the ad level.

For example, you perform goaling at the campaign level and your customer orders 25,000 ad requests. At the campaign item level, one ad is set up to display 60 percent of the ad requests, and the other ad is set up to display 40 percent of the ad requests. If the customer changes the number of ad requests, for example, to 40,000, you do not have to manually change the number of times the ads appear; they will still appear 60 percent and 40 percent. If you goal at the campaign item level, you set the ad request goals for each individual ad.

See also: ad request

campaign item

A communication vehicle that contributes to the specified result of a campaign. You can create three types of campaign items in Commerce Server: ads, direct mail, or discounts. You can use third-party products to create additional types of campaign items.

campaign item ID

The computer-generated identification number for a campaign item.

Campaign Manager module

The Commerce Server Business Desk module used to create customer accounts, and then create and manage advertising campaigns, discount campaigns, and direct mail campaigns.

Campaigns resource

A Commerce resource with site-level properties, managed through Commerce Server Manager. Use it to configure the connection string to the database containing campaign data.

capacity planning

Planning for application, hardware, and network requirements to support expected site traffic and to achieve site performance goals.

case

The set of all the information known about a specific user, such as user profile data and transaction history. Individual cases are constructed from data in the Commerce Server Data Warehouse. The cases are the input from which Commerce Server builds a Prediction model.

case extractor

A component that reads data from the Commerce Server Data Warehouse and produces cases for model building.

case identifier

An ID that is unique for each user.

catalog

A collection of categories and products.

catalog data

The content of a catalog, including data about the individual product items and their organized categories.

Catalog Designer module

The Commerce Server Business Desk module used to create and manage catalog schema. Catalog schema consists of category definitions, product definitions, and property definitions. These components are the foundation of the categories, products, and properties in catalogs.

Catalog Editor module

The Commerce Server Business Desk module used to edit and manage catalogs. The Catalog Editor module supports adding, editing, and deleting products and categories, as well as, importing and exporting catalogs and refreshing full-text indexing.

catalog expression

An expression that specifies which products in a catalog a discount may be applied to.

catalog properties

The basic properties that describe a catalog, such as name, start date, end date, currency, unit of weight measure, and product unique ID. Use the Catalog Editor module to manage catalog properties.

catalog schema

A description of a catalog that specifies its category definitions, product definitions, and property definitions. Several catalogs can share one schema. Use the Catalog Designer module to manage catalog schema.

catalog set

A group of one or more catalogs that you make available to different users or organizations. For example, you may create two custom catalogs that you display to members of a specific organization, and then create two other catalogs that you make available to a different organization. This gives you four catalogs that have been grouped into two catalog sets.

Catalog Sets module

The Commerce Server Business Desk module used to create and manage catalog sets.

category

A container for products or sub-categories. Each category is an individual instance of a category definition. For example, a category based on the Department category definition (which has the properties Description and Manager) may be named Hardware, and have the properties Power Tools (Description) and Frank Lee (Manager). Use the Catalog Editor module to manage categories.

category (Commerce Server Business Desk)

An organizational construct used within the navigation pane that allows the grouping of related Commerce Server Business Desk modules.

category definition

The properties that are available in a particular type of category. One category definition may be used for many categories. For example, the Department category definition could contain Description and Manager properties. Use the Catalog Designer module to manage category definitions.

category hierarchy

A hierarchy within a category where one category is specified as a parent and one (or more) category is a child. A category cannot be both a parent and a child (descendent) of the same category.

category properties

The properties that form a category definition. For example, the Department category definition may have the following properties: Description and Manager. Use the Catalog Designer module to manage category properties.

category relationship

A way of associating one product with another product or category. Category relationships have names, a description, and a target. A category can be related to another category (for example, a relationship from the Jeans category to the Belts category). A category can also be related to an individual product (for example, to a featured item within the category). A category can have multiple relationships with other categories and/or products.

channel

A named set of properties that identifies the source of documents and defines specific processing steps that BizTalk Server performs before a document is delivered to the destination designated by the messaging port with which the channel is associated.

checkout

The process of finalizing a purchase on a Web site. For example, when customers shop on your Web site, they may select several items and save them in their shopping basket. When they have finished shopping, they click on a checkout link or graphical button that takes them to an online form where they enter their name, billing address, payment type, and shipping information.

child category

An entity used in catalogs to group a set of products together in a hierarchy. A child category is a subordinate of a parent category. For example, Music is a parent category, and Rock, Country, and Classical are child categories. You create parent and child categories to organize the products displayed on your site.

See also: root category, ancestor category, descendant category, parent category

class

A logical collection of related data members. Classes typically model physical objects (user, product) or conceptual entities (visit, Web hit). An instance of a class represents user data imported into the Commerce Server Data Warehouse. A class maps to a table definition in the underlying relational database.

See also: data member

class key

The subset of data members of a class whose values uniquely identify an instance of the class.

See also: key

class key member

One of the members of a multi-valued class key.

class member relation

An association between specific data members of the two classes in a class relation.

class meta-data

A conceptual model that describes the attributes that must be specified to create a class in the Commerce Server Data Warehouse logical schema.

class relation

A connection between two classes in a parent-child relationship. The relation defines the number of instances of each class. In the Commerce Server Data Warehouse, nearly all class relations are many-to-one. This means that a parent may not have any children, or may have one or more children.

click frequency

The number of clicks divided by the reach of clicks.

See also: reach

click URL

The URL that users see when they click a piece of content on your Web site or in a direct mail message.

client

The program or user that makes a request in a client/server relationship. For example, someone who uses Commerce Server Business Desk makes client requests for information from the Business Desk server.

cluster

In the Commerce Server Predictor feature, a group of users who share certain profile characteristics. Clusters are identified by the Predictor resource, and can be viewed using the Segment Viewer module.

See also: Web farm

code value

An abbreviation used to represent textual information for properties such as country, state, and order status. For example, WA is the code value for Washington.

COM

See Component Object Model.

comma-delimited file

See comma-separated value file.

comma-separated value file (.csv)

A text file that uses the comma character to separate, or delimit, columns or database fields. Most databases and other programs can export and import a CSV file, so that database files can be created in one program and used by another program.

Commerce application

See application.

Commerce Server Business Desk

A Web-based site management tool available in Commerce Server 2000 that hosts business management modules you use to manage and analyze your commerce sites. For example, you can update pricing information in your catalog, target new ads to specific users, and then run reports to measure how these changes affect site productivity. Commerce Server Business Desk is accessible from any computer running Microsoft Internet Explorer 5.5 and because it is Web based, it can be accessed either locally or remotely.

By default, every Commerce Server Web site has a distinct instance of Business Desk associated with it. The framework is implemented primarily as Dynamic Hypertext Markup Language (DHTML). It is designed so that site developers can modify or extend the management functionality provided with Business Desk.

Commerce Server Business Desk Framework

A set of services provided for use by Business Desk modules. These services include navigation, security, and user interface controls. In addition, the Framework provides a set of standardized mechanisms that define how to integrate Commerce Server Business Desk modules.

Commerce Server Direct Mailer

A global resource that is also a Windows 2000 service. Direct Mailer runs direct mail campaigns. It processes lists of recipients, constructs personalized message bodies from either Web pages or static files, and sends the mail message to the recipients. Use Commerce Server Manager to configure and manage Direct Mailer, and to specify the database connection string to the Direct Mailer database. Commerce Server Setup installs Direct Mailer and the Direct Mailer database as part of the Web Server or Complete installation, or when you select Direct Mailer during a Custom installation.

See also: personalization, Direct Mailer database

Commerce Server Manager

A system administration tool that you use to manage and configure Commerce Server resources, sites, applications, and Web servers. Commerce Server Setup installs it automatically when you perform a Web Server or Complete installation, or when you select the Administration Tools feature during a Custom installation. The Microsoft Management Console (MMC) hosts Commerce Server Manager.

Commerce Server Site Packager

A deployment tool that you use to package your site, applications, and resources into a single file (that has a .pup extension), and then move that file to another computer. Using Site Packager, you can deploy your site across multiple computers in a distributed environment. Commerce Server Setup installs it automatically when you perform a Web Server or Complete installation, or when you select the Runtime Objects feature during a Custom installation.

Completed Reports module

The Commerce Server Business Desk module used to view both the status of static reports that have been executed and to view the reports once they have been completed.

Component Object Model (COM)

The object-oriented programming model that defines how objects interact within a single application or between applications. In COM, client software accesses an object through a pointer to an interface, which is a related set of properties and methods.

Component Object Model (COM) component

A binary file containing code for one or more class factories, COM classes, registry-entry mechanisms, loading code, and so on.

confidence interval

A number indicating the probability that a predicted value will fall between a set of given bounds.

connection string

A series of semicolon-delimited arguments that define the location of a database and how to connect to it.

console tree

The left pane in an MMC interface that displays the items contained in the console. By default it is the left pane of a console window, but it can be hidden. The items in the console tree and their hierarchical organization determine the capabilities of the console.

content pane

In Commerce Server Business Desk, the window in which action pages are rendered.

content replication

A method of copying Web site content from one server node to another. You can copy files manually, or use replication software to copy content automatically. Replication is a necessary function of clustering to ensure fault tolerance.

Content Selection Framework (CSF)

A development framework for the targeted delivery of content. The Content Selection Framework (CSF) provides the components you use to build a business-specific messaging system. CSF provides a platform for making high-speed decisions to target content to users.

content selection score

A numerical value that is the basis for selecting targeted content, such as ads or discounts, within the Content Selection Framework (CSF). An initial score is assigned to each item in the Initial Scoring stage, which defaults to one (1)if no value is set, and that score is adjusted based on how completely the item matches the targeting criteria. The SelectWinners component selects the items with the highest adjusted score to show to the Web site user. Items with a score of zero (0) are not selected.

content size

Height and width values (by pixel) for your content. You can define new content sizes using the Reference Tables module. When you create or change a content size, the update appears in the content sizes drop-down list, available in the Campaign Manager module.

cookie

Information about a user, such as an identification number, a password, click history, or number of times the user visited a site, stored in a file. A cookie can also store ticket data. Commerce Server supports both persistent and non-persistent cookies. Persistent cookies are stored on the computers of the users. Non-persistent cookies are used to track the activity of authenticated users who visit your site. When the session ends, the non-persistent cookie is deleted.

See also: ticket

country code

A three-character data code used in Commerce Server Business Desk to identify the country or region to which you ship products or with whom you do business. Country codes must be set up in order to use the Tax Rates module of Business Desk.

creative

The content that is to be placed on an advertising schedule. In the advertising industry, creative denotes ownership of the content. You cannot change any aspect of the ad without approval from the company that owns the ad you are running.

cross sell

A specific type of related sell that suggests to users a product related to the product(s) they already have in their baskets. Use the Commerce Server 2000 Software Development Kit (SDK) to add cross-sell functionality to your site.

See also: related sell

CS Authentication resource

A Commerce Server resource with global-level properties, managed through Commerce Server Manager. Use CS Authentication to configure authentication options for a site.

CSF

See Content Selection Framework.

csv

See comma-separated value file.

cube

A structure that contains a subset of the data in the Commerce Server Data Warehouse, defined by shared dimensions and measures. A cube in Commerce Server is created during the unpacking process, and is populated and processed for data retrieval when the Reports preparation DTS task is run. Storing data in cubes increases the speed of data retrieval.

See also: online analytical processing (OLAP)

Currency Locale Identifier (LCID)

Identifies the locale for currency handling. The default value is zero, which uses the default locale ID of the server.

custom catalog

A catalog that contains the same categories and products as a base catalog, but also contains custom pricing rules for the products.

custom price

The specific pricing rules that apply to products in a custom catalog. There are three types of custom prices: percentage off, fixed amount off, and explicit price.

customer

The company or individual for whom you run campaigns. A customer can be an agency, advertiser, or your own business.

D

data code

A code value used to represent textual information for properties such as country, state, and order status. For example, WA is the data code for Washington.

Data Codes module

The Commerce Server Business Desk module used to add and maintain order status codes, state codes, and country codes. Country codes and state codes must be set up before updating your tax tables using the Tax Rates module.

data constraints

The restrictions to the values allowed for a property. Data constraints are specific to the data type. For example, for a number, the constraints may be the minimum value and the maximum value.

data fit score

A value that measures the quality of predictions made by an analysis model when filling in missing data.

See also: score

data marshalling

A method of unpacking data so that it can be persisted in storage and later retrieved by unpacking. Commerce Server uses data marshalling to persist the contents of Dictionary objects to the database.

data member

A member of a class used to store a piece of data. A data member maps to a column in the underlying relational database in the Data Warehouse.

See also: class

data store

A SQL Server database or other database containing data used by a commerce site, such as information about registered users, products, or ads. This also refers to the server that contains the data (the data-store server).

Data Transformation Services (DTS)

A SQL Server component used to import, export, and transform data from different data sources. Commerce Server provides a set of DTS tasks that you use to import data into the Commerce Server Data Warehouse.

data type

A definition of a set of data that specifies the possible range of values for the set. Examples of data types are: number, decimal, and text.

Data Warehouse

In Commerce Server, a combination of a SQL Server database, an online analytical processing (OLAP) database, and a set of processes that a system administrator uses to import and maintain large amounts of data from multiple data sources.

Data Warehouse logical schema

See logical schema.

Data Warehouse Meta-model

A conceptual model that describes how to create the classes, data members, relations, and keys of the Data Warehouse logical schema.

Data Warehouse resource

A Commerce Server resource with global-level properties, managed through Commerce Server Manager. Use the Data Warehouse resource to specify the database connection string to the Data Warehouse database.

decision tree

A graphical representation of a collection of prediction rules showing the probability of one event predicting a second event based on historical data. The decision tree for attribute X encodes the probability distribution p( X | attributes that predict X ).

See also: dependency network

default component

A Component Object Model (COM) server object that ensures that critical values for the stage exist. Default components usually appear near the beginning of the stage.

See also: stage

default confidence

A value that represents probability of purchase. Only items that have a probability of purchase exceeding this number are returned.

dependency network

A graphical summary of the predictive relationships (dependencies) contained in a Predictor model. A graphical summary of the predictive relationships (dependencies) contained in a Prediction model. Use the Prediction Model Viewer to view a dependency network.

See also: arc, decision tree

descendant category

A category subordinate to another category through one or more parent-child relationships. A child category is a descendant category, as is a child of a child.

See also: ancestor category, child category, descendant products, root category, parent category

descendant products

Products associated with a category or any of its descendant categories.

See also: descendant category

design-time control (DTC)

A special type of ActiveX control used for generating text in an editing environment. Typically, a user is presented with several choices in the control; the choices a user makes will alter the details of a section of scripting code or HTML that is placed on the page being edited.

Dictionary object

An object used to support the creation, storage, and retrieval of name/value pairs in memory. Because every element in a Dictionary object is a Variant, you can create a Dictionary object that consists of almost any kind of value (including other Dictionary objects), and you can store any combination of Variant types in the same Dictionary object.

Digest authentication

One of the authentication methods that you can set at the Default Web Site or Application level in IIS. In Digest authentication, a hash value is sent across the network, rather than a clear password. This method works across proxy servers and firewalls, and is a high-security form of authenticated access.

dimension

A descriptive attribute of a measure, usually textual and usually discrete. For example, a dimension might describe the number of purchases. The numeric amount would be the measure.

See also: online analytical processing (OLAP), measure

direct mail

A mail message that is directed to a specific user and that meets the specific requirements of a direct mail campaign.

direct mail campaign

A campaign to distribute e-mail message ads to a targeted group of users. The objective is to achieve a high response rate from the mailings.

Direct Mailer

See Commerce Server Direct Mailer.

Direct Mailer database

A SQL Server database that contains e-mail message bodies, event data, and job data. Commerce Server Setup installs the Direct Mailer database when you install Commerce Server Direct Mailer. The database is installed on the same computer as Direct Mailer. Use Commerce Server Manager to specify the connection string from Direct Mailer to the Direct Mailer database.

See also: Commerce Server Direct Mailer

Direct Mailer job file

A text file that specifies information about the Direct Mailer job, such as whether it delivers personalized message bodies, the format of mail message headers, and the location of the list of recipients. A direct mailer job file is used only for the stand-alone mode of Direct Mailer.

direct price

A price that is associated with a specific product in a catalog rather than with a pricing category.

See also: indirect price

discount

A specific type of promotion in which shoppers are invited to save money on specific products or product groups if they meet certain specified conditions. In Commerce Server, discounts have a targeting component and a display component.

DTC

See design-time control.

DTS

See Data Transformation Services.

dual key

A type of key that is the combination of a primary key and a join key. You can use dual keys when you add profile attributes in Commerce Server Business Desk. See also join key, primary key.

See also: join key, primary key

dynamic list

A list of user records that the List Manager service creates at run time, when the list is needed (such as when the list data is being exported). Each time the list is requested, List Manager gathers the most recent data in the Data Warehouse. The information needed to create the list is stored in the List Manager database. (This differs from a static list where the entire list of user records is stored in the List Manager database.) Use dynamic lists for direct mail campaigns that you will run frequently, or if the list of recipients is updated frequently.

See also: static list

dynamic report

A report that is created at run time. Each time the report is run, it gathers the most recent data in the Data Warehouse. Only the report definition, which remains the same over time, is stored. (This differs from a static report, where the report is stored, with the data, in the Data Warehouse.) You can view dynamic reports in a PivotTable or a PivotChart. Use the Reports module to run dynamic reports.

DynamicTable HTML Component (HTC)

The HTML Component (HTC) used for editing the columns displayed in tabular data.

E

e-commerce

The process of buying and selling products and services over the Internet.

EDI

See Electronic Data Interchange.

edit page

One of two main types of action pages in Commerce Server Business Desk. Edit pages provide mechanisms for altering data in Business Desk. Edit pages do not share the Business Desk workspace with the navigation pane. The latter is hidden when edit pages are rendered, thereby preventing navigation to a different module until the edit page is dismissed and the user returns to a list page.

See also: list page

EditField HTML Component (HTC)

The HTML Component (HTC) used for editing individual items of data of various types. EditField HTCs are often embedded within other HTCs, such as the DynamicTable, the EditSheet, and the ListEditor.

EditSheet HTML Component (HTC)

The HTML Component (HTC) used to bundle together controls that are used to edit data.

Electronic Commerce

See e-commerce.

Electronic Data Interchange (EDI)

The transfer of data between different companies using networks, such as the Internet. As more and more companies connect to the Internet, EDI is becoming increasingly important as an easy mechanism for companies to use when they buy, sell, and trade information.

envelope

A named set of properties that represents a specific business document. Envelope properties include an envelope format and may include a pointer to an envelope specification. Or, the header and footer information, or header information only, that encapsulates electronic business data for transport.

event

The occurrence of a specific action performed by a user. Typical events include pressing a keyboard key or clicking a mouse to choose a button. Events are recorded with the time at which they occur. Programmers write code to respond to these actions.

See also: frequency

explicit price

A custom price that specifies a precise amount. An explicit price overrides the price specified in the base catalog.

explicit profiling

An information collecting process in which users visiting a Web site supply profile data about themselves. For example, users may fill in an online form with their names, addresses, phone numbers, and so forth.

See also: implicit profiling

explicit targeting

Delivering targeted content by using existing data about the users who browse your site.

exposure limit

The number of times a piece of content can be shown to a user within a session. By default the exposure limit is set to no exposure limit. It is recommended that the upper exposure limit is not set to more than 10 exposures per user per session.

expression

A condition that is evaluated against profiles to determine whether to deliver content or perform another action. For example, an expression might be "user.totalvisit > 100". If this expression evaluates to "True," then a specific piece of content is displayed to a user. Use the Campaign Expressions module to create expressions, and then combine the expressions with the action you want to perform after the expressions are evaluated.

See also: Expression Builder

Expression Builder

A tool you use to create an expression. The Expression Builder includes a list of common expressions that you can select from to define the properties you want to target. You access the Expression Builder when creating a new target expression or catalog expression from the Campaign Expressions module.

See also: expression

expression store

The tables in a Commerce Server database that store expression information.

See also: store

ExpressionBuilder HTML Component (HTC)

The HTML Component (HTC) used to create named expressions, which in turn can be used for targeting. The ExpressionBuilder HTC makes use of an embedded version of the QueryBuilder HTC.

Extensible Markup Language (XML)

A data format for structured document interchange on the Web. It is called the Extensible Markup Language because it is not a fixed format like HTML. XML is designed to enable the use of Standard Generalized Markup Language (SGML) on the World Wide Web. XML is not a single markup language. It is a metalanguage that allows an author to design a markup language. A regular markup language defines a way to describe information in a certain class of documents (for example, HTML). With XML, authors can define their own customized markup language for many classes of documents.

Extensible Markup Language (XML) data-island

XML data contained in, or accessible from, an ASP page. One of the two elements, xml and script, is used to define an XML data-island, and a particular XML data-island is referenced using the ID attribute of these elements. The data itself often exists within these elements, but can exist elsewhere when a source attribute is used to provide the Uniform Resource Locator (URL) of an alternate location.

Extensible Markup Language/ Hypertext Transfer Protocol (XMLHTTP) operations

The mechanism used by the ListSheet HTML Component (HTC) and the TreeView HTC to fetch XML data from the server, allowing new data to be displayed without the need to re-render the entire page displaying that data.

extranet

An extension of a corporate intranet using World Wide Web technology to facilitate communication with the suppliers and customers of a corporation. An extranet allows customers and suppliers to gain limited access to the intranet of a company in order to enhance the speed of communications and the efficiency of business relationships.

F

failover

The process of taking resources, either individually or in a group, offline on one server cluster node and bringing them back online on another node. The offline and online transitions occur in a predefined order, with resources that are dependent on other resources taken offline before and brought back online after the resources upon which they depend.

fetch page

A type of Active Server Pages (ASP) page designed to return Extensible Markup Language (XML) documents containing data in the standard XML data format. Only XML data is present on the page being returned. The ListSheet and TreeView HTCs expect this data format when they are engaged in XMLHTTP operations.

file caching

See caching.

Find pane

In Commerce Server Business Desk, an area in the upper portion of the module content pane in a list page. Find criteria are entered in the Find pane. Criteria are then used in a Find task. Most commonly, the lower portion of the module content pane consists of a ListSheet HTC in which the results of the Find task are displayed.

firewall

A security checkpoint that separates an intranet from the Internet (or Internet groups). Only specific data may pass through a firewall.

fixed amount off

The exact amount subtracted from the list price to arrive at a custom price.

fixed markup

The exact amount added to the list price to arrive at a custom price.

free-text searchable

A Yes/No flag in a property definition that indicates whether the property can be found through a free-text search. To set this flag to Yes, the property type must be string or enumerated. A free-text search locates exact matches and words that are inflectionally generated from the one(s) you specified. For example, the word "drive" would return matches for drives, drove, driving, and driven.

free-threaded components

COM components that can reside on multiple threads of execution. The components support access by multiple clients and do not rely on COM to synchronize calls to them.

frequency

The number of events divided by the reach of the events.

See also: event, reach

FrontPage server extensions

A set of programs you can use to administer, author, and browse a FrontPage-extended Web site.

full-text catalog

A SQL Server object that stores the full-text index of a database.

full-text index

The portion of a full-text catalog that stores all of the full-text words and their locations for a given table. When changes are made to a catalog (such as adding or removing products, or changing the values of free-text searchable fields), the full-text index must be updated to reflect the changes.

G

global resource

A resource that is available for use by all sites. Global resources expose an object at the global level in Commerce Server Manager, and at the site level of those sites that are using the global resource. Properties for a global resource are configured at the global level.

The following global resources are included with Commerce Server: Commerce Server Direct Mailer and Predictor (which are also Windows 2000 services), CS Authentication, Profiles, and Data Warehouse. Third parties can develop custom global resources to work with Commerce Server. Use Commerce Server Manager to manage global resources.

See also: resource

global resource pointer

A resource object exposed at the site level that serves to reference a global resource being used by that site. Such global resources might also be referenced and used by other sites.

globally unique identifier (GUID)

A 128-bit number that is guaranteed to be globally unique. Traditionally, GUIDs are created by running the Guidgen.exe command line program. The Guidgen.exe program never produces the same number twice, no matter how many times it is run or how many different computers it runs on. In Commerce Server, the GenID object can be used to generate GUIDs.

goaling

See campaign goaling.

group

The area within a Commerce Server Business Desk screen that has a collapsible heading, allowing the information in that section to be displayed or hidden as the user prefers. Also referred to as section.

GUID

See globally unique identifier.

H

hashing key

A unique key, often a column or group of columns in a database, that is used when searching for an item in a large list to increase lookup speed.

high precision currency value

A currency value represented as a 64-bit integer and scaled by 10000, as opposed to the 32-bit integers used in Site Server 3.0 Commerce Edition. In the Commerce Server 2000 representation, $1.99 is shown as 19900. Keys that have a high precision currency value assigned to it have a prefix of cy_. For example, the high precision currency version of the key _oadjust_adjustedprice is _cy_oadjust_adjustedprice.

hit

A single action (for example, a click on an advertisement) taken by a user at a Web site that results in one line of data being added to the Web server log file.

horizontal scaling

Increasing Web site capacity by adding more servers to the server cluster. Also called scaling out.

See also: vertical scaling

house ad

An ad that is served when paid ads are ahead of their Need of Delivery schedule. For example, a customer orders 1000 paid ads to be delivered over four months, but in the first two months the order has been served 850 times. To balance the Need of Delivery schedule, house ads would be served. House ads are also served when there are no paid ads eligible for the request.

For example, a house ad would be served because all paid ads missed a required target or hit an exclusion. A house ad is used to sell leftover inventory at discounted prices. They are also used if the ads on the site don't have specific delivery goals, but you want to have the ads run at specified weights.

See also: weight

HTA

See HTML Application.

HTC

See HTML Component.

HTML Application (HTA)

An Internet Explorer mechanism for displaying HTML as a standalone application. Commerce Server Business Desk is implemented as an HTA, and has code that prevents it from being run within a normal browser instance.

HTML Component (HTC)

A control implemented using Internet Explorer DHTML behaviors. HTCs are used in Commerce Server Business Desk modules for data display and manipulation.

HTTP

See Hypertext Transfer Protocol.

Hypertext Transfer Protocol (HTTP)

The client/server protocol used to transmit and receive all data over the World Wide Web. When you type a URL into your browser, you are actually sending an HTTP request to a Web server for a page of information.

I

identification

The process of mapping an object onto the supported identification schemas or getting the unique user identifier (UID). The operating system, IIS, or Commerce Server usually provides this identification.

IIS

See Internet Information Services.

IIS application

See application.

image

A visual element used on a Web page, such as an illustration, photograph, or background texture. Web-based images are typically .gif or .jpg formats.

implicit profiling

An information collection process in which the actions and behaviors of a user visiting a Web site are recorded as the user moves around in and interacts with the Web site.

See also: explicit profiling, Predictor resource

implicit targeting

Delivering targeted content by using your existing user data to extrapolate unknown information about users who browse your site. In Commerce Server, the Predictor resource enables you to segment users to support implicit targeting.

impression

See ad request.

Independent Software Vendor (ISV)

A third-party vendor who develops software, such as tax, shipping, or inventory software, that integrates with Commerce Server and extends its functionality. You can compare an ISV to a Solution Provider, who customizes Commerce Server for specific customers or vertical markets, and designs and deploys systems.

indirect price

A price that is associated with a pricing category. The price field in the product record is ignored.

See also: direct price

industry code

An identifier for a specific industry, for example, Automotive, Aviation, Beverage. You create industry codes using the Reference Tables module. The industry codes enable you to identify the associated industry for an ad, thus preventing two ads from competing advertisers in the same industry from appearing on the same page. Industry codes are associated with campaigns at the customer level; the industry code is used as the default for all the advertising campaigns for the customer. If you do not associate the industry code at the customer level, you must associate it at the advertising level.

inheritance

The ability of a newly created object to automatically have the properties of an existing object. For example, a newly created child directory can inherit the access-control settings of the parent directory.

Integrated Windows authentication

One of the authentication methods that you can set at the Web Site or Application level in IIS. This method employs the Windows logon user name and password for authentication, but does not prompt the user for this information unless the authentication of the current log on fails. It does not work over proxy connections, and is used for private areas of intranets.

intelligent cross-sell

A way to dynamically adapt the product recommendations displayed to users based on past purchase behavior and the products users are viewing or have added to their baskets. Use the Predictor resource to add intelligent cross-sell capabilities to your Web site.

See also: related sell, up sell

Internet

A set of distinct computer networks joined together with gateways that handle data transfer and the conversion of messages from the sending network to the protocols used by the receiving networks. These networks and gateways use the Transmission Control Protocol/Internet Protocol (TCP/IP) suite of protocols.

Internet address

See Internet domain name.

Internet domain name

The name used for hosting a site on the Internet. An Internet domain name is a combination of a second-level domain name (such as "Microsoft") and a top-level domain name (such as "com" or "net"), separated by a period. Before establishing a commerce site on the Internet, a business must first apply for and register a second-level domain name with an authorized Domain Name System (DNS) registration authority. This name must meet the requirements for external DNS naming, and must not already be registered or in use. To register the name, a business must obtain (or have an Internet Service Provider (ISP) obtain on its behalf) at least one Internet Protocol (IP) address valid for use on the Internet and the IP addresses of at least two currently active DNS servers on the Internet. Also called an Internet address, domain name, and URL.

Internet Information Services (IIS)

The Windows 2000 services that support Web site creation, configuration, and management, along with other Internet functions. You must install IIS on a server before you install Commerce Server.

Internet Service Provider (ISP)

A public provider of remote connections to the Internet. An ISP is a company that enables remote users to access the Internet by providing dial-up connections or installing leased lines. An ISP may host commerce sites for client companies, hosting several sites on a single server or server cluster. The ISP may provide the infrastructure and perform administration tasks common to all sites, while allowing clients to perform some site administration tasks from their remote computers.

intranet

A network designed for information processing within a company or organization. Its uses include such services as document distribution, software distribution, access to databases, and training. An intranet is so called because it usually employs applications associated with the Internet, such as Web pages, Web browsers, File Transfer Protocol (FTP) sites, e-mail, newsgroups, and mailing lists, in this case accessible only to those within the company or organization.

ISP

See Internet Service Provider.

ISV

See Independent Software Vendor.

J

join key

An association between a field in one table or query and a field of the same data type in another table or query. Commerce Server uses a join key to relate data in one data store used by the Profiles resource to data in another data store also used by the Profiles resource. For example, a join key may exist on the User Name property, relating the User Name field stored with data in Active Directory to the User Name field stored with data in a SQL Server table.

See also: dual key

K

key

An identifier for a record or group of records in a datafile. A key indicates a special property of a field or set of fields within a record. Possible key types include dual, join, primary, and unique.

See also: class key

L

LCID

See Currency Locale Identifier.

List Manager database

A database that stores lists of user records. You create lists of user records by using the List Manager module in Commerce Server Business Desk. The lists are available for use by the Direct Mailer to run a direct mail campaign, and in the Users module in Business Desk.

List Manager module

The Commerce Server Business Desk module used to create, import, export, copy, delete, and merge lists of user records. For example, you can create a list of recipients for a direct mail campaign.

List Manager service

A Windows 2000 service that performs the tasks you specify using the List Manager module in Commerce Server Business Desk. For example, you can create, delete, import, export, copy, and merge lists of user records. To create a list you can import data from flat files, a SQL Server database, the Data Warehouse, and Predictor resource segments. You can export lists to a flat file and to a SQL Server database.

list page

One of two main types of action pages in Commerce Server Business Desk. List pages provide a read-only view of some type of data, and typically allow that data to be filtered, sorted, selected, and otherwise acted upon. List pages typically consist of a ListSheet HTC, and sometimes a find pane above the ListSheet HTC. List pages share the Business Desk workspace with the navigation pane.

See also: edit page

ListBox HTML Component (HTC)

The HTML Component (HTC) used for list-to-list copy and move operations.

ListEditor HTML Component (HTC)

The HTML Component (HTC) used for editing tabular data where the editing of individual records occurs in a separate table below the table containing the list.

ListSheet HTML Component (HTC)

The HTML Component (HTC) used to display a list of records, and to select one or more of those records for editing. The ListSheet HTC is read-only.

load balancing

Scaling the performance of a server-based program (such as a Web server) by distributing its client requests across multiple servers within the server cluster. Each host can specify the load percentage that it will handle, or the load can be equally distributed across all the hosts. If a host fails, the load is dynamically redistributed among the remaining hosts. Network Load Balancing is the load balancing solution Windows Clustering uses, available on Windows 2000 Advanced Server.

load testing

See stress testing.

log file

A record of the transactions or the activities that take place on a computer system. The file can be either a text file or a database file. In Commerce Server, log files are imported into the Data Warehouse so you can analyze the activity on your site by using the Analysis modules in Commerce Server Business Desk.

logical schema

In the Data Warehouse, a conceptual model that maps to the data in the physical store, and provides an understandable view of the data. When a developer creates code to access or change data in the Data Warehouse, the developer interacts with the logical schema. Commerce Server processes access data in the Data Warehouse through the logical schema.

M

mailable list

A list with an rcp_email column that contains user e-mail addresses.

mailing list

A list for use with the Direct Mailer. A mailing list contains five standard fields: rcp_email, rcp_guid, rcp_fmt, rcp_locale, and rcp_url.

master configuration file

The XML configuration file that defines the categories and modules available within a particular instance of Commerce Server Business Desk. Each module entry identifies a module configuration file that contains the configuration information for that module.

MDX

See multidimensional expression.

measure

Data, generally numeric, that measures a business event. For example, the number of purchases a user made is a measure.

See also: dimension

message body

The content that is delivered in an e-mail message.

message header

The first part of an e-mail message that specifies the address of the recipient, the message format, the language, and optionally, the globally unique identifier (GUID).

messaging port

A set of rules configured by using BizTalk Messaging Manager with which you can direct how documents are enveloped, secured, and transported to a designated destination organization.

meta-data

Data used to describe other data. For example, data type is a piece of meta-data that further describes a property.

Microsoft Management Console (MMC)

A framework for hosting administrative tools called consoles. A console may contain tools, folders, other containers, Web pages, and other administrative items. These items are displayed in the left pane of the console, called a console tree. A console has one or more windows that can provide views of the console tree. The main MMC window provides commands and tools for authoring consoles.

See also: snap-in

MIME

See Multipurpose Internet Mail Extensions.

MMC

See Microsoft Management Console.

module

A choice you can select from the navigation pane on Commerce Server Business Desk. For example, you can choose the Campaign Manager, Catalog Designer, or Reports module. Each module is a set of ASP files that provides a particular type of related functionality and is organized with one or more entry points from the navigation pane.

module configuration file

An XML configuration file that defines the actions, tasks, and entry points for a Commerce Server Business Desk module (or set of modules). Module entry points identify the category with which they are associated.

MSCSAuth ticket

See authentication ticket.

MSCSProfile ticket

See profile ticket.

multidimensional expression (MDX)

An expression used for querying and manipulating the multidimensional data stored in OLAP server cubes.

multiple-choice property

A property that contains a set of predefined values. For example, you could create a multiple-choice property named Shirt_Size, and define the following possible values: S, M, and L.

Multipurpose Internet Mail Extensions (MIME)

A standard that extends the Simple Mail Transfer Protocol (SMTP) to permit data, such as video, sound, and binary files to be transmitted by Internet e-mail without having to be translated into ASCII format first.

N

navigation pane

In Commerce Server Business Desk, the window on the left side of a list page that displays the hierarchy of categories and modules.

Need of Delivery (NOD)

The formula that Commerce Server uses to determine the time and frequency with which it delivers a piece of content. This formula takes into account the total quantity of content to be delivered, and the length of time over which the quantity must be delivered. Need of Delivery is calculated for each ad request by the Content Selection Framework, after it has processed the ad request. Need of Delivery is applied to paid ads; it is not applied to house ads.

See also: ad request

NOD

See Need of Delivery.

node

A graphical representation of an attribute, as displayed by the Predictor Model Viewer.

See also: attribute

non-Commerce application

A container of non-Commerce Web servers with the common properties for the application. It is analogous to a Commerce application and its Commerce Web server members.

non-Commerce Web server

A Web server that Commerce Server has not been installed on. It produces W3C format log file which can be imported to the Data Warehouse and used for analysis. A non-Commerce Web server may or may not be running Internet Information Services (IIS).

non-transacted pipeline

A pipeline that does not support COM+ transactions. MtsPipeline and PooledPipeline are the only objects that support non-transacted pipelines.

See also: pipeline, pipeline object, transacted pipeline

O

OLAP

See online analytical processing.

online analytical processing (OLAP)

A class of technologies that are designed for live, ad-hoc data access and analysis. OLAP data is stored in a multidimensional database, which considers each data attribute (such as product, geographic sales region, and time period) as a separate dimension. OLAP data is grouped and organized, by shared dimensions, in cubes. The Data Warehouse uses OLAP cubes to store imported data, which accelerates report and query processing.

See also: dimension, cube

operational data

Data that is collected, typically in log files, on a daily or other periodic basis. After it is collected, operational data is often imported into the Data Warehouse.

opt in

An action a user takes to subscribe to a mailing list.

opt out

An action a user takes to unsubscribe from a mailing list. The user is added to the opt-out list.

opt-out list

A list of users who have chosen to unsubscribe to a mailing list.

order

An online purchase submitted by a user to your Web site. An order typically includes one or more items, the name and address of the user, and the form of payment for the purchase.

order form object

The object that stores state data about the current, and possibly historical, purchases of a particular user.

Order Processing pipeline

The software infrastructure that links several components and runs them in sequence. Commerce Server 2000 includes three Order Processing pipelines: product, plan, and purchase.

order status code

A numerical data code used in Commerce Server Business Desk to identify the types of order status used on your Web site. For example, you may create order status codes to define saved orders, deleted orders, or unprocessed orders.

Order Status module

The Commerce Server Business Desk module used to view order status information and display all the details associated with an order including the order header and line-item information.

organization

A company, division, department, or other business unit within a company that is designated within Commerce Server Business Desk as a source or destination for the exchange of business documents. The set of properties that represent the key characteristics of the organization related to the electronic exchange of documents is referred to as an organization profile. Also, an organization is a grouping of users.

See also: Organizations module

organization profile

A set of properties that describe a company, division, department, or other business unit within a company. For example, name, account number, spending limits, company discount, and so forth, are all properties that can constitute an organization profile. In Commerce Server Business Desk, you can set up an organization profile for companies with which you have a business relationship.

Organizations module

The Commerce Server Business Desk module used to add, modify, or delete organization profiles.

See also: organization

P

package

A file created by the Commerce Server Site Packager deployment tool that contains all the data necessary to deploy a site onto a different computer. This includes applications and resources, including the resource property settings stored in the Administration database. A package does not contain those property settings that are specific to a computer (such as connection strings). Package files have a .pup extension.

page group

A set of associated Web pages that you create using the Reference Tables module in Business Desk. For example, if you are running a newspaper site, you might create a page group for Sports, one for the Top Story, and another for Local News. You can set advertising rates by page group, run reports to see the total number of hits for a page group, and target ads to run on specific page groups. A site developer must ad-enable a Web page before it can be assigned to a page group.

parent category

An entity used in catalogs to group a set of products in a hierarchy. For example, Music is a parent category, and Rock, Country, and Classical are child categories. You create parent and child categories to organize the products displayed on your site.

See also: ancestor category, child category, descendant category, root category

percentage markup

The percentage amount that the list price is increased to arrive at a custom price. For example, a 20 percent increase means that the price is 120 percent of the list price.

percentage off

The percentage amount that the list price is decreased to arrive at a custom price. For example, a 20 percent discount means that the price is 80 percent of the list price.

personalization

A feature with which you can direct Web-based content or e-mail messages to users based on their user profile data and their previous requests for content.

See also: target group, Campaign Expressions module, Commerce Server Direct Mailer, Predictor resource, target expression

physical store

The physical databases that comprise the Data Warehouse.

pipeline

A software infrastructure that defines and links together one or more stages of a business process, running them in sequence to complete a specific task. Each stage of a pipeline contains one or more pipeline components (COM objects) that can be configured to work with the unique requirements of the site.

See also: non-transacted pipeline, pipeline object, transacted pipeline

pipeline component

The Component Object Model (COM) server object that implements the required pipeline component interfaces. Each component performs operations on some part of an OrderForm object or Dictionary object before sending it to the next component or stage in the pipeline.

pipeline configuration file

A file containing the configuration data for a pipeline. The pipeline specified in the file is created and run by a pipeline object. The file contains stages and components that can be customized using the Pipeline Editor.

pipeline configuration template

The template file used to create new pipelines. The pipelines created using a pipeline configuration template are saved as pipeline configuration (.pct) files. The templates serve as the basis for creating custom pipelines. Stages and components can be added, deleted, or renamed in any template.

Pipeline Editor

An application used to create and edit Commerce Server pipeline configuration (.pcf) files. The Pipeline Editor displays a pipeline as a pipe graphic, showing the stages of the pipeline as segments of the pipe. The components used in a stage appear as valves.

pipeline object

An object that uses pipeline configuration files to execute a series of components. Commerce Server 2000 provides six objects to execute pipelines: MtsPipeline, MtsTxPipeline, PooledPipeline, PooledTxPipeline, OrderGroup, and OrderPipeline. The MtsPipeline and PooledPipeline objects do not support COM+ transactions.

See also: non-transacted pipeline, pipeline, transacted pipeline

PivotChart report

A report that is displayed in an interactive chart. You can use the chart to view and rearrange data graphically, in a similar manner to a PivotTable report. In Commerce Server, you can view dynamic reports as PivotChart reports. To view PivotChart reports, use the Reports module in Commerce Server Business Desk.

PivotTable report

A report that is displayed in an interactive table. You can rotate the rows and columns of the table to see different summaries of the source data, filter the data, or display detail data for different areas of interest. In Commerce Server, you can view dynamic reports as PivotTable reports. To view PivotTable reports, use the Reports module in Commerce Server Business Desk.

pooled pipeline

The pipeline object that is registered with COM+ to take advantage of object pooling.

popularity penalty

A penalty applied to a prediction that reduces the probability that a popular (well known) item will be recommended.

port

See messaging port.

Prediction model

A summary of the data that is used by the algorithm for prediction. Use the Prediction Model Viewer in Commerce Server Manager to view Prediction models.

prediction model configuration

A user-defined description of the data used for a Prediction or Segment model.

Prediction Model Viewer

A browsing tool used to view both the dependency network and the individual decision trees of a Prediction model.

Predictor resource

A global resource that is also a Windows 2000 service. The Predictor resource is managed through Commerce Server Manager, and consists of a powerful data-mining engine that enables you to provide predictive capabilities for your Web site based on the aggregate properties of the entire user population that visits your site. Use the Predictor resource to build analysis models that you then deploy to your Web site in order to analyze user information.

See also: implicit profiling, personalization

pricing category

A category in which every product gets the price from the category. That is, the category overrules the price assigned at the product level.

primary key

One or more fields (for example, in a column) whose value or values uniquely identify each record in a table. A primary key cannot allow Null values and must always have a unique index. A primary key is used to relate a table to foreign keys in other tables.

See also: unique key, dual key

probability distribution

For a discrete attribute, a set of probabilities, one for each possible value of the attribute.

For a continuous attribute, x, a function that when integrated from a to b yields the probability that the value of x lies between a and b. Also known as a probability density for x.

product

An item for sale in a catalog. Each product is an individual instance of a product definition. For example, a product based on the Book product definition (which has the properties "Author," "Title," and "List Price") may have the properties "Bill Gates," "The Road Ahead," and "$15.00." Use the Catalog Editor module in Business Desk to manage products.

Product Catalog resource

A Commerce Server resource with site-level properties, managed through Commerce Server Manager. Use the Product Catalog resource to configure the connection string to the database containing catalog data.

product definition

The properties that are available in a particular product type. Each product is associated with a product definition. For example, the Book product definition could contain the following properties: "Author," "Title," and "List Price." A product definition must have one product identifier, such as a stock-keeping unit (SKU), and always has a List Price property. Use the Catalog Designer module in Business Desk to manage product definitions.

product family

A product that has product variants. For example, the product family "Women's Thermal Shirts" may include the following product variants: red shirt, blue shirt, and green shirt. A product family always has a unique identifier, such as the name of the product.

product identifier

A required property that uniquely identifies products within a catalog, such as a stock-keeping unit (SKU). A product identifier cannot be removed from the product definition. .

product pricing

Determining how much to charge a particular user for a particular product.

product properties

The properties that form a product definition. For example, the Book product definition may have the following product properties: "Author," "Title," and "List Price." Use the Catalog Designer module in Business Desk to manage product properties.

product relationship

A way of associating one product in a catalog with another product or category. For example, printers may be related to printer ribbons or ink cartridges, but these products would be in different categories. A product relationship has a name, indicating the type of relationship (for example, "Accessory"), and it has a source product or category and a target product or category. Use the Catalog Designer module in Business Desk to manage product relationships.

product variant

A specific item that is grouped with related variants that together form a product. Variants usually vary from each other in one or more properties. For example, a medium-sized, green shirt with a stock-keeping unit (SKU) of 14678 is one product variant of the Shirt product; together size, color, and SKU form one variant. A product variant always includes a unique identifier, such as an SKU, and a price. Each product variant is based on the same product definition.

product variant properties

The properties that vary among product variants. For example, the product variant medium-sized, green shirt, has two product variant properties: size and color.

profile

A set of characteristics that define any business-related item, such as a user, a company, or a business process. Each profile is an individual instance of a profile definition. For example, a profile based on the New User profile definition may have the properties Amy Egert, 52, Female. You can specify the profile data that the Users module collects about users who visit your site. This information may include name, age, gender, address, and so forth.

profile definition

The properties that are available in a particular profile type. Each profile is associated with a profile definition. For example, the New User profile definition could contain the following properties: name, age, gender, address, and so forth. Use the Profile Designer module in Business Desk to manage profile definitions.

Profile Designer module

The Commerce Server Business Desk module used to add and change profile definitions.

profile property

A characteristic that specifies which profile data is to be collected when a user visits your Web site. For example, the First Name property specifies that the first name of the user should be collected. Use the Profile Designer module in Business Desk to manage profile properties.

profile property attribute

A characteristic that describes a profile property. Profile property attributes include information such as the data type of the profile property (for example, number, text, and decimal), whether the property is single-valued (for example, only one First Name is allowed) or multi-valued, and whether the user visiting the Web site can perform a search using this property.

profile ticket

A ticket created by Commerce Server for anonymous (guest) users. Also called MSCSProfile ticket.

See also: authentication ticket, ticket

ProfileDesigner HTML Component (HTC)

The HTC used to edit profiles, such as a user profile.

Profiles resource

A Commerce Server resource with global-level properties, managed through Commerce Server Manager. You use the Profiles resource to specify the database connection string to the database containing user profile data. You also use the Profiles resource to create, edit, and delete profile properties and profiles. You can add and remove data sources, such as SQL Server databases or Active Directory data sources.

ProgID

See Programmatic Identifier.

Programmatic Identifier (ProgID)

A unique name that identifies a program or Component Object Model (COM) object. Unlike a globally unique identifier (GUID), a ProgID is usually an intelligible alphanumeric string, for example, "Commerce.Dictionary."

property

A characteristic of a product, category, or profile. All properties have a name and a data type (for example, Description text).

property definition

A specification of a property that is available for use in profile definitions, category definitions, or product definitions. For example, you might create a property definition named Description that is type "string." Or you might create a property definition named Gender that is type "enumerated" and it accepts only two values: "Male" or "Female." Use the Catalog Designer module and the Profile Designer module in Business Desk to manage property definitions.

property-based search

A search method in which you can search a catalog for products that have properties with specific values (such as price > $20 and color = blue).

proxy server

A firewall component that manages Internet traffic to and from a local area network (LAN) and can provide other features, such as document caching and access control. A proxy server can improve performance by caching and directly supplying frequently requested data, such as a popular Web page, and can filter and discard requests that the owner does not consider appropriate, such as requests for unauthorized access to proprietary files.

Publish Campaigns module

The Commerce Server Business Desk module used to update your site with new campaign information. The Publish Campaigns module empties the caches that store campaign information for your site. The next time Commerce Server receives a request for campaign data, the updated data is loaded in the caches.

See also: cache

Publish Profiles module

The Commerce Server Business Desk module used to update your site with new profile information. The Publish Profiles module empties the caches that store profile information for your site. The next time Commerce Server receives a request for profile data, the updated data is loaded in the caches.

See also: cache

Publish Transactions module

The Commerce Server Business Desk module used to update your site with new transaction information such as new tax rates and shipping methods. The Publish Transactions module empties the caches that store transaction information for your site. The next time Commerce Server receives a request for transaction data, the updated data is loaded in the caches.

See also: cache

PUP

See Commerce Server Site Packager.

Q

query

A specific request to retrieve, change, or delete data.

QueryBuilder HTML Component (HTC)

The HTML Component (HTC) used to build a simple query.

R

reach

The number of unique users who performed a specific action, such as clicking on a specific ad.

See also: frequency, click frequency

recommendation score

A value that measures the quality of analysis models when used to recommend products for cross selling. The score measures the quality of a ranked list of recommendations returned from the models.

See also: score

Reference Tables module

The Commerce Server Business Desk module used to create and manage content sizes, industry codes, and page groups.

registered user

Someone who visits a Web site and purposefully supplies personal information, such as name, address, and phone number. This information is transmitted back to the server and can be used to tell you how many of your customers are male and female, how many purchased specific items, which customers consistently order the same products, and other specific details.

related sell

A class of promotions that help display additional merchandise to users by creating a relationship between the product they are viewing or have in their basket, and other related products. Use the Commerce Server 2000 Software Development Kit to provide up-sell and cross-sell functionality to your site. Use the Predictor resource to add intelligent cross-sell functionality.

See also: cross sell, intelligent cross-sell

relation

See class relation and class member relation.

reliability

A measure of the time between failures (mean time between failures), where failure is defined as a departure from acceptable service for an application, a computer system, or the network system. In contrast, availability involves reliability as well as the time required to bring a system back to normal operations after it goes down (or is taken down for planned maintenance or upgrade). When you plan for a Commerce Server installation, you plan your hardware, network, and operational procedures to obtain the level of reliability you require.

replication

The process of copying content and/or configuration settings from one server node to another. You can copy files manually or use replication software to copy them automatically. Replication is a necessary function of server clustering to ensure fault tolerance.

report definition

The fields and queries that are populated with data when a report is run. Each report has its own report definition. When you customize a report, you customize the report definition, not the report that contains the data.

Reports module

The Commerce Server Business Desk module used to select and run a report.

request

Any connection to an Internet site that requests content to be retrieved from a URL. Unlike hits, requests are related to content and user behavior. For example, if a user requests an HTML page that has three graphics files, the Web server might make a log entry for the three graphics files, the HTML page, and perhaps add some lines for overhead. However, for the Reports run in the Analysis module in Business Desk, only one request is counted. Also known as a Web request or an HTTP request.

request duration

The time between two consecutive requests in the same visit.

required component

The Component Object Model (COM) server object that ensures the integrity of data leaving the stage. Required components also perform currency and integer conversions so that stages containing all Site Server 3.0 Commerce Edition components will perform properly with stages containing all Commerce Server 2000 components.

resource

An entity that provides functionality to the applications in a Commerce Server site. A resource has one or more COM objects. These are used on the Web pages of an application to access the functionality of the resource. A resource may have global properties or site-level properties, but not both. Resource properties are stored in the Administration database. A set of resources ships with Commerce Server; some of these resources are also Windows 2000 services. Third parties can develop custom resources to work with Commerce Server. Use Commerce Server Manager to manage resources.

See also: global resource, service, site resource

root category

A category that is not a child of any other category. A root category may or may not have children, but it does not have a parent.

See also: child category, ancestor category, descendant category, parent category

root product

A product contained in a catalog that is not associated with any category.

S

scaling

Expanding the capacity of a Web server or server cluster to accommodate increased site traffic and improve site performance.

scaling out

See horizontal scaling.

scaling up

See vertical scaling.

score

A measurement of how accurately an analysis model predicts new data. You use these scores to measure the effectiveness of analysis models as you adjust the values used for the Sample size and Input and output attribute fraction parameters in the Build Model dialog box.

See also: data fit score, recommendation score

segment

In the Segment Viewer module, a group of users who share similar profile properties.

segment comparison

In the Segment Viewer module, a view showing the differences between the selected segments.

segment group

In the Segment Viewer module, a collection of similar segments.

segment hierarchy

In the Segment Viewer module, a hierarchical arrangement of segments and segment groups in which a parent segment includes all the users that its child segments contain. The top-level segment group represents the entire population.

Segment model

In the Segment Viewer module, a summary of the data that is used by the algorithm for segmentation. Use the Segment Viewer module in Commerce Server Business Desk to view Segment models.

segment summary

In the Segment Viewer module, a sorted list of the most significant properties that characterize a segment.

Segment Viewer module

The Commerce Server Business Desk module used to identify usage trends and make marketing decisions based upon similarities among users.

segmentation

A data mining technique that identifies groups of cases that are similar to each other. Use the Segment Viewer module to perform segmentation.

server cluster

Two or more computers connected together for the purpose of sharing resources and request load. Each member of a server cluster is called a node. Nodes in a server cluster can have their own storage devices or share a common device. Typically, server clustering involves support for load balancing, fault tolerance, and failover.

See also: Web farm

server extensions

A set of programs on a Web server that support administering, authoring, and browsing a FrontPage-extended Web site.

server farm

See server cluster, Web farm.

service

A program, routine, or process that performs a specific system function to support other programs, particularly at a low (close to the hardware) level. When services are provided over a network, they can be published in Active Directory, facilitating service-centric administration and usage. Services have a set of common administrative functions. For example, a service can be started, stopped, paused, or resumed; its start parameters can be modified; and it can be administered using command line utilities and scripts. Commerce Server includes the following resources that are also services: Direct Mailer, Predictor, and List Manager.

See also: resource

Shipping Methods module

The Commerce Server Business Desk module used to define your shipping method, either by weight, quantity, or subtotal.

site

In Commerce Server Manager, a container for Commerce Server applications and site-level resources. For example, the Retail site contains two applications: the business-to-consumer Web site and the business-to-consumer Commerce Server Business Desk, and both share the same site-level resources.

Site Configuration Store

The Administrative database containing configuration settings for the site, including the base currency, alternate currency, and SMTP server name.

site developer

The person who writes the HTML/ASP code for your Web site to customize it for your business. This person might also customize reports and add or modify Business Desk modules to extend the functionality for your unique business needs.

Site Packager

See Commerce Server Site Packager.

site resource

A resource that is available for use by a specific site. All resources used by a site expose an object at the site level in Commerce Server Manager. For example, a global resource can also be a site resource: a global resource used by a site exposes an object at the site level; the only property that the object exposes is a pointer to the associated global resource at the global level.

A site resource can have all of its properties at the site level, or all of its properties at the global level, but it cannot have both. You configure the properties of a site resource at the site level. A set of site resources is included with Commerce Server, and third parties can develop custom site resources. Use Commerce Server Manager to manage site resources.

See also: resource

site terms

A list of specific values that are pertinent to your site. You use a site term to assign this list of values, called terms, to a profile property as the property type. For example, you can create a site term named Gender, and define the following possible terms: "Female," "Male," and "Unknown." When you create a profile property named Gender, and assign the gender site term as the type reference, users will be able to select "Female," "Male," or "Unknown" from the drop-down list that is displayed for the gender property on your Web site. Users can select only one of the possible values for the property.

By applying site terms to profile properties, you establish common words that can be used throughout Commerce Server, for example, to target advertising content to users.

See also: Site Terms Editor module, Site Vocabulary

Site Terms Editor module

The Commerce Server Business Desk module used to add and edit site terms.

See also: site terms

Site Vocabulary

A hierarchically arranged set of possible values for user and content attributes in Site Server 3.0. In Commerce Server 2000, Site Vocabulary becomes site terms.

See also: site terms

SKU

Stock keeping unit. In Commerce Server, the SKU is a unique identifier, usually alphanumeric, for a product. The SKU allows a product to be tracked for inventory purposes. A SKU can be associated with any item that can be purchased. For example, a shirt in style number 3726, size 8 might have a SKU of 3726-8.

snap-in

A type of tool you can add to a console supported by Microsoft Management Console (MMC). A stand-alone snap-in can be added by itself; an extension snap-in can only be added to extend the function of another snap-in.

See also: Microsoft Management Console (MMC)

Solution Site

A set of Commerce Server features that are pre-configured for a specific site scenario and bundled into a package file. Commerce Server includes the Blank Solution Site in the box. The other two sites, Retail and Supplier, are available online at http://www.microsoft.com/commerceserver/solutionsites. Each Solution Site is designed to be unpacked and then customized to meet the needs of your site.

specification search

A search method in which you can perform a progressive drill-down search of products by specifying parameter constraints, such as a category, product, or property. To perform a specification search, you search for properties by progressively reducing the number of products that match your search criteria. Specification searches are useful when you do not want to search all of your products for a property, but you need to identify a group of products instead.

specification searchable

A Yes/No flag in a property definition that indicates whether the property can be found through a specification search.

sponsor

An advertising customer who pays to run ads on specific sections or pages of a site, to the exclusion of all other ads. These ads are given priority over all other ads, even targeted ads. Often these ads are messages that are integrated with your content on an exclusive basis, for example, transition ads with "brought to you by" messages. Both pages and targets can have sponsors. To set up this type of ad, use the Target Groups module in Business Desk and specify the sponsor action in a target expression.

stage

A subdivision of a pipeline that serves as a logical grouping of components. For example, the Tax stage groups together pipeline components related to calculating the tax that should be applied to a particular order.

See also: default component, stage affinity

stage affinity

A quality of components that can function within a given stage. To identify the stage or stages with which a component has an affinity, you write the class ID of the new component to the \HKEY_CLASSES_ROOT\CLSID\component_classid\implemented categories\stage_catid key within the Microsoft Windows NT Registry, where stage_cat_id is the globally unique identifier (GUID) of the stage with which the component will have an affinity, and where component_class_id is the class ID of the component itself.

See also: stage

state code

A three-character data code used in Commerce Server Business Desk to identify the state or province to which products will be shipped. State codes must be set up in order to use the Tax module of Commerce Server Business Desk.

static list

A list of user records that is created immediately upon request, and then stored in the List Manager database. (This differs from a dynamic list, where only the information needed to create the list is stored in the List Manager database.) Use static lists for direct mail campaigns that you run infrequently, or if the list of recipients does not change frequently.

See also: dynamic list

static report

A report that is run immediately upon request and then stored, with the data, in the Data Warehouse. (This differs from a dynamic report, where only the information needed to create the report is stored in the Data Warehouse.) You can post static reports to your Web site, and you can export the data in a static report to the List Manager module in Business Desk. Use the Reports module to run static reports, and use the Complete Reports module to view them.

status bar

The short, wide display area at the bottom of the Commerce Server Business Desk content pane. It is used to display current task status, such as a loading message, and a key of symbols used in the HTML components (HTCs) in the action page.

See also: action page

store

A specific set of tables in a database.

See also: expression store

stress testing

Testing performed on a Commerce Server application to ensure that it can support the expected number of concurrent users and handle peak user loads while maintaining the required level of performance. Stress testing is performed with a stress tool that generates loads defined by the system administrator to approximate the expected use patterns of the site. Also called load testing.

subscribe

The process in which users add their e-mail addresses to a List Manager list to receive content, or supply registration information so they can retrieve content or access a service or site.

supplier

A trading partner in a business-to-business site. Use Microsoft BizTalk Server to add suppliers to a site. Also known as a vendor.

system administrator

The primary user of Commerce Server Manager. This person is responsible for installing, configuring, and managing Commerce Server.

T

target

One or more expressions that identify who, where, and when content should be displayed. You can target demographics, sections of a Web site, or both.

See also: target group, target expression

target action

An option that specifies that a piece of content is to be shown when the target is met more often than when the target is not met. Use target action when it is difficult to deliver against the targeting goals of the campaign item (for example, there is not enough of the target available to require the content be shown). For example, if you are to deliver 1000 ad requests to users who live in Alaska, and you only have 15 users in Alaska, you need to deliver that ad to users who do not live in Alaska. Use the Target Groups module in Business Desk to specify the target action for an expression.

target expression

For Commerce Server campaigns, an expression that identifies where, when, and to whom content should be displayed. For example, you can target content to users who have specific profile properties. You can also target content to specific sections of a Web site. For example, you can create a target expression that will display certain ads only on Sports pages.

See also: personalization, target

target group

A collection of targets that content is to be shown to. When you form a target group, you combine two or more expressions. By combining expressions in a target group, you can create expressions that use OR statements, effectively targeting a wider audience.

See also: personalization, target

Target Group module

The Commerce Server Business Desk module used to manage target groups.

targeting

Delivering specific content to specific users.

task

In Commerce Server Business Desk, an operation performed from an action page, often leading to the display of a different action page where the details of the task are performed. Tasks are initiated by pressing a task button. Some tasks, such as Edit and Remove, are context-sensitive; they apply to whatever is selected in the current action page.

Tax Rates module

The Commerce Server Business Desk module used to update tax tables and rates for your Web site.

text file

A file composed of text characters. A text file can be a word-processing file or a plain ASCII file encoded in a format that can be read by nearly all computers. For the Campaigns Manager module, text is one of the types of display available for ads and discounts. An ad of this type displays as lines of text on the page.

three-tier architecture

An architecture that divides a networked application into three logical areas: the user interface layer (also called the top tier), the business logic layer (also called the middle tier), and the database layer (also called the bottom tier or back end). Layers can have one or more components. For example, there can be one or more user interfaces in the top tier. Also, each user interface can communicate with multiple applications in the middle tier at the same time, and the applications in the middle tier can use multiple databases at a time. Components in a tier can run on a computer that is separate from the other tiers, communicating with the other components over a network.

ticket

A string of property/value pairs used to store authentication and other information about a user. For example, "userID/joeuser" is a property/value pair. Ticket data can be stored in a cookie or a URL query string.

See also: authentication ticket, cookie, profile ticket

toolbar

The horizontal row of buttons located at the top of a Commerce Server Business Desk screen when the content pane is displayed. You use these buttons to access the functionality available from that Business Desk screen.

trading partner

An external organization with which your organization exchanges electronic data. The exchange of data among trading partners is governed by the agreements, pipelines, and distribution lists that are created between your organization and the trading partners. The exchange of data among trading partners is handled by Microsoft BizTalk Server 2000.

transacted pipeline

A pipeline that supports COM+ transactions. MtsTxPipeline and PooledTxPipeline are the only objects that support transactions. If any component in a transacted pipeline fails, the work of the preceding components in the pipeline is undone, and the object ends the transaction.

See also: non-transacted pipeline, pipeline, pipeline object

transaction

A group of operations that are logged so that, if necessary, the operations can be undone in case of an error. Commerce Server 2000 provides pipeline objects that support transactions.

Transaction Config resource

A Commerce Server resource with site-level properties, managed through Commerce Server Manager. Use the Transaction Config resource to configure the connection string to the database containing transaction meta-data.

transaction data

The data that is generated when users purchase products from your site. Transaction data can include any user activity recorded from a product page, a basket page, or a checkout page. For example, it might include the name, shipping address, date and time, product purchased, and total order value.

Transactions resource

A Commerce Server resource with site-level properties, managed through Commerce Server Manager. Use the Transactions resource to configure the connection string to the database containing transaction meta-data.

TreeView HTML Component (HTC)

The HTML Component (HTC) used to display an Extensible Markup Language (XML) structure in an expandable tree format.

TRUSTe

An independent, non-profit initiative whose mission is to build the trust and confidence of users on the Internet by promoting the TRUSTe principles of fair information practices. Microsoft is a premier sponsor of TRUSTe and a member of the TRUSTe privacy program.

U

Unified Modeling Language

A visual modeling language for software systems.

Uniform Resource Identifier (URI)

Identifies points of content on the Internet. The content can be a page of text, a video or sound clip, an image, or a program. The most common form of URI is the Web page address, also known as the Uniform Resource Locator (URL). A URI usually includes the file name for the resource, the name of the computer the resource resides on, and the protocol used to access it. For example, http://www.microsoft.com/sql/techinfo/security/password.htm.

Uniform Resource Locator (URL)

The address of a file (resource) accessible on the Internet. The type of resource depends on the Internet application protocol. For example, for the Hypertext Transfer Protocol (HTTP) used on the World Wide Web, the resource can be an HTML page, an image file, a program such as a Common Gateway Interface (CGI) application or Java applet, or any other file supported by HTTP. The URL contains the name of the protocol required to access the resource, a domain name that identifies a specific computer on the Internet, and a hierarchical description of a file location on the computer.

unique key

A field that contains a unique identifier for each record in a table. For example, the social security number field is a unique key for employee records.

See also: primary key

unregistered user

Someone who visits a Web site and purposefully does not provide the personal or identifying information required to register.

up sell

A specific type of related sell that suggests to users that they replace a product they are looking at or have in their basket with a better product. Use the Software Development Kit to add up-sell functionality to your site.

See also: intelligent cross-sell

update

To rebuild the full-text index. Used only in the Catalog Editor module of Commerce Server Business Desk.

URI

See Uniform Resource Identifier.

URL

See Uniform Resource Locator.

usage profile

A set of properties that describe the traffic patterns on a site. For example, a usage profile shows how many people browse a certain page, what is the browse-to-buy ratio, and how many users ad an item to their basket and then remove it. System administrators use the usage profile to determine how many Web servers are needed and to configure a site.

user

A person who visits a commerce site at least once. User refers to any person who clicks on the site, whether or not the user has registered.

user list

A list with an rcp_guid column that contains user IDs.

user profile

A set of predefined properties that describe a user. For example, name, address, and gender properties can constitute a user profile.

Users module

The Commerce Server Business Desk module used to modify user records and add and delete user information.

V

value

The actual data assigned to a profile property. For example, the profile property "First Name" might have the value "John."

variant

A single combination of the attributes that are available for a product. For a given type of shirt, for example, each combination of color, size, and unique stock-keeping unit (SKU) is a variant. Each product variant always includes a unique identifier, such as a stock-keeping unit (SKU), and a price. Each product variant is based on the same product definition.

vertical scaling

Increasing Web site capacity by upgrading hardware (for example adding RAM or processors), while maintaining the physical footprint and number of servers in the server cluster. Also called scaling up.

See also: horizontal scaling

vignette ad

An ad composed of text that is displayed adjacent to the image where the ad is displayed. The text can be to the left, right, or top of the ad image.

virtual directory

A directory name, used in a Web address, that corresponds to a physical directory on the server; sometimes called URL mapping. In Internet Information Services (IIS0 5.0, a virtual directory is the next item in the Microsoft Management Console (MMC) hierarchy under a Web Site (virtual server), and inherits properties from the Web Site. Some of these properties can be overridden at the virtual directory level; other cannot. Applications, including Commerce Server applications, are at the virtual directory level in IIS, and have the same parent-child relationship with the Web Site.

virtual server

Also called a Web Site (such as the Default Web Site). A virtual computer that resides on an HTTP server but appears to users as a separate HTTP server. Several virtual servers can reside on one computer, each one capable of running its own programs and each one with individualized access to input and peripheral devices.

Each virtual server has its own Internet domain name and Internet Protocol (IP) address and appears to users as an individual Web site. Some Internet Service Providers (ISPs) use virtual servers for those clients who want to use their own domain names. An ISP may want to create multiple Internet Information Services (IIS) 5.0 Web Sites and unpack Commerce applications for different clients into separate IIS Web Sites. Commerce applications under different IIS Web Sites can share global resources.

visit

A series of requests by a user. A visit begins in one of two ways: the user can be referred to the site through a link, or the user can type the site URL in his or her browser. A visit ends when a specified period of time (the default is 30 minutes) has passed without any additional requests to the site.

visit duration

The time between the first and last request of a visit. This time does not include the time a user spends viewing the last request of a visit.

W

Web application

See application.

Web farm

Two or more Web servers connected together for the purpose of sharing resources and request load. Typically, a Web farm will involve support for load balancing, fault tolerance, and failover, and will appear to the user as a single server with a single Internet Protocol (IP) address. Also called a server farm or server cluster.

See also: cluster, server cluster

Web server

In general use, a computer equipped with the server software that uses Internet protocols such as HTTP to respond to Web client requests on a Transmission Control Protocol/Internet Protocol (TCP/IP) network.

In Commerce Server, a Web server is a physical server computer running Internet Information Services (IIS) 5.0; it inherits properties from the IIS Web Site. A Web server appears under an application in the Commerce Server Manager console. One commerce application can use multiple Web servers that serve different types of content for the application.

Web site

In general use, a collection of files and applications accessed through a Web address, covering a specific theme or subject, and managed by a particular person or organization. A Web site resides on servers connected to the Web network and provides content that is available to worldwide users 24 hours a day, seven days a week. Web sites typically use HTML to format and present information and to provide navigational facilities that enable users to move within the site and around the Web. From an Internet Information Services (IIS) 5.0 administration standpoint, Web Site specifically means a virtual server (such as the Default Web Site). A virtual server is a virtual computer that resides on an HTTP server but appears to the user as a separate HTTP server. Several virtual servers can reside on one computer, each one capable of running its own programs and each one with individualized access to input and peripheral devices. Each virtual server has its own Internet domain name and Internet Protocol (IP) address

weight

A means of determining when a campaign item is displayed, relative to all of the campaign items for a given customer. In a campaign, weight only applies to ads that are goaled at the campaign-level. For house ads the weight is relative to all other house ads for all customers and all campaigns. For paid ads, the weight is relative to other paid ads in the same campaign. To determine when discount campaign items are displayed you use priority, not weight.

See also: house ad

Windows Media Services ad

An ad that displays high quality audio and video advertisements.

Windows Script Host (WSH)

A language-independent scripting environment for 32-bit Windows platforms, installed by default with Windows 2000 and IIS. WSH can be used to automate administrative tasks on a server, using any scripting language.

WSH

See Windows Script Host.

X

XML

See Extensible Markup Language.

XML data-island

See Extensible Markup Language (XML) data-island.

XMLHTTP operations

See Extensible Markup Language/Hypertext Transfer Protocol (XMLHTTP) operations.


Support Online

Online Support
and Information

* | Microsoft Commerce Server 2000 Web site
* | Microsoft Commerce Server 2000 Solution Sites
* | Commerce Server 2000 ISV Partners Web site
* | Microsoft Product Support Services Web site
* | MSDN Online
* | MSDN Online Library
* | Microsoft COM Web site
* | Microsoft SQL Server Web site
* | Microsoft Accessibility Web site


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.

© 1996-2000 Microsoft Corporation. All rights reserved.

Microsoft, Active Directory, ActiveX, BackOffice, BizTalk, Developer Studio, FrontPage, Hotmail, JScript, MSDN, MS-DOS, MSN Outlook, PivotChart, PivotTable, Verdana, Visual Basic, Visual C++, Webdings, Win32, Windows, Windows Media, 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.


Direct Mail Properties, Connection Strings Tab

This table shows the options and their functions available on the Connection Strings tab of the Direct Mail Properties dialog box.

Use this | To do this
Connection strings in this resource | Select the connection string for Direct Mailer.
Description of selected connection string | Provides a description for the selected connection string.
Value of selected connection string | Provides a value for the selected connection string.


Direct Mail Properties, Properties Tab

This table shows the options and their functions available on the Properties tab of the Direct Mail Properties dialog box.

Use this | To do this
Properties | Select the property name.
Selected Property Value | Enter the values of the selected property.
Description | Provides a description of the selected property.